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:

  1. Go to the Integrations & API page.
  2. 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:

  1. 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.
  2. After successful authentication, the response will contain the access_token.
  3. 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.

These are sample requests to authenticate using an email and API password:

The full JavaScript sample can be downloaded here. 

function signIn(email, apiPassword) {
  var loginData = {
    grant_type: 'password',
    username: email,
    password: apiPassword
  };
  $.ajax({
    type: 'POST',
    url: 'https://staging.testdome.com/api/token',
    data: loginData
  }).done(function (data) {
    // Cache the access token in session storage.
    sessionStorage.setItem("TestDomeApiAccessToken", data.access_token);
  }).fail(showError);
}

This is a sample response you may receive if the authentication succeeds: 

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

Request the API

You now have everything ready to make your first action using the TestDome API.
Below is a sample that shows how to get all tests from an account:

These are sample requests to authenticate using an email and API password:

The full JavaScript sample can be downloaded here. 

function getTests(token) {
  var headers = {};
  headers.Authorization = 'Bearer ' + token;

  $.ajax({
    type: 'GET',
    url: 'https://staging.testdome.com/api/v2/tests',
    headers: headers
  }).done(function (data) {
    // Here you have access to the tests.
    displayTests(data);
  }).fail(showError);
}

To learn more about the response details, check the endpoints documentation (OpenAPI documentation).

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