TestDome API

Get started

The TestDome API allows apps to interact directly with the TestDome platform.
Some typical use cases include the following:

Automatically invite candidates to a test (e.g., directly from the company HR tool).
Automatically pull candidate's reports as soon as they finish a test.

The TestDome API is based on REST.

Guides

Enable access

Learn how to enable access to the TestDome API from the platform.

Authentication

Learn how to authenticate your requests to act on behalf of your user account.

Request the API

Check a sample request that shows how to fetch tests from your account.

Pricing

Check the pricing and limitations to use the TestDome API.

Services

View the OpenAPI docs and get started with webhooks.

API versions

Learn when the API version changes and what you need to do.

Enable access

Before you make your first API call, you need an API password.

To enable API access:

Go to the Integrations & API page.
Under the API section, click "Generate Password".

Authentication

Your app will need to contact TestDome services on your behalf.
Authentication via OAuth2 allows your app to operate on behalf of your account.

These are the steps for OAuth2 authentication:

Send a POST request to /api/token that contains:
- The email you use to login to TestDome.
- The API password that you generated in the Enable access step.
After successful authentication, the response will contain the access_token.
Use this token as part of the authorization header in each of your subsequent API calls.
- This token will be valid for 30 minutes, after which you'll need to request a new token.

The code snippets below show how to authenticate using an email and API password:

The full JavaScript sample can be downloaded here.

const body = {
  username: 'your@email.com',
  password: 'your-password',
  grant_type: 'password'
};

const response = await fetch('https://staging.testdome.com/api/token', {
  method: 'POST',
  body: new URLSearchParams(body),
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded'
  }
});

const data = await response.json();

// This is the access token to be used in the future requests.
const access_token = data.access_token;

If the authentication succeeds, the status code will be 200 OK with this response:

{
  "token_type": "Bearer",
  "access_token": "{{ token }}",
  "expires_in": 1800,
  "userName": "{{ email }}"
}

If the authentication fails, expect 400 Bad Request with this response:

{
  "error": "invalid_grant",
  "error_description": "The user name or password is incorrect."
}

Use the status code and response bodies to determine what to do next in your application.

Request the API

You now have everything ready to make your first action using the TestDome API. The next sections go into detail about:

Collection Requests
Collection Responses
Selection and Expansion
Error Handling
Sample Projects

Collection Requests

Whenever querying collections, use the following optional query parameters for pagination:

$skip: The number of items to skip (default is 0).
$top: The number of items to retrieve (default is 100, must be between 1 and 100).

The following code snippet, without parameters, gets the first page of tests:

const access_token = 'your-access-token';

const response = await fetch('https://staging.testdome.com/api/v3/tests', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${access_token}`
  }
});

// Refer to `TestModel` in the API docs for details.
const data = await response.json();

Collection Responses

If the request is successful, you'll get a response like this:

{
  "skip": 0,
  "top": 10,
  "totalCount": 125,
  "hasMoreItems": true,
  "value": [
    {
      "id": 10,
      "name": "Back-end C# Developer",
      "...": "..."
    }
  ],
  "_links": {
    "next": {
      "href": "/v3/tests?$skip=10&$top=10"
    }
  }
}

Whenever you're querying collections, you'll get responses with these properties:

Collection property: value holds all the items.
Pagination properties:
- skip: The number of items skipped.
- top: The number of items available at value.
- totalCount: The total number of items available.
- hasMoreItems: Whether there are more items to retrieve in the next pages.
Metadata property: _links holds the links to the next page, if available.

It's recommended to check the documentation page if you're sure what to expect.

Selection and Expansion

Whenever you query objects and collections, you can use the following query parameters to control the response:

$expand: A comma-separated list of properties to expand (in case they're not included in the response by default).
$select: A comma-separated list of properties to receive in the response.

With these parameters, you should be able to fine-tune the response to your needs.

Error Handling

Whenever something goes wrong, the API will return an error response similar to this:

{
  "code": "malformedValue",
  "message": "$top(101) is not valid. $top must be a value between 0 and 100",
  "target": "$top",
  "details": []
}

Use the properties to determine what to do next automatically or log the error, for example.

Sample Projects

Download sample projects showing other operations (like list and invite candidates):

If you'd like to get examples for other languages, contact us at support@testdome.com.

Pricing

Only the invitation of candidates incurs a charge. The prices for inviting candidates over the API are the same as for inviting candidates over the TestDome website.

Visit the Pricing page for more information.

Services

To find out more about the services available, go to the OpenAPI documentation page.

To find out more about how you can react to candidate changes, go to the webhooks documentation page.

API versions

TestDome uses a major-only versioning approach (e.g. v3, v4, etc.). A new version will only be introduced if a breaking change is needed.

Breaking changes are changes that can break an existing integration.

Please be aware that we do not consider added functionality as a breaking change, and we will not update the API version when doing things such as:

Adding new endpoints.
Adding new optional query parameters.
Adding new optional body parameters, for both requests and responses.
Adding new error codes.
- If your client does not recognize a new error code, you should keep checking the codes of inner errors until you find the one you can recognize.
Changing error messages.
- We consider error messages to be additional information for developers, not for the application itself. A changed message should not break your error handling.
Changing URLs within response fields.
- We consider such URLs, like a report URL in a candidate response model, dynamic and advise against relying on the structure of such URLs.

You can find the TestDome API changelog and subscribe to changes here.

Not exactly what you're looking for?

Webhooks

Screening Features

Interview Features