Get Started

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

  • Automated inviting of candidates to a test (e.g., directly from the company HR tool)
  • Automated pulling of candidate reports as soon as they finish a test

The TestDome API is made around several RESTful web services.

API versions

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

  • Adding new endpoints
  • Adding new query parameters
  • Adding new 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 a developer, not for the application itself. A changed message should not break your error handling)

Call your first service

Enable access to TestDome API

Before you make your first API call, an API password needs to be generated.

To enable API access, go to your account settings and, under the API section, click "Generate password".

Set up OAuth2 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 that contains the email used for login to your TestDome account and the API password that you received in the previous step to https://testdome/api/token.
  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 time you'll need to request a new token.

The example code below demonstrates this part.

The full JavaScript sample can be downloaded here.

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

The full C# sample can be downloaded here.

static HttpClient Authorize(string email, string apiPassword)
    // Create HttpClient.
    HttpClient client = new HttpClient()
        BaseAddress = new Uri("")
    client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
    // Get token.
    FormUrlEncodedContent content = new FormUrlEncodedContent(new[]
        new KeyValuePair<string, string>("grant_type", "password"),
        new KeyValuePair<string, string>("username", email),
        new KeyValuePair<string, string>("password", apiPassword)
    HttpResponseMessage response = client.PostAsync("token", content).Result;
    string result = response.Content.ReadAsStringAsync().Result;
    string accessToken = JObject.Parse(result)["access_token"].ToString();
    // Set authorization header.
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
    return client;

Call the service

You now have everything ready to make your first action using the TestDome API. You first need to call the right service with the right arguments. Below is a sample that shows how to get all tests from the account.

The full JavaScript sample can be downloaded here.

function getTests() {
  var token = sessionStorage.getItem("TestDomeApiAccessToken");
  var headers = {};
  headers.Authorization = 'Bearer ' + token;
    type: 'GET',
    url: '',
    headers: headers
  }).done(function (data) {

The full C# sample can be downloaded csharp.

static IEnumerable<Test> GetTests(HttpClient client)
    HttpResponseMessage response = client.GetAsync("v2/tests").Result;
    return response.Content.ReadAsAsync<IEnumerable<Test>>().Result;


Only the inviting of candidates incurs a charge. The prices for inviting candidates over the API are the same as for inviting candidates over the TestDome website. You can find prices here.


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


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