Home Pricing Login
Start Free Trial
By using our site you are agreeing that we can use cookies in accordance with our Cookie Policy.
Pricing Start Free Trial

Codility API documentation

Let's build a fantastic integration with your system

Contents

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

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. Events 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

Saved email templates

All email templates for the authenticated account are 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 email templates

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

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": "
Hi [FIRST_NAME] [LAST_NAME],
Please use [PRIVATE_TEST_LINK] to access your test.
[COMPANY_NAME]
"
      }' \
  https://codility.com/api/email-templates/default/

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

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

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/apisessions/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 to 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

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 place-holder.
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 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 \
  -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"
  }

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/
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"
  }

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>/",
      "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, 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 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"
        ]
        "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

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 tests 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