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

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

Account

Credits

You can retrieve the current amount of available credits by accessing the https://codility.com/api/account/credit-level/ endpoint.

Example Request:

  curl \
  -H "Authorization: Bearer your_api_token" \
  -X GET https://codility.com/api/account/credit-level/

Example Response:

  {
    "credits_available": 30,
    "level": "ok"
  }

credits_available represents the number of available credits
level a text credits indicator dependent on account settings. Possible values are: "ok" | "warning" | "empty"
message additional message dependent on credits level

User logins

History of account users logins is available under https://codility.com/api/account/user-logins/ endpoint.

Example Request:

  curl \
  -H "Authorization: Bearer your_api_token" \
  -X GET https://codility.com/api/account//user-logins/?page=1

Example Response:

  {
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
      {
        "timestamp": "2019-01-02 00:00:00",
        "ip": "127.0.0.1",
        "user": {
          "first_name": "Jan",
          "last_name": "Kowalski",
          "email": "kowalski@kodility.com"
        }
      },
      {
        "timestamp": "2019-01-01 00:00:00",
        "ip": "127.0.0.1",
        "user": {
          "first_name": "Jan",
          "last_name": "Kowalski",
          "email": "kowalski@kodility.com"
        }
      }
    ]
  }

count represents the total number of results
next is a link to the next page
prev is a link to the previous page
timestamp login event timestamp. results entries are ordered in descending order based on this value
ip the IP address from which the user logged in

Email templates

Saved email templates

All email templates for the authenticated account are available under https://codility.com/api/email-templates/saved/

Example Request:

  curl \
  -H "Authorization: Bearer your_api_token" \
  -X GET https://codility.com/api/email-templates/saved/

Example Response:

  [
    {
      "name": "test_template",
      "reply_to": "test@codility.com",
      "subject": "Email template test",
      "content": "Hello!"
    }
  ]

name contains the name of the template
reply_to is the email to which mails generated from this template will be sent
subject is the email subject template
content is the email content template

Default email template

The default email template for the authenticated account is available under https://codility.com/api/email-templates/default/

Example Request:

  curl \
  -H "Authorization: Bearer your_api_token" \
  -X GET https://codility.com/api/email-templates/default/

Example Response:

  {
    "reply_to": "test@codility.com",
    "subject": "Email template test",
    "content": "Hello!"
  }

reply_to is the email to which mails generated from this template will be sent
subject is the email subject template
content is the email content template

Create new email template

You can add a new email template with https://codility.com/api/email-templates/create/ endpoint.

Example Request:

  curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_token" \
  -X POST \
  -d '{
        "name": "new_test_template",
        "reply_to": [
          "test1@example.com",
          "test2@example.com"
        ],
        "subject": "[COMPANY_NAME] invites you to a test at Codility",
        "content": "<p>Hi <b>[FIRST_NAME] [LAST_NAME]</b>,</p><p>Please use [PRIVATE_TEST_LINK] to access your test.<p><i>[COMPANY_NAME]</i></p>"
      }' \
  https://codility.com/api/email-templates/create/

Example Response:

  "ok"

Sessions

List all sessions

You can list all sessions with https://codility.com/api/sessions/ endpoint.

Example Request:

  curl \
  -H "Authorization: Bearer your_api_token" \
  -X GET https://codility.com/api/sessions/

Example Response:

  {
    "count": 30,
    "next": null,
    "previous": null,
    "results": [
      {
          "url": "https://codility.com/api/sessions/3T6G76-Y23/?format=json",
          "id": "3T6G76-Y23",
          "candidate": null,
          "first_name": "Onufry",
          "last_name": "Niewiadomski",
          "email": "nie.onu@o2.com",
          "create_date": "2019-04-24T14:00:00Z",
          "start_date": "2019-04-24T14:45:00Z",
          "campaign_url": "https://codility.com/api/tests/122537/?format=json",
          "similarity": {
            "text": "acknowledged",
            "icon": "https://codility.com/static/nux-img/sim-status-confirmed.png
            "embed_url": "https://codility.com/api/sessions/3T6G76-Y23/embed_similarity/"
          }
      },
      {
          "url": "https://codility.com/api/sessions/3T6G86-Y23/?format=json",
          "id": "3T6G86-Y23",
          "candidate": "my_candidate_123",
          "first_name": "Konstanty",
          "last_name": "Pasek",
          "email": "pa.ko@tlen.com",
          "create_date": "2019-04-24T14:00:00Z",
          "start_date": null,
          "campaign_url": "https://codility.com/api/tests/122537/?format=json",
          "similarity": null
      },
      ...
    ]
  }

Similarity checks are only available for coding tasks (excluding SQL tasks).

count represents the total number of results
next is a link to the next page
prev is a link to the previous page
url is the link to the individual session data page
id is the session id
candidate is the custom id provided when inviting a candidate to a test
first_name candidates first name
last_name candidates last name
email candidates email
create_date the date and time on which the session was created
start_date the date and time on which the session was started
campaign_url link to the test from which the session was created
similarity contains information on the similarity check results
text short information about similarity check status
icon icon matching the short information
embed_url url under which you can retrieve a temporary access link to the similarity report

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 "Authorization: Bearer your_api_token" \
  https://codility.com/api/sessions/KKUFDG-5V5/

Example Response:

  {
    "url": "https://codility.com/api/sessions/KKUFDG-5V5/",
    "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/37087736411/",
    "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/KKUFDG-5V5/",
    "pdf_report_url": "https://codility.com/api/sessions/KKUFDG-5V5/pdf/",
    "feedback_link": null,
    "cancel_url": "https://codility.com/api/sessions/KKUFDG-5V5/cancel/",
    "start_codelive_url": null,
    "test_link": "https://app.codility.com/test/KKUFDG-5V5",
    "candidate_data": {
      "field_of_study": null,
      "school": null,
      "academic_degree": null,
      "programming_experience": null,
      "profile_url": null,
      "additional_data": {}
    }
  }

url is the link to the individual session data page
candidate is the custom id provided when inviting a candidate to a test
first_name candidates first name
last_name candidates last name
email candidates email
create_date the date and time on which the session was created
start_date the date and time on which the session was started
campaign_url link to the test from which the session was created
similarity contains information on the similarity check results. same as in the endpoint described in List all sessions
evaluation contains evaluation details for all the tasks in the given session
tasks list of all the tasks in the session and their results
task_name name of the task
result candidates score for the task
max_result maximal score for the task
prg_lang programming language in which the solution was submitted
name (deprecated) name of the task
report_link url to session report
pdf_report_url API endpoint to download the full session report
feedback_link link to candidates feedback on the test
cancel_url a link that can be used to cancel this session. If it is impossible to cancel the session (i.e. it was already completed) the value of this field will be null
start_codelive_url (only for codelive sessions) a link allowing the interviewer to start the codelive session
test_link invitation link which will be sent to the candidate via e-mail
candidate_data contains candidate answers to standard pre-test questions

If the particular session is a codelive session, an additional field codelive will be present in the response.
Inside following data will be found:
candidate_start_date date and time at which the candidate joined the session
last_activity_date date and time of candidate last activity(this time is updated every 3 minutes)
access_code code required to join the session as an interviewer, when joining via the test link
Here is a sample codelive section:
"codelive": { "candidate_start_date":2019-07-08T09:10:15.137, "last_activity_date":"2019-07-08T09:19:15.137", "access_code":"343434" }

E-mail candidates

You can send (or resend) email to a candidate by using https://codility.com/api/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 placeholder.

Example Response:

  {
    "result":"OK"
  }

Cancel sessions

You can cancel a session using the https://codility.com/api/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

Embed candidate report

You can retrieve a temporary link to the candidate report. It can be embedded inside your webapp. To retrieve the link use the https://codility.com/api/sessions/<session_id>/embed_report endpoint. Please, note that the retrieved link has an expiration date.

Example Request:

  curl \
  -H "Authorization: Bearer your_api_token" \
  -X POST \
  https://codility.com/api/sessions/<session_id>/embed_report/

Example Response:

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

url a temporary link to the candidate report
valid_until an expiration date of the link

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 https://codility.com/api/sessions/<test-id>/pdf/ endpoint.

Example Request:

  curl \
  -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.

Get similarity check results

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

Example Request:

  curl \
  -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"
  }

url a temporary link to the tests similarity report
valid_until an expiration date of the link

Tests

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 "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>/",
      "id": 123,
      "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/<test-id>/invite/",
      "sessions_url": "https://codility.com/api/tests/<test-id>/sessions/"
    }]
  }

count represents the total number of results
next is a link to the next page
prev is a link to the previous page
The structure of an entry in results is a subset of the response showed in Test details that includes the following fields: url, id, name, create_date, is_archived, public_test_link, invite_url, sessions_url

Test details

You can check the tests details with the https://codility.com/api/tests/<test_id>/ endpoint.

Example Request:

  curl \
  -H "Authorization: Bearer your_api_token" \
  -X GET https://codility.com/api/tests/<test_id>/

Example Response:

  {
    "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/<test-id>/invite/",
    "sessions_url": "https://codility.com/api/tests/<test-id>/sessions/"
  }

url is the same link as the one used to retrieve the response
name is name of the test
create_date the date and time on which the test was created
is_archived a boolean flag showing whether the given camapign is archived
public_test_link the public test link if the test is a public test. null in case the test is not public
invite_url url to invite candidates for this test. Detailed description of this endpoint can be found in section Add candidates
sessions_url url to browse all the sessions created from this test. Detailed description of this endpoint can be found in section List test sessions

Add candidates

You can create a test for the candidate. Send a POST request to https://codility.com/api/tests/<test_id>/invite/ endpoint in order to generate private test links that you can hand out. You can also specify e-mail addresses that should receive e-mail reports after candidates complete their tests. Specifying the recipients is optional and defaults to whatever is set up in the given Codility test. Calls to this endpoint will not send any emails to the candidates.

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"
        ]
        "event_callbacks": [
          {
            "event": "result",
            "url": "http://example.com/handle_result"
          }
        ]
      }' \
  https://codility.com/api/tests/<test_id>/invite/

Each entry in the candidates list can have the following fields:

id (required) identifier used to identify the candidate taking the test. It does not have to be unique
redirect_url URL where to redirect (HTTP 302) the candidate after the evaluation is completed
first_name candidates first name
last_name candidates last name
email candidates email
additional_data any data in JSON format you want to store with candidate

rpt_emails will specify emails that should receive e-mail reports. If not specified will default to the tests settings

Data passed in event_callbacks can be used to specify endpoints to which Codility will send HTTP POST requests when the specified event occurs. The data has to follow the format:

event (required) one of: "result" | "similarity". Depending on this value the HTTP request will be made either when the test result is available (result), or when similarity status of the session is available (similarity)
url (required) URL to which the HTTP POST request will be made with session data

Event data

When the callback conditions are met a POST request will be made to the specified endpoint. These requests will have the following body:

      {
        "event": "result",
        "session": {
          ...
        }
      }

The session format is the same as the one specified in the Browse Candidate Session Data section

Example Response:

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

List test sessions

You can list all sessions created from a test by using https://codility.com/api/tests/<test_id>/sessions/ endpoint.

Example Request:

  curl \
  -H "Authorization: Bearer your_api_token" \
  -X GET https://codility.com/api/tests/<test_id>/sessions/

Example Response:

  {
    "count": 1,
    "next": null,
    "previous": null,
    "results": [

        {
            "url": "https://codility.com/api/sessions/<session_id>/",
            "id": "<session_id>",
            "candidate": null,
            "first_name": "Johan",
            "last_name": "Strauss",
            "email": "j.str@no.name.com",
            "create_date": "2014-01-21T16:15:01Z",
            "start_date": null,
            "campaign_url": "https://codility.com/api/tests/<test_id>/",
            "similarity": null
        }
    ]
  }

url is the link to the individual session url. More information on the detailed session information Browse Candidate Session Data
id session id
candidate is the custom id provided when inviting a candidate to a test
first_name candidates first name
last_name candidates last name
email candidates email
create_date the date and time on which the session was created
start_date the date and time on which the session was started
campaign_url link to the test from which the session was created
similarity contains information on the similarity check results. Same as in the endpoint described in List all sessions

Codelive

Create Whiteboard

You can create codelive whiteboard session. Send a POST request to https://codility.com/api/codelive/create_whiteboard/ endpoint in order to generate private codelive links that you can hand out.

Example Request:

  curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_token" \
  -X POST \
  -d '{
        "room_name": "example name"
      }' \
  https://codility.com/api/codelive/create_whiteboard/

room_name name that will be displayed in the codility interface

Example Response:

  {
    "test_url": "https://app.codility.com/test/CL-S4SWMD-QY6/",
    "access_code":"343434"
  }

test_url represents url to private codelive session access_code code required to join the session as an interviewer, when joining via the test link

Codility API documentation

Let's build a fantastic integration with your system

Contents

Overview

Contents

Technical facts

A note before you move forward

Auth

Token-based auth

OAuth2

Flows

Account

Credits

Example Request:

Example Response:

User logins

Example Request:

Example Response:

Email templates

Saved email templates

Example Request:

Example Response:

Default email template

Example Request:

Example Response:

Create new email template

Example Request:

Example Response:

Sessions

List all sessions

Example Request:

Example Response:

Browse candidate session data

Example Request:

Example Response:

E-mail candidates

Example Request:

Example Response:

Cancel sessions

Example Request:

Example Response:

Embed candidate report

Example Request:

Example Response:

Get the PDF report for a test

Example Request:

Get similarity check results

Example Request:

Example Response:

Tests

Browse tests

Example Request:

Example Response:

Test details

Example Request:

Example Response:

Add candidates

Example Request:

Example Response:

List test sessions

Example Request:

Example Response:

Codelive

Create Whiteboard

Example Request:

Example Response: