The Devskiller REST API lets you interact with Devskiller platform. You can use the API especially for:

  • searching for an exam

  • adding a candidate

  • getting candidates list

  • getting candidate details and results

Overview

In this section you can find general information about Devskiller REST API

API Endpoint

All API URLs are relative to https://api.devskiller.com/. For example, to get list of candidates you should call /candidates endpoint at https://api.devskiller.com/candidates

API Key

Each request must contain an API Key passed as HTTP header: X-Api-Key. To get your personal API key, please contact us at: support@devskiller.com

HTTP verbs

RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

HTTP status codes

RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

200 OK

The request completed successfully

201 Created

The resource has been created successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information

412 Precondition failed

The request data refers to some invalid data

417 Expectation failed

The request cannot be completed for current application state

404 Not Found

The requested resource did not exist

Errors

Whenever an error response (status code >= 400) is returned, the body will contain a JSON object that describes the problem. The error object has the following structure:

Path Type Description

code

Number

Error code

errorId

String

Unique error id, you can use it when contacting with us

details

String

Error description

For example, a request that attempts to apply a non-existent tag to a note will produce a 400 Bad Request response:

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 126

{
  "code" : 400,
  "errorId" : "e4f70f94-b940-4078-b83b-15c56925b7c4",
  "details" : "Errors: email: incorrect mail, Email"
}

Candidate operations

The Candidates resources is used to create and list candidates

Listing candidates

GET /candidates

A GET request will list all candidates.

Query parameters

Parameter Description

query

(Optional) Search by name,email or token

status

(Optional) Filter candidates by status. Add multiple status parameters to search for several statuses.

tags

(Optional) Filter candidates by tags. Add multiple tags parameters to search for several tags.

count

(Optional) Maximum number of candidates to get. Default: 10, Max: 100

page

(Optional) Number of the page to fetch, starting with 1. Default: 1

Response structure

Path Type Description

pageNumber

Number

Number of the current page

pageSize

Number

Maximum number of elements for a page

totalElements

Number

Total number of candidates matching criteria

totalPages

Number

Total number of pages matching criteria

items

Array

An array with candidates

Example request

$ curl 'https://api.devskiller.com/candidates?query=John&count=10&page=1&status=TOKEN_SENT&status=ASSESSMENT_READY&tags=Tag1&tags=Tag2' -i -H 'X-Api-Key: TEST-API-KEY' -H 'Accept: application/json'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 422

{
  "items" : [ {
    "id" : "CANDIDATE-UUID-1234",
    "firstName" : "John",
    "lastName" : "Smith",
    "email" : "test@email.com",
    "examId" : "UUID-FOR-123",
    "status" : "TOKEN_SENT",
    "scoredPoints" : null,
    "maxPoints" : 65,
    "examUrl" : "http://exam.url/exam.html?TEST-TOKEN",
    "tags" : [ "Tag1", "Tag2" ]
  } ],
  "totalElements" : 1,
  "totalPages" : 1,
  "pageSize" : 10,
  "pageNumber" : 1
}

Creating a candidate

POST /candidates

A POST request is used to create a candidate. After successfully creating a candidate, an email with the invitation will be send to the candidate.

Request structure

Path Type Description

email

String

(Required) The candidate’s email address

firstName

String

(Required) The candidate’s first name

lastName

String

(Required) The candidate’s last name

examId

String

(Required) The exam’s id that the candidate has been asked to solve

tags

Array

(Optional) The candidate’s tags (array of strings)

communicationDisabled

Boolean

(Optional) Should the outbound communication to the candidate be disabled. Default: "false"

Example request

$ curl 'https://api.devskiller.com/candidates' -i -X POST -H 'X-Api-Key: TEST-API-KEY' -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
    "communicationDisabled": false,
    "firstName": "John",
    "lastName": "Smith",
    "examId": "UUID-FOR-123",
    "tags": [
        "Tag1",
        "Tag2"
    ],
    "email": "test@email.com"
}'
POST /candidates HTTP/1.1
X-Api-Key: TEST-API-KEY
Content-Type: application/json
Accept: application/json
Host: api.devskiller.com
Content-Length: 201

{
    "communicationDisabled": false,
    "firstName": "John",
    "lastName": "Smith",
    "examId": "UUID-FOR-123",
    "tags": [
        "Tag1",
        "Tag2"
    ],
    "email": "test@email.com"
}

Example response

HTTP/1.1 201 Created
Location: https://api.devskiller.com/candidates/CANDIDATE-UUID-1234
Content-Type: application/json;charset=UTF-8
Content-Length: 298

{
  "id" : "CANDIDATE-UUID-1234",
  "firstName" : "John",
  "lastName" : "Smith",
  "email" : "test@email.com",
  "examId" : "UUID-FOR-123",
  "status" : "TOKEN_SENT",
  "scoredPoints" : null,
  "maxPoints" : 65,
  "examUrl" : "http://exam.url/exam.html?TEST-TOKEN",
  "tags" : [ "Tag1", "Tag2" ]
}

Possible response codes

Status code Usage

200 OK

The request completed successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information

412 Precondition failed

Requested exam cannot be used (it doesn’t exist or is in wrong state)

417 Expectation failed

There are insufficient credits to complete the request

Details of a candidate

GET /candidates/{id}

A GET request will retrieve the details of a candidate

Response structure

Path Type Description

id

String

The candidate’s id

status

String

The candidate’s status. Possible values: TOKEN_SENT, TOKEN_EXPIRED, TEST_STARTED, TEST_FINISHED, AUTO_ASSESSMENT_READY, IN_ASSESSMENT, ASSESSMENT_READY, ACCEPTED, REJECTED

email

String

The candidate’s email address

firstName

String

The candidate’s first name

lastName

String

The candidate’s last name

scoredPoints

Null

The candidate’s score. Null if candidate has not been assessed yet.

maxPoints

Number

The maximum number of points, that candidate might get from assigned exam.

examUrl

String

The url to the test for candidate.

examId

String

The exam’s id that the candidate has been asked to solve

tags

Array

The candidate’s tags (array of strings)

Example request

$ curl 'https://api.devskiller.com/candidates/CANDIDATE-UUID-1234' -i -H 'X-Api-Key: TEST-API-KEY' -H 'Accept: application/json'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 298

{
  "id" : "CANDIDATE-UUID-1234",
  "firstName" : "John",
  "lastName" : "Smith",
  "email" : "test@email.com",
  "examId" : "UUID-FOR-123",
  "status" : "TOKEN_SENT",
  "scoredPoints" : null,
  "maxPoints" : 65,
  "examUrl" : "http://exam.url/exam.html?TEST-TOKEN",
  "tags" : [ "Tag1", "Tag2" ]
}

Results for a candidate

GET /candidates/{id}/results

A GET request will retrieve the results for a candidate

Response structure

Path Type Description

maxPoints

Number

Maximum points that candidate could get for the test

scoredPoints

Number

The candidate’s score

examDurationInMinutes

Number

How long did it take to complete the test

examTimeLimitInMinutes

Number

Exam’s time limit

askedForContractData

Boolean

True if candidate has been asked for contract data

financialExpectations

Number

Financial expectations, available if candidate has been asked for contract data.

noticePeriod

String

Notice period, available if candidate has been asked for contract data

note

String

Optional note about candidate, made by assessor

replySent

Boolean

True if a feedback mail has been sent to the candidate

reportUrl

String

The candidate’s report URL.

pdfReportUrl

Null

The candidate’s report URL (PDF download).

skills

Array

The candidate’s skills results.

skills[].name

String

The skill’s name.

skills[].scoredPoints

Number

The skil’s scored points.

skills[].maxPoints

Number

The skill’s max points.

Example request

$ curl 'https://api.devskiller.com/candidates/CANDIDATE-UUID-5678/results' -i -H 'X-Api-Key: TEST-API-KEY' -H 'Accept: application/json'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 561

{
  "reportUrl" : "https://report.devskiller.com/candidate-report.html?REPORT-UUID/REPORT-UUID2",
  "pdfReportUrl" : null,
  "scoredPoints" : 45,
  "maxPoints" : 65,
  "skills" : [ {
    "name" : "Skill1",
    "scoredPoints" : 10,
    "maxPoints" : 20
  }, {
    "name" : "Skill2",
    "scoredPoints" : 5,
    "maxPoints" : 14
  } ],
  "note" : "Some note about candidate",
  "askedForContractData" : true,
  "financialExpectations" : 5000,
  "noticePeriod" : "one month",
  "replySent" : false,
  "examDurationInMinutes" : 44,
  "examTimeLimitInMinutes" : 60
}

Exam operations

GET /exams

The Exams resources is used to list exams

Listing exams

A GET request will list all candidates.

Query parameters

Parameter Description

count

(Optional) Maximum number of exams to get. Default: 10, Max: 100

page

(Optional) Number of the page to fetch, starting with 1. Default: 1

Response structure

Path Type Description

pageNumber

Number

Number of the current page

pageSize

Number

Maximum number of elements for a page

totalElements

Number

Total number of exams matching criteria

totalPages

Number

Total number of pages matching criteria

items

Array

An array of exams

Example request

$ curl 'https://api.devskiller.com/exams?count=10&page=1' -i -H 'X-Api-Key: TEST-API-KEY' -H 'Accept: application/json'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 558

{
  "items" : [ {
    "id" : "UUID-FOR-123",
    "name" : "Test exam 123",
    "durationInMinutes" : 100,
    "automaticAssessmentPossible" : true,
    "numberOfPages" : 2,
    "numberOfTasks" : 4,
    "skillTags" : [ "Java", "Hibernate" ]
  }, {
    "id" : "UUID-FOR-456",
    "name" : "Test exam 456",
    "durationInMinutes" : 100,
    "automaticAssessmentPossible" : true,
    "numberOfPages" : 2,
    "numberOfTasks" : 4,
    "skillTags" : [ "Java", "Hibernate" ]
  } ],
  "totalElements" : 2,
  "totalPages" : 1,
  "pageSize" : 10,
  "pageNumber" : 1
}

Details of an exam

GET /exams/{id}

A GET request will retrieve the details of an exam

Response structure

Path Type Description

id

String

The exam’s id

name

String

The exam’s name

durationInMinutes

Number

The exam’s duration in minutes

numberOfPages

Number

The exam’s number of pages

numberOfTasks

Number

The exam’s number of tasks

skillTags

Array

Array of skills tested with this exam

automaticAssessmentPossible

Boolean

Is automatic assessment of candidate’s answers is possible? If false, some of candidate’s answers needs manual assessment

Example request

$ curl 'https://api.devskiller.com/exams/UUID-FOR-123' -i -H 'X-Api-Key: TEST-API-KEY' -H 'Accept: application/json'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 211

{
  "id" : "UUID-FOR-123",
  "name" : "Test exam 123",
  "durationInMinutes" : 100,
  "automaticAssessmentPossible" : true,
  "numberOfPages" : 2,
  "numberOfTasks" : 4,
  "skillTags" : [ "Java", "Hibernate" ]
}

Webhooks

Webhooks are inverted API endpoints which allows you to receive push notifications from Devskiller.

To receive Devskiller’s push notifications you have to register your webhook endpoint address in the administration panel. You will also find there the webhook secret with is used to sign all requests sent by Devskiller.

Receive push notification

A POST request will push events to your endpoint.

Request structure

Path Type Description

[]

Object

An array of events

[].candidateId

String

The candidate’s id

[].event

String

Event type. Possible values: EXAM_FINISHED

Example request

$ curl 'https://api.yourdomain.com/devskillerWebhooks' -i -X POST -H 'X-Hook-Secret: TEST-SECRET' -H 'Content-Type: application/json' -d '[
    {
        "candidateId": "CANDIDATE-UUID-1234",
        "event": "EXAM_FINISHED"
    }
]'
POST /devskillerWebhooks HTTP/1.1
X-Hook-Secret: TEST-SECRET
Content-Type: application/json
Host: api.yourdomain.com
Content-Length: 94

[
    {
        "candidateId": "CANDIDATE-UUID-1234",
        "event": "EXAM_FINISHED"
    }
]

Example response

HTTP/1.1 202 Accepted
If your endpoint responded 4xx or 5xx Devskiller will retry the request with a given schedule:
  1. after 3 seconds

  2. after 15 seconds

  3. after 1 minute

  4. after 5 minutes

  5. after 30 minutes

  6. after 150 minutes