Codility API documentation

Overview

The API is a tool that developers can use to automate activities related to Codility. You can use it to fit Codility seamlessly into your recruitment process by building integrations with any kind of HR tools you use.

Some examples of what you can build are:

• send Codility test invitations and receive test results in your favourite Applicant Tracking System
• receive alerts when someone finishes a test
• build custom reports about your recruitment that update in real time

Contents

Technical facts

The API is published under https://codility.com/api/ and is available only over HTTPS. It follows standard HTTP conventions and relies on JSON for data representation.

You can open any API URL in the browser to read its documentation.

The API usage limit is currently 500 requests per user per hour. (If you require a higher limit, please contact us.)

A note before you move forward

The shape of URLs in our recruiter and candidate interfaces is not part of the API promise and we sometimes change them. So its best if you do not rely on extracting information from the URLs, please treat them as black boxes.

However, whenever these URLs change, we make sure to leave a permanent redirect in place so that your saved links keep working.

Auth

Token-based auth

This is the go-to approach for accessing your own account through our API.

First, go to the "Integrations" section in My Account and create an Application. An access token will be generated for you. This access token gives full access to your account, so keep it secret!

Include the access token as a header in all HTTP requests to our API:

Authorization: Bearer <token>

OAuth2

If you'd like to build a Codility integration that will allow other users to connect their own Codility accounts, OAuth2 is the way to go.

The first step is to get a Codility account for the purposes of maintaining the integration (this doesn't have to be an account used for testing candidates). Log in and go to the "Integrations" section in My Account, then create an Application.

We will generate an OAuth2 Client ID and Client Secret pair for you. You can use these to ask your users for permission to access their Codility account data.

Our OAuth2 endpoints are:

• https://codility.com/oauth2/authorize/
• https://codility.com/oauth2/token/

Please contact us at support@codility.com, we look forward to hearing about your project and are happy to help!

Flows

Browse tests

You can browse all your tests by using https://codility.com/api/tests/ endpoint.

Displaying the list of tests to the end-user is helpful when you need to ask the user to select a Codility test that should be issued to candidates. In this case, it's useful to only show the tests that haven't been archived by the user in Codility dashboards: you can filter out archived tests by adding a query parameter is_archived=False.

Example Request:

  curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_token" \
  -X GET \
  https://codility.com/api/tests/?is_archived=False

Example Response:

  {
    "count": 1,
    "next": null,
    "previous": null,
    "results": [{
      "url": "https://codility.com/api/tests/test-id/",
      "name": "Design task for PDF",
      "create_date": "2017-06-27T15:02:15.437",
      "is_archived": false,
      "public_test_link": null,
      "invite_url": "https://codility.com/api/tests/8/invite/",
      "sessions_url": "https://codility.com/api/tests/8/sessions/"
    }]
  }

For the detail of each field, please refer to https://codility.com/api/tests/

Add candidates

You can invite candidates: POST to https://codility.com/api/tests/<test_id>/invite/ to create private test links that you can hand out. You can also specify e-mail addresses that should receive e-mail reports. This is optional and defaults to whatever is set up in the given Codility test.

Example Request:

  curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_token" \
  -X POST \
  -d '{
        "candidates": [{
          "id": "123"
        }],
        "rpt_emails": [
          "raven@example.com",
          "starfire@example.com"
        ]
      }' \
  https://codility.com/api/tests/test_id/invite/

For more details on possible options for fields in request, please refer to: https://codility.com/api/tests/<test_id>/invite/

Example Response:

  {
    "candidates": [{
      "id": "123",
      "test_link": "https://app.codility.com/test/6ZZ5JT-2D3",
      "session_url": "https://codility.com/api/sessions/6ZZ5JT-2D3/"
    }]
  }

Go to register callbacks section to find available extra features.

E-mail candidates

You can send (or resend) email to a candidate by using /sessions/<session-id>/email/ endpoint.

Example Request:

  curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_token" \
  -X POST -d \
    '{
        "subject": "Hello from the other side",
        "content": "[PRIVATE_TEST_LINK]",
        "reply_to": "leen.hash@example.com",
        "cc": ["robert.lewandowski@example.com", "john.doe@example.com"]
    }' \
  https://codility.com/api/sessions/<session-id>/email/

None of the field params are required but notice that if you include "content" in the field params then [PRIVATE_TEST_LINK] is a mandatory place-holder.

Example Response:

  {
    "result":"OK"
  }

Browse Candidate Session Data

You can view candidate data for a particular test session using the following endpoint:
https://codility.com/api/sessions/<session_id>

Example Request:

  curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_token" \
  -X POST \
  https://codility.com/api/sessions/session_id/

Example Response:

  {
    "url": "https://codility.com/api/sessions/session_id/",
    "candidate": null,
    "first_name": "Robert",
    "last_name": "Lewandowski",
    "email": "robert.lewandowski@example.com",
    "create_date": null,
    "start_date": null,
    "campaign_url": "https://codility.com/api/tests/test_id/",
    "similarity": null,
    "evaluation": {
      "tasks": [{
        "task_name": "AbsDistinct",
        "result": null,
        "max_result": 100,
        "prg_lang": null,
        "name": "abs_distinct"
      }],
      "max_result": 100,
      "result": null
    },
    "report_link": "https://app.codility.com/tickets/session_id/",
    "pdf_report_url": "https://codility.com/api/sessions/session_id/pdf/",
    "feedback_link": null,
    "cancel_url": "https://codility.com/api/sessions/session_id/cancel/",
    "start_codelive_url": null,
    "test_link": "https://app.codility.com/test/session_id",
    "candidate_data": {
      "field_of_study": null,
      "school": null,
      "academic_degree": null,
      "programming_experience": null,
      "profile_url": null
    }
  }

Register callbacks

When adding candidates, you can request a callback for the evaluation of the test session. This will instruct Codility to send a HTTP POST request with evaluation details to your endpoint once the test has been taken and the evaluation is complete (or some event happens). The POST contains JSON-encoded evaluation data.

Currently, the following events are supported:

• "result": the result is available for a ticket
• "similarity": a similarity report has been created for a ticket (anti-cheating)

Example invite request with callbacks:

  curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_token" \
  -X POST \
  -d '{
        "candidates": [{
          "id": "123"
        }],
        "event_callbacks": [
          {
            "event": "result" | "similarity",
            "url" : "https://example.com/client_api_endpoint"
          }
        ]
      }' \
  https://codility.com/api/tests/test_id/invite/

Example event callback body:

{
  "event": "result",
  "session": (session_detail object)
}

Cancel sessions

You can cancel a sessoin using the /sessions/<session-id>/cancel/ endpoint.

Example Request:

  curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_token" \
  -X POST https://codility.com/api/sessions/session_id/cancel/

Example Response:

  {
    "result":"OK"
  }

In case the status of the session is evaluating or closed the response status will be 400 bad request

Get similarity check results

Once the candidate completes the test, you can fetch similarity report for a test by calling the /sessions/<test-id>/embed_report/ endpoint.

Example Request:

  curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_token" \
  -X POST https://codility.com/api/sessions/<test-id>/embed_similarity/

Example Response:

  {
    "url":"https://codility.com/similarity/tickets/MTK2AM-KSX/?sat=wf58aRC1",
    "valid_until":"2017-07-05T15:18:59.280"
  }

Get the PDF report for a test

Once the candidate completes the test, you can fetch the url to generate the PDF report for the test by calling the /sessions/<test-id>/pdf/

Example Request:

  curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_token" \
  -X GET https://codility.com/api/sessions/<test-id>/pdf/

For this request you will recieve an http response with MIME type application/pdf for the test specified by <test-id> in path param.

Embed candidate report

You can embed the UI for the candidate report inside your webapp by using https://codility.com/api/sessions/session_id/embed_report endpoint. Candidate report has a lot of data, hence we do not provide an API endpoint for it. But you can use this endpoint to embed the candidate report UI in an iframe.

Example Request:

  curl -s -D - -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_token" \
  -X POST \
  https://codility.com/api/sessions/session_id/embed_report/

Example Response:

  {
    "url": "https://codility.com/tickets/session_id/?sat=AAoWaNQB",
    "valid_until": "2017-07-06T15:11:24.534"
  }