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:
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.)
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.
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>
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:
Please contact us at support@codility.com, we look forward to hearing about your project and are happy to help!
You can retrieve the current amount of available credits by accessing the
https://codility.com/api/account/credit-level/
endpoint.
curl \ -H "Authorization: Bearer your_api_token" \ -X GET https://codility.com/api/account/credit-level/
{ "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
History of account users logins is available under
https://codility.com/api/account/user-logins/
endpoint.
curl \ -H "Authorization: Bearer your_api_token" \ -X GET https://codility.com/api/account//user-logins/?page=1
{ "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
All email templates for the authenticated account are available under
https://codility.com/api/email-templates/saved/
curl \ -H "Authorization: Bearer your_api_token" \ -X GET https://codility.com/api/email-templates/saved/
[ { "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
The default email template for the authenticated account is available under
https://codility.com/api/email-templates/default/
curl \ -H "Authorization: Bearer your_api_token" \ -X GET https://codility.com/api/email-templates/default/
{ "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
You can add a new email template with
https://codility.com/api/email-templates/create/
endpoint.
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/
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
"ok"
You can list all sessions with
https://codility.com/api/sessions/
endpoint.
curl \ -H "Authorization: Bearer your_api_token" \ -X GET https://codility.com/api/sessions/
{ "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
https://codility.com/api/sessions/<session_id>
curl \ -H "Authorization: Bearer your_api_token" \ https://codility.com/api/sessions/KKUFDG-5V5/
{ "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"
}
https://codility.com/api/sessions/<session-id>/email/
endpoint.
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.
{ "result":"OK" }
You can cancel a session using the https://codility.com/api/sessions/<session-id>/cancel/
endpoint.
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer your_api_token" \ -X POST https://codility.com/api/sessions/session_id/cancel/
{ "result":"OK" }
In case the status of the session is evaluating
or closed
the response status will be 400 bad request
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.
curl \ -H "Authorization: Bearer your_api_token" \ -X POST \ https://codility.com/api/sessions/<session_id>/embed_report/
{ "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
https://codility.com/api/sessions/<test-id>/pdf/
endpoint.
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.
https://codility.com/api/sessions/<test-id>/embed_report/
endpoint.
curl \ -H "Authorization: Bearer your_api_token" \ -X POST https://codility.com/api/sessions/<test-id>/embed_similarity/
{ "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
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
.
curl \ -H "Authorization: Bearer your_api_token" \ -X GET https://codility.com/api/tests/?is_archived=False
{ "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 resultsnext
is a link to the next pageprev
is a link to the previous pageresults
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
You can check the tests details with the https://codility.com/api/tests/<test_id>/
endpoint.
curl \ -H "Authorization: Bearer your_api_token" \ -X GET https://codility.com/api/tests/<test_id>/
{ "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 testcreate_date
the date and time on which the test was createdis_archived
a boolean flag showing whether the given camapign is archivedpublic_test_link
the public test link if the test is a public test.
null
in case the test is not publicinvite_url
url to invite candidates for this test.
Detailed description of this endpoint can be found in section
Add candidatessessions_url
url to browse all the sessions created from this test.
Detailed description of this endpoint can be found in section
List test sessions
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.
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 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
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
{ "candidates": [{ "id": "123", "test_link": "https://app.codility.com/test/6ZZ5JT-2D3", "session_url": "https://codility.com/api/sessions/6ZZ5JT-2D3/" }] }
You can list all sessions created from a test by using
https://codility.com/api/tests/<test_id>/sessions/
endpoint.
curl \ -H "Authorization: Bearer your_api_token" \ -X GET https://codility.com/api/tests/<test_id>/sessions/
{ "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 Dataid
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
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.
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
{ "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