NAV Navbar
API Version:   V2 V1
cURL http

Devskiller API Overview

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

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: Devskiller-Api-Key. To get your personal API key, please navigate to the Settings -> Integrations menu in the Devskiller administration panel, and acquire your key in the API Access section.

More details about acquiring the API Key can be found in our help https://help.devskiller.com/devskiller-settings/integrations/how-to-integrate-with-an-api

Content Type

This version of the API is using the HATEOAS approach based on the HAL - Hypertext Application Language standard.

Please ensure that you set Content-Type and Accept headers to the application/vnd.devskiller.v2.hal+json.

Candidates & assessments

The Candidates resources is used manage the candidates.

Candidate object

This is an object representing the candidate.

Sample

{
  "id" : "1024138f-684f-4311-b539-774fd3ef3a9c",
  "firstName" : "John",
  "lastName" : "Smith",
  "email" : "john@smith.com",
  "tags" : [ "Phoenix", "TeamLeader" ],
  "disableCommunication" : false,
  "externalId" : "553c8ceb",
  "status" : "IN_EVALUATION",
  "_embedded" : {
    "assessments" : [ {
      "id" : "90224982-2017-4098-bfc8-48f7b60ec01d",
      "status" : "ASSESSMENT_COMPLETED",
      "creationDate" : "2018-11-23T11:12:13Z",
      "startDate" : "2018-11-23T12:12:13Z",
      "finishDate" : "2018-11-23T13:12:13Z",
      "_links" : {
        "candidateAccess" : {
          "href" : "https://exam.devskiller.com/exam.html?2Y4D-9R2G-6WT7"
        },
        "onlineReport" : {
          "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        },
        "pdfReport" : {
          "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        },
        "candidateUrl" : {
          "href" : "https://app.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/detail/overview"
        },
        "self" : {
          "href" : "https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/assessments/90224982-2017-4098-bfc8-48f7b60ec01d"
        }
      }
    } ]
  },
  "assignedUser" : "d493e6d3-6a6a-4cf2-8990-46366c75064f",
  "assignedTeam" : "dc1087ed-97d5-43bc-ba31-5e8593fe3083",
  "creationDate" : "2018-11-23T11:12:13Z",
  "_links" : {
    "onlineReport" : {
      "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
    },
    "pdfReport" : {
      "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
    },
    "self" : {
      "href" : "https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c"
    }
  }
}
HTTP/1.1 200 OK
Content-Type: application/vnd.devskiller.v2.hal+json;charset=UTF-8

{
  "id" : "1024138f-684f-4311-b539-774fd3ef3a9c",
  "firstName" : "John",
  "lastName" : "Smith",
  "email" : "john@smith.com",
  "tags" : [ "Phoenix", "TeamLeader" ],
  "disableCommunication" : false,
  "externalId" : "553c8ceb",
  "status" : "IN_EVALUATION",
  "_embedded" : {
    "assessments" : [ {
      "id" : "90224982-2017-4098-bfc8-48f7b60ec01d",
      "status" : "ASSESSMENT_COMPLETED",
      "creationDate" : "2018-11-23T11:12:13Z",
      "startDate" : "2018-11-23T12:12:13Z",
      "finishDate" : "2018-11-23T13:12:13Z",
      "_links" : {
        "candidateAccess" : {
          "href" : "https://exam.devskiller.com/exam.html?2Y4D-9R2G-6WT7"
        },
        "onlineReport" : {
          "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        },
        "pdfReport" : {
          "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        },
        "candidateUrl" : {
          "href" : "https://app.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/detail/overview"
        },
        "self" : {
          "href" : "https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/assessments/90224982-2017-4098-bfc8-48f7b60ec01d"
        }
      }
    } ]
  },
  "assignedUser" : "d493e6d3-6a6a-4cf2-8990-46366c75064f",
  "assignedTeam" : "dc1087ed-97d5-43bc-ba31-5e8593fe3083",
  "creationDate" : "2018-11-23T11:12:13Z",
  "_links" : {
    "onlineReport" : {
      "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
    },
    "pdfReport" : {
      "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
    },
    "self" : {
      "href" : "https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c"
    }
  }
}

Attributes

id
Type: String Content: Standard
The candidate's id
externalId
Type: String Content: Standard
The candidate's external id
email
Type: String Content: Standard
The candidate's email address
firstName
Type: String Content: Standard
The candidate's first name
lastName
Type: String Content: Standard
The candidate's last name
status
Type: String Content: Standard
The candidate's status
tags
Type: Array Content: Standard
The candidate's tags (array of strings)
disableCommunication
Type: Boolean Content: Standard
Should the outbound communication to the candidate be disabled
assignedUser
Type: String Content: Standard
Identifier of assigned user. Null if unassigned
assignedTeam
Type: String Content: Standard
Identifier of assigned team. Null if unassigned
creationDate
Type: String Content: Standard
Date when the candidate has been created
_embedded.assessments[]
Type: Array Content: Extended
Collection of assessments: assessment object with standard content
self
Direct link to the candidate
onlineReport
Link to the candidate report page
pdfReport
Link to the candidate PDF report

Creating a candidate

Request

POST /candidates HTTP/1.1
Content-Type: application/vnd.devskiller.v2.hal+json
Devskiller-Api-Key: TEST-API-KEY
Accept: application/vnd.devskiller.v2.hal+json
Host: api.devskiller.com

{
    "email": "john@smith.com",
    "firstName": "John",
    "lastName": "Smith",
    "tags": [
        "Phoenix",
        "TeamLeader"
    ],
    "externalId": "553c8ceb",
    "disableCommunication": false
}
$ curl 'https://api.devskiller.com/candidates' -i -X POST \
    -H 'Content-Type: application/vnd.devskiller.v2.hal+json' \
    -H 'Devskiller-Api-Key: TEST-API-KEY' \
    -H 'Accept: application/vnd.devskiller.v2.hal+json' \
    -d '{
    "email": "john@smith.com",
    "firstName": "John",
    "lastName": "Smith",
    "tags": [
        "Phoenix",
        "TeamLeader"
    ],
    "externalId": "553c8ceb",
    "disableCommunication": false
}'

Response

HTTP/1.1 201 Created
Location: https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c
Content-Type: application/vnd.devskiller.v2.hal+json;charset=UTF-8

{
  "id" : "1024138f-684f-4311-b539-774fd3ef3a9c",
  "firstName" : "John",
  "lastName" : "Smith",
  "email" : "john@smith.com",
  "tags" : [ "Phoenix", "TeamLeader" ],
  "disableCommunication" : false,
  "externalId" : "553c8ceb",
  "status" : "NEW",
  "assignedUser" : "d493e6d3-6a6a-4cf2-8990-46366c75064f",
  "assignedTeam" : "dc1087ed-97d5-43bc-ba31-5e8593fe3083",
  "creationDate" : "2018-11-23T11:12:13Z",
  "_links" : {
    "onlineReport" : {
      "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
    },
    "pdfReport" : {
      "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
    },
    "self" : {
      "href" : "https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c"
    }
  }
}
{
  "id" : "1024138f-684f-4311-b539-774fd3ef3a9c",
  "firstName" : "John",
  "lastName" : "Smith",
  "email" : "john@smith.com",
  "tags" : [ "Phoenix", "TeamLeader" ],
  "disableCommunication" : false,
  "externalId" : "553c8ceb",
  "status" : "NEW",
  "assignedUser" : "d493e6d3-6a6a-4cf2-8990-46366c75064f",
  "assignedTeam" : "dc1087ed-97d5-43bc-ba31-5e8593fe3083",
  "creationDate" : "2018-11-23T11:12:13Z",
  "_links" : {
    "onlineReport" : {
      "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
    },
    "pdfReport" : {
      "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
    },
    "self" : {
      "href" : "https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c"
    }
  }
}

POST /candidates

A POST request is used to create a new candidate.

Request Body:

email
Type: String Required
The candidate's email address
firstName
Type: String Optional
The candidate's first name
lastName
Type: String Optional
The candidate's last name
tags
Type: Array Optional
The candidate's tags (array of strings)
externalId
Type: String Optional
Unique identifier of the candidate used in your system
disableCommunication
Type: Boolean Optional
Should the outbound communication to the candidate be disabled. Default: `false`

Response Headers:

Location
URI of the created candidate

Response Body:

The method returns the candidate object with standard content

Listing candidates

Request

GET /candidates?query=John&assignedUser=123&count=10&page=1&status=WAITING_FOR_ANSWERS&tags=Phoenix&tags=TeamLeader&startDate=2020-04-22 HTTP/1.1
Devskiller-Api-Key: TEST-API-KEY
Accept: application/vnd.devskiller.v2.hal+json
Host: api.devskiller.com

$ curl 'https://api.devskiller.com/candidates?query=John&assignedUser=123&count=10&page=1&status=WAITING_FOR_ANSWERS&tags=Phoenix&tags=TeamLeader&startDate=2020-04-22' -i -X GET \
    -H 'Devskiller-Api-Key: TEST-API-KEY' \
    -H 'Accept: application/vnd.devskiller.v2.hal+json'

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.devskiller.v2.hal+json;charset=UTF-8

{
  "_embedded" : {
    "candidates" : [ {
      "id" : "1024138f-684f-4311-b539-774fd3ef3a9c",
      "firstName" : "John",
      "lastName" : "Smith",
      "email" : "john@smith.com",
      "tags" : [ "Phoenix", "TeamLeader" ],
      "disableCommunication" : false,
      "externalId" : "553c8ceb",
      "status" : "NEW",
      "assignedUser" : "d493e6d3-6a6a-4cf2-8990-46366c75064f",
      "assignedTeam" : "dc1087ed-97d5-43bc-ba31-5e8593fe3083",
      "creationDate" : "2018-11-23T11:12:13Z",
      "_links" : {
        "onlineReport" : {
          "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        },
        "pdfReport" : {
          "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        },
        "self" : {
          "href" : "https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c"
        }
      }
    } ]
  },
  "page" : {
    "size" : 1,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 1
  }
}
{
  "_embedded" : {
    "candidates" : [ {
      "id" : "1024138f-684f-4311-b539-774fd3ef3a9c",
      "firstName" : "John",
      "lastName" : "Smith",
      "email" : "john@smith.com",
      "tags" : [ "Phoenix", "TeamLeader" ],
      "disableCommunication" : false,
      "externalId" : "553c8ceb",
      "status" : "NEW",
      "assignedUser" : "d493e6d3-6a6a-4cf2-8990-46366c75064f",
      "assignedTeam" : "dc1087ed-97d5-43bc-ba31-5e8593fe3083",
      "creationDate" : "2018-11-23T11:12:13Z",
      "_links" : {
        "onlineReport" : {
          "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        },
        "pdfReport" : {
          "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        },
        "self" : {
          "href" : "https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c"
        }
      }
    } ]
  },
  "page" : {
    "size" : 1,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 1
  }
}

GET /candidates

A GET request will list all candidates.

Request parameters:

query
Optional
Search by name,email or token
assignedUser
Optional
Identifies of the assigned user
assignedTeam
Optional
Identifies of the assigned team
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.
startDate
Optional
Filter candidates by exam start date.
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:

page.number
Type: Number Content: Standard
Number of the current page
page.size
Type: Number Content: Standard
Maximum number of elements for a page
page.totalElements
Type: Number Content: Standard
Total number of candidates matching criteria
page.totalPages
Type: Number Content: Standard
Total number of pages matching criteria
_embedded.candidates
Type: Array Content: Always
Arrays of candidates: candidate object with standard content

Retrieving the candidate

Request

GET /candidates/1024138f-684f-4311-b539-774fd3ef3a9c HTTP/1.1
Devskiller-Api-Key: TEST-API-KEY
Accept: application/vnd.devskiller.v2.hal+json
Host: api.devskiller.com

$ curl 'https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c' -i -X GET \
    -H 'Devskiller-Api-Key: TEST-API-KEY' \
    -H 'Accept: application/vnd.devskiller.v2.hal+json'

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.devskiller.v2.hal+json;charset=UTF-8

{
  "id" : "1024138f-684f-4311-b539-774fd3ef3a9c",
  "firstName" : "John",
  "lastName" : "Smith",
  "email" : "john@smith.com",
  "tags" : [ "Phoenix", "TeamLeader" ],
  "disableCommunication" : false,
  "externalId" : "553c8ceb",
  "status" : "IN_EVALUATION",
  "_embedded" : {
    "assessments" : [ {
      "id" : "90224982-2017-4098-bfc8-48f7b60ec01d",
      "status" : "ASSESSMENT_COMPLETED",
      "creationDate" : "2018-11-23T11:12:13Z",
      "startDate" : "2018-11-23T12:12:13Z",
      "finishDate" : "2018-11-23T13:12:13Z",
      "_links" : {
        "candidateAccess" : {
          "href" : "https://exam.devskiller.com/exam.html?2Y4D-9R2G-6WT7"
        },
        "onlineReport" : {
          "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        },
        "pdfReport" : {
          "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        },
        "candidateUrl" : {
          "href" : "https://app.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/detail/overview"
        },
        "self" : {
          "href" : "https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/assessments/90224982-2017-4098-bfc8-48f7b60ec01d"
        }
      }
    } ]
  },
  "assignedUser" : "d493e6d3-6a6a-4cf2-8990-46366c75064f",
  "assignedTeam" : "dc1087ed-97d5-43bc-ba31-5e8593fe3083",
  "creationDate" : "2018-11-23T11:12:13Z",
  "_links" : {
    "onlineReport" : {
      "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
    },
    "pdfReport" : {
      "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
    },
    "self" : {
      "href" : "https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c"
    }
  }
}
{
  "id" : "1024138f-684f-4311-b539-774fd3ef3a9c",
  "firstName" : "John",
  "lastName" : "Smith",
  "email" : "john@smith.com",
  "tags" : [ "Phoenix", "TeamLeader" ],
  "disableCommunication" : false,
  "externalId" : "553c8ceb",
  "status" : "IN_EVALUATION",
  "_embedded" : {
    "assessments" : [ {
      "id" : "90224982-2017-4098-bfc8-48f7b60ec01d",
      "status" : "ASSESSMENT_COMPLETED",
      "creationDate" : "2018-11-23T11:12:13Z",
      "startDate" : "2018-11-23T12:12:13Z",
      "finishDate" : "2018-11-23T13:12:13Z",
      "_links" : {
        "candidateAccess" : {
          "href" : "https://exam.devskiller.com/exam.html?2Y4D-9R2G-6WT7"
        },
        "onlineReport" : {
          "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        },
        "pdfReport" : {
          "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        },
        "candidateUrl" : {
          "href" : "https://app.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/detail/overview"
        },
        "self" : {
          "href" : "https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/assessments/90224982-2017-4098-bfc8-48f7b60ec01d"
        }
      }
    } ]
  },
  "assignedUser" : "d493e6d3-6a6a-4cf2-8990-46366c75064f",
  "assignedTeam" : "dc1087ed-97d5-43bc-ba31-5e8593fe3083",
  "creationDate" : "2018-11-23T11:12:13Z",
  "_links" : {
    "onlineReport" : {
      "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
    },
    "pdfReport" : {
      "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
    },
    "self" : {
      "href" : "https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c"
    }
  }
}

GET /candidates/{id}

A GET request will retrieve the details of a candidate

Response structure

The method returns the candidate object with extended content

Deleting the candidate

Request

DELETE /candidates/2er4Hm3VwGW3J0lfwrvQYd HTTP/1.1
Devskiller-Api-Key: TEST-API-KEY
Host: api.devskiller.com

$ curl 'https://api.devskiller.com/candidates/2er4Hm3VwGW3J0lfwrvQYd' -i -X DELETE \
    -H 'Devskiller-Api-Key: TEST-API-KEY'

Response

HTTP/1.1 204 No Content


DELETE /candidates/{id}

A DELETE request will remove a candidate

Accepting/rejecting the candidate

Request

PATCH /candidates/2er4Hm3VwGW3J0lfwrvQYd HTTP/1.1
Content-Type: application/vnd.devskiller.v2.hal+json
Devskiller-Api-Key: TEST-API-KEY
Host: api.devskiller.com

{
    "status": "ACCEPTED"
}
$ curl 'https://api.devskiller.com/candidates/2er4Hm3VwGW3J0lfwrvQYd' -i -X PATCH \
    -H 'Content-Type: application/vnd.devskiller.v2.hal+json' \
    -H 'Devskiller-Api-Key: TEST-API-KEY' \
    -d '{
    "status": "ACCEPTED"
}'

Response

HTTP/1.1 202 Accepted


PATCH /candidates/{id}

A PATCH request is used to accept or reject the candidate.

Request Body:

status
Type: String Required
The candidate's new status. Possible values: ACCEPTED,REJECTED

Assessment object

Sample

{
  "id" : "90224982-2017-4098-bfc8-48f7b60ec01d",
  "status" : "ASSESSMENT_COMPLETED",
  "timeTakenInSeconds" : 480,
  "timeLimitInSeconds" : 600,
  "score" : {
    "scoredPoints" : 45,
    "maxPoints" : 50,
    "percentage" : 90
  },
  "skills" : [ {
    "name" : "Java",
    "percentage" : 90
  }, {
    "name" : "SQL",
    "percentage" : 80
  } ],
  "sections" : [ {
    "timeTakenInSeconds" : 480,
    "timeLimitInSeconds" : 600,
    "score" : {
      "scoredPoints" : 20,
      "maxPoints" : 20,
      "percentage" : 100
    },
    "answers" : [ {
      "taskId" : "2tMX6eEu30TBTNGyFDdCx8",
      "title" : "SQL Left joins",
      "type" : "DATABASE",
      "score" : {
        "scoredPoints" : 20,
        "maxPoints" : 20,
        "percentage" : 100
      },
      "difficulty" : "EASY",
      "gitUrl" : "https://git.devskiller.com/d2f17e98-90fa-44cb-ad3c-6ef70a193e72.git"
    } ]
  }, {
    "timeTakenInSeconds" : 720,
    "timeLimitInSeconds" : 900,
    "score" : {
      "scoredPoints" : 25,
      "maxPoints" : 30,
      "percentage" : 83
    },
    "answers" : [ {
      "taskId" : "3roXXLB3P9GGpB5wR4lYj9",
      "title" : "Multithreading in Java",
      "type" : "PROGRAMMING",
      "score" : {
        "scoredPoints" : 25,
        "maxPoints" : 30,
        "percentage" : 83
      },
      "difficulty" : "MEDIUM",
      "gitUrl" : "https://git.devskiller.com/6a670f01-8395-4027-a6f1-d112d62a9140.git"
    } ]
  } ],
  "creationDate" : "2018-11-23T11:12:13Z",
  "startDate" : "2018-11-23T12:12:13Z",
  "finishDate" : "2018-11-23T13:12:13Z",
  "_embedded" : {
    "test" : {
      "id" : "d2d55c15-cb0e-4328-8699-ad957ba239c5",
      "name" : "Senior Java Developer",
      "_links" : {
        "self" : {
          "href" : "https://api.devskiller.com/tests/d2d55c15-cb0e-4328-8699-ad957ba239c5"
        }
      }
    }
  },
  "_links" : {
    "candidateAccess" : {
      "href" : "https://exam.devskiller.com/exam.html?2Y4D-9R2G-6WT7"
    },
    "onlineReport" : {
      "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
    },
    "pdfReport" : {
      "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
    },
    "candidateUrl" : {
      "href" : "https://app.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/detail/overview"
    },
    "self" : {
      "href" : "https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/assessments/90224982-2017-4098-bfc8-48f7b60ec01d"
    }
  }
}
HTTP/1.1 200 OK
Content-Type: application/vnd.devskiller.v2.hal+json;charset=UTF-8

{
  "id" : "90224982-2017-4098-bfc8-48f7b60ec01d",
  "status" : "ASSESSMENT_COMPLETED",
  "timeTakenInSeconds" : 480,
  "timeLimitInSeconds" : 600,
  "score" : {
    "scoredPoints" : 45,
    "maxPoints" : 50,
    "percentage" : 90
  },
  "skills" : [ {
    "name" : "Java",
    "percentage" : 90
  }, {
    "name" : "SQL",
    "percentage" : 80
  } ],
  "sections" : [ {
    "timeTakenInSeconds" : 480,
    "timeLimitInSeconds" : 600,
    "score" : {
      "scoredPoints" : 20,
      "maxPoints" : 20,
      "percentage" : 100
    },
    "answers" : [ {
      "taskId" : "2tMX6eEu30TBTNGyFDdCx8",
      "title" : "SQL Left joins",
      "type" : "DATABASE",
      "score" : {
        "scoredPoints" : 20,
        "maxPoints" : 20,
        "percentage" : 100
      },
      "difficulty" : "EASY",
      "gitUrl" : "https://git.devskiller.com/d2f17e98-90fa-44cb-ad3c-6ef70a193e72.git"
    } ]
  }, {
    "timeTakenInSeconds" : 720,
    "timeLimitInSeconds" : 900,
    "score" : {
      "scoredPoints" : 25,
      "maxPoints" : 30,
      "percentage" : 83
    },
    "answers" : [ {
      "taskId" : "3roXXLB3P9GGpB5wR4lYj9",
      "title" : "Multithreading in Java",
      "type" : "PROGRAMMING",
      "score" : {
        "scoredPoints" : 25,
        "maxPoints" : 30,
        "percentage" : 83
      },
      "difficulty" : "MEDIUM",
      "gitUrl" : "https://git.devskiller.com/6a670f01-8395-4027-a6f1-d112d62a9140.git"
    } ]
  } ],
  "creationDate" : "2018-11-23T11:12:13Z",
  "startDate" : "2018-11-23T12:12:13Z",
  "finishDate" : "2018-11-23T13:12:13Z",
  "_embedded" : {
    "test" : {
      "id" : "d2d55c15-cb0e-4328-8699-ad957ba239c5",
      "name" : "Senior Java Developer",
      "_links" : {
        "self" : {
          "href" : "https://api.devskiller.com/tests/d2d55c15-cb0e-4328-8699-ad957ba239c5"
        }
      }
    }
  },
  "_links" : {
    "candidateAccess" : {
      "href" : "https://exam.devskiller.com/exam.html?2Y4D-9R2G-6WT7"
    },
    "onlineReport" : {
      "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
    },
    "pdfReport" : {
      "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
    },
    "candidateUrl" : {
      "href" : "https://app.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/detail/overview"
    },
    "self" : {
      "href" : "https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/assessments/90224982-2017-4098-bfc8-48f7b60ec01d"
    }
  }
}

Attributes

id
Type: String Content: Standard
Assessment id
status
Type: String Content: Standard
Assessment status
creationDate
Type: String Content: Standard
Date when the assessment has been created
startDate
Type: String Content: Standard
Date when the candidates started the assessment
finishDate
Type: String Content: Standard
Date when the finished started the assessment
timeTakenInSeconds
Type: Number Content: Standard
Time in seconds spent by the candidate on the assessment
timeLimitInSeconds
Type: Number Content: Standard
Assessment time limit in seconds
score.scoredPoints
Type: Number Content: Standard
Scored points
score.maxPoints
Type: Number Content: Standard
Max points
score.percentage
Type: Number Content: Standard
Percentage result
skills[].name
Type: String Content: Extended
Name of the skill
skills[].percentage
Type: Number Content: Extended
Percentage result for the tasks related to the skill
sections[].timeTakenInSeconds
Type: Number Content: Extended
Time in seconds spent by the candidate in the section
sections[].timeLimitInSeconds
Type: Number Content: Extended
Time limit in seconds for the section
sections[].score
Type: Object Content: Extended
Score of the section with the structure same as the `score` of the assessment
sections[].answers[].taskId
Type: String Content: Extended
Id of the task
sections[].answers[].title
Type: String Content: Extended
Title of the task
sections[].answers[].gitUrl
Type: String Content: Extended
Link to git repository
sections[].answers[].type
Type: String Content: Extended
Type of the task. Possible values: CHOICE, CODE_GAPS, CODE_REVIEW, DATABASE, DEVOPS, ESSAY, PROGRAMMING
sections[].answers[].difficulty
Type: String Content: Extended
Difficulty of the task. Possible values: EASY, MEDIUM, HARD
sections[].answers[].score
Type: Object Content: Extended
Score of the section with the structure same as the `score` of the assessment
_embedded.test.id
Type: String Content: Extended
Test id
_embedded.test.name
Type: String Content: Extended
Test name
_embedded.test._links.self.href
Type: String Content: Extended
Link to the test
self
Direct link to the assessment
candidateAccess
Link for the candidate to take the assessment
onlineReport
Link to the assessment report page
pdfReport
Link to the assessment PDF report
candidateUrl
Link to candidate page

Creating an assessment

Request

POST /candidates/2er4Hm3VwGW3J0lfwrvQYd/assessments HTTP/1.1
Content-Type: application/vnd.devskiller.v2.hal+json
Devskiller-Api-Key: TEST-API-KEY
Accept: application/vnd.devskiller.v2.hal+json
Host: api.devskiller.com

{
    "testId": "70Wvi8uyl9mFFM4xuVdI5o",
    "validityInDays": 14,
    "note": "Custom note for the candidate"
}
$ curl 'https://api.devskiller.com/candidates/2er4Hm3VwGW3J0lfwrvQYd/assessments' -i -X POST \
    -H 'Content-Type: application/vnd.devskiller.v2.hal+json' \
    -H 'Devskiller-Api-Key: TEST-API-KEY' \
    -H 'Accept: application/vnd.devskiller.v2.hal+json' \
    -d '{
    "testId": "70Wvi8uyl9mFFM4xuVdI5o",
    "validityInDays": 14,
    "note": "Custom note for the candidate"
}'

Response

HTTP/1.1 201 Created
Location: https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/assessments/90224982-2017-4098-bfc8-48f7b60ec01d
Content-Type: application/vnd.devskiller.v2.hal+json;charset=UTF-8

{
  "id" : "90224982-2017-4098-bfc8-48f7b60ec01d",
  "status" : "ASSESSMENT_COMPLETED",
  "creationDate" : "2018-11-23T11:12:13Z",
  "startDate" : "2018-11-23T12:12:13Z",
  "finishDate" : "2018-11-23T13:12:13Z",
  "_links" : {
    "candidateAccess" : {
      "href" : "https://exam.devskiller.com/exam.html?2Y4D-9R2G-6WT7"
    },
    "onlineReport" : {
      "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
    },
    "pdfReport" : {
      "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
    },
    "candidateUrl" : {
      "href" : "https://app.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/detail/overview"
    },
    "self" : {
      "href" : "https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/assessments/90224982-2017-4098-bfc8-48f7b60ec01d"
    }
  }
}
{
  "id" : "90224982-2017-4098-bfc8-48f7b60ec01d",
  "status" : "ASSESSMENT_COMPLETED",
  "creationDate" : "2018-11-23T11:12:13Z",
  "startDate" : "2018-11-23T12:12:13Z",
  "finishDate" : "2018-11-23T13:12:13Z",
  "_links" : {
    "candidateAccess" : {
      "href" : "https://exam.devskiller.com/exam.html?2Y4D-9R2G-6WT7"
    },
    "onlineReport" : {
      "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
    },
    "pdfReport" : {
      "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
    },
    "candidateUrl" : {
      "href" : "https://app.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/detail/overview"
    },
    "self" : {
      "href" : "https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/assessments/90224982-2017-4098-bfc8-48f7b60ec01d"
    }
  }
}

POST /candidates/{candidateId}/assessments

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

Request Body:

testId
Type: String Required
The id of the test
validityInDays
Type: Number Optional
Test validity in days
note
Type: String Optional
Note to include in the invitation email

Response Headers:

Location
URI of the created assessment

Response Body:

The method returns the assessment object with standard content

Retrieving the assessment

Request

GET /candidates/2er4Hm3VwGW3J0lfwrvQYd/assessments/5wxgYgs41BZoohKMdwrMKj HTTP/1.1
Devskiller-Api-Key: TEST-API-KEY
Accept: application/vnd.devskiller.v2.hal+json
Host: api.devskiller.com

$ curl 'https://api.devskiller.com/candidates/2er4Hm3VwGW3J0lfwrvQYd/assessments/5wxgYgs41BZoohKMdwrMKj' -i -X GET \
    -H 'Devskiller-Api-Key: TEST-API-KEY' \
    -H 'Accept: application/vnd.devskiller.v2.hal+json'

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.devskiller.v2.hal+json;charset=UTF-8

{
  "id" : "90224982-2017-4098-bfc8-48f7b60ec01d",
  "status" : "ASSESSMENT_COMPLETED",
  "timeTakenInSeconds" : 480,
  "timeLimitInSeconds" : 600,
  "score" : {
    "scoredPoints" : 45,
    "maxPoints" : 50,
    "percentage" : 90
  },
  "skills" : [ {
    "name" : "Java",
    "percentage" : 90
  }, {
    "name" : "SQL",
    "percentage" : 80
  } ],
  "sections" : [ {
    "timeTakenInSeconds" : 480,
    "timeLimitInSeconds" : 600,
    "score" : {
      "scoredPoints" : 20,
      "maxPoints" : 20,
      "percentage" : 100
    },
    "answers" : [ {
      "taskId" : "2tMX6eEu30TBTNGyFDdCx8",
      "title" : "SQL Left joins",
      "type" : "DATABASE",
      "score" : {
        "scoredPoints" : 20,
        "maxPoints" : 20,
        "percentage" : 100
      },
      "difficulty" : "EASY",
      "gitUrl" : "https://git.devskiller.com/d2f17e98-90fa-44cb-ad3c-6ef70a193e72.git"
    } ]
  }, {
    "timeTakenInSeconds" : 720,
    "timeLimitInSeconds" : 900,
    "score" : {
      "scoredPoints" : 25,
      "maxPoints" : 30,
      "percentage" : 83
    },
    "answers" : [ {
      "taskId" : "3roXXLB3P9GGpB5wR4lYj9",
      "title" : "Multithreading in Java",
      "type" : "PROGRAMMING",
      "score" : {
        "scoredPoints" : 25,
        "maxPoints" : 30,
        "percentage" : 83
      },
      "difficulty" : "MEDIUM",
      "gitUrl" : "https://git.devskiller.com/6a670f01-8395-4027-a6f1-d112d62a9140.git"
    } ]
  } ],
  "creationDate" : "2018-11-23T11:12:13Z",
  "startDate" : "2018-11-23T12:12:13Z",
  "finishDate" : "2018-11-23T13:12:13Z",
  "_embedded" : {
    "test" : {
      "id" : "d2d55c15-cb0e-4328-8699-ad957ba239c5",
      "name" : "Senior Java Developer",
      "_links" : {
        "self" : {
          "href" : "https://api.devskiller.com/tests/d2d55c15-cb0e-4328-8699-ad957ba239c5"
        }
      }
    }
  },
  "_links" : {
    "candidateAccess" : {
      "href" : "https://exam.devskiller.com/exam.html?2Y4D-9R2G-6WT7"
    },
    "onlineReport" : {
      "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
    },
    "pdfReport" : {
      "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
    },
    "candidateUrl" : {
      "href" : "https://app.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/detail/overview"
    },
    "self" : {
      "href" : "https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/assessments/90224982-2017-4098-bfc8-48f7b60ec01d"
    }
  }
}
{
  "id" : "90224982-2017-4098-bfc8-48f7b60ec01d",
  "status" : "ASSESSMENT_COMPLETED",
  "timeTakenInSeconds" : 480,
  "timeLimitInSeconds" : 600,
  "score" : {
    "scoredPoints" : 45,
    "maxPoints" : 50,
    "percentage" : 90
  },
  "skills" : [ {
    "name" : "Java",
    "percentage" : 90
  }, {
    "name" : "SQL",
    "percentage" : 80
  } ],
  "sections" : [ {
    "timeTakenInSeconds" : 480,
    "timeLimitInSeconds" : 600,
    "score" : {
      "scoredPoints" : 20,
      "maxPoints" : 20,
      "percentage" : 100
    },
    "answers" : [ {
      "taskId" : "2tMX6eEu30TBTNGyFDdCx8",
      "title" : "SQL Left joins",
      "type" : "DATABASE",
      "score" : {
        "scoredPoints" : 20,
        "maxPoints" : 20,
        "percentage" : 100
      },
      "difficulty" : "EASY",
      "gitUrl" : "https://git.devskiller.com/d2f17e98-90fa-44cb-ad3c-6ef70a193e72.git"
    } ]
  }, {
    "timeTakenInSeconds" : 720,
    "timeLimitInSeconds" : 900,
    "score" : {
      "scoredPoints" : 25,
      "maxPoints" : 30,
      "percentage" : 83
    },
    "answers" : [ {
      "taskId" : "3roXXLB3P9GGpB5wR4lYj9",
      "title" : "Multithreading in Java",
      "type" : "PROGRAMMING",
      "score" : {
        "scoredPoints" : 25,
        "maxPoints" : 30,
        "percentage" : 83
      },
      "difficulty" : "MEDIUM",
      "gitUrl" : "https://git.devskiller.com/6a670f01-8395-4027-a6f1-d112d62a9140.git"
    } ]
  } ],
  "creationDate" : "2018-11-23T11:12:13Z",
  "startDate" : "2018-11-23T12:12:13Z",
  "finishDate" : "2018-11-23T13:12:13Z",
  "_embedded" : {
    "test" : {
      "id" : "d2d55c15-cb0e-4328-8699-ad957ba239c5",
      "name" : "Senior Java Developer",
      "_links" : {
        "self" : {
          "href" : "https://api.devskiller.com/tests/d2d55c15-cb0e-4328-8699-ad957ba239c5"
        }
      }
    }
  },
  "_links" : {
    "candidateAccess" : {
      "href" : "https://exam.devskiller.com/exam.html?2Y4D-9R2G-6WT7"
    },
    "onlineReport" : {
      "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
    },
    "pdfReport" : {
      "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
    },
    "candidateUrl" : {
      "href" : "https://app.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/detail/overview"
    },
    "self" : {
      "href" : "https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/assessments/90224982-2017-4098-bfc8-48f7b60ec01d"
    }
  }
}

GET /candidates/{id}/assessments/{assessmentId}

A GET request will retrieve the results for a candidate

Response Body:

The method returns the assessment object with extended content

Deleting the assessment

Request

DELETE /candidates/2er4Hm3VwGW3J0lfwrvQYd/assessments/5wxgYgs41BZoohKMdwrMKj HTTP/1.1
Devskiller-Api-Key: TEST-API-KEY
Host: api.devskiller.com

$ curl 'https://api.devskiller.com/candidates/2er4Hm3VwGW3J0lfwrvQYd/assessments/5wxgYgs41BZoohKMdwrMKj' -i -X DELETE \
    -H 'Devskiller-Api-Key: TEST-API-KEY'

Response

HTTP/1.1 204 No Content


DELETE /candidates/{id}/assessments/{assessmentId}

A DELETE request will remove an assessment

Invitations

You can work individually with candidates and assessment, but if you have a 1:1 candidate-assessment relation, you can prefer to work with invitations.

Creating an invitation

Request

POST /invitations HTTP/1.1
Content-Type: application/vnd.devskiller.v2.hal+json
Devskiller-Api-Key: TEST-API-KEY
Accept: application/vnd.devskiller.v2.hal+json
Host: api.devskiller.com

{
    "email": "john@smith.com",
    "firstName": "John",
    "lastName": "Smith",
    "tags": [
        "Phoenix",
        "TeamLeader"
    ],
    "externalId": "553c8ceb",
    "disableCommunication": false,
    "testId": "70Wvi8uyl9mFFM4xuVdI5o",
    "validityInDays": 14,
    "note": "Custom note for the candidate"
}
$ curl 'https://api.devskiller.com/invitations' -i -X POST \
    -H 'Content-Type: application/vnd.devskiller.v2.hal+json' \
    -H 'Devskiller-Api-Key: TEST-API-KEY' \
    -H 'Accept: application/vnd.devskiller.v2.hal+json' \
    -d '{
    "email": "john@smith.com",
    "firstName": "John",
    "lastName": "Smith",
    "tags": [
        "Phoenix",
        "TeamLeader"
    ],
    "externalId": "553c8ceb",
    "disableCommunication": false,
    "testId": "70Wvi8uyl9mFFM4xuVdI5o",
    "validityInDays": 14,
    "note": "Custom note for the candidate"
}'

Response

HTTP/1.1 201 Created
Location: https://api.devskiller.com/invitations/90224982-2017-4098-bfc8-48f7b60ec01d
Content-Type: application/vnd.devskiller.v2.hal+json;charset=UTF-8

{
  "id" : "90224982-2017-4098-bfc8-48f7b60ec01d",
  "_embedded" : {
    "assessment" : {
      "id" : "90224982-2017-4098-bfc8-48f7b60ec01d",
      "status" : "NEW",
      "timeTakenInSeconds" : 480,
      "timeLimitInSeconds" : 600,
      "score" : null,
      "skills" : null,
      "sections" : null,
      "creationDate" : "2018-11-23T11:12:13Z",
      "startDate" : "2018-11-23T12:12:13Z",
      "finishDate" : "2018-11-23T13:12:13Z",
      "_embedded" : {
        "test" : {
          "id" : "d2d55c15-cb0e-4328-8699-ad957ba239c5",
          "name" : "Senior Java Developer"
        }
      },
      "_links" : {
        "candidateAccess" : {
          "href" : "https://exam.devskiller.com/exam.html?2Y4D-9R2G-6WT7"
        },
        "onlineReport" : {
          "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        },
        "pdfReport" : {
          "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        },
        "candidateUrl" : {
          "href" : "https://app.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/detail/overview"
        }
      }
    },
    "candidate" : {
      "id" : "1024138f-684f-4311-b539-774fd3ef3a9c",
      "firstName" : "John",
      "lastName" : "Smith",
      "email" : "john@smith.com",
      "tags" : [ "Phoenix", "TeamLeader" ],
      "disableCommunication" : false,
      "externalId" : "553c8ceb",
      "status" : "NEW",
      "assignedUser" : "d493e6d3-6a6a-4cf2-8990-46366c75064f",
      "assignedTeam" : "dc1087ed-97d5-43bc-ba31-5e8593fe3083",
      "creationDate" : "2018-11-23T11:12:13Z",
      "_links" : {
        "onlineReport" : {
          "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        },
        "pdfReport" : {
          "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        }
      }
    }
  },
  "_links" : {
    "self" : {
      "href" : "https://api.devskiller.com/invitations/90224982-2017-4098-bfc8-48f7b60ec01d"
    }
  }
}
{
  "id" : "90224982-2017-4098-bfc8-48f7b60ec01d",
  "_embedded" : {
    "assessment" : {
      "id" : "90224982-2017-4098-bfc8-48f7b60ec01d",
      "status" : "NEW",
      "timeTakenInSeconds" : 480,
      "timeLimitInSeconds" : 600,
      "score" : null,
      "skills" : null,
      "sections" : null,
      "creationDate" : "2018-11-23T11:12:13Z",
      "startDate" : "2018-11-23T12:12:13Z",
      "finishDate" : "2018-11-23T13:12:13Z",
      "_embedded" : {
        "test" : {
          "id" : "d2d55c15-cb0e-4328-8699-ad957ba239c5",
          "name" : "Senior Java Developer"
        }
      },
      "_links" : {
        "candidateAccess" : {
          "href" : "https://exam.devskiller.com/exam.html?2Y4D-9R2G-6WT7"
        },
        "onlineReport" : {
          "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        },
        "pdfReport" : {
          "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        },
        "candidateUrl" : {
          "href" : "https://app.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/detail/overview"
        }
      }
    },
    "candidate" : {
      "id" : "1024138f-684f-4311-b539-774fd3ef3a9c",
      "firstName" : "John",
      "lastName" : "Smith",
      "email" : "john@smith.com",
      "tags" : [ "Phoenix", "TeamLeader" ],
      "disableCommunication" : false,
      "externalId" : "553c8ceb",
      "status" : "NEW",
      "assignedUser" : "d493e6d3-6a6a-4cf2-8990-46366c75064f",
      "assignedTeam" : "dc1087ed-97d5-43bc-ba31-5e8593fe3083",
      "creationDate" : "2018-11-23T11:12:13Z",
      "_links" : {
        "onlineReport" : {
          "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        },
        "pdfReport" : {
          "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        }
      }
    }
  },
  "_links" : {
    "self" : {
      "href" : "https://api.devskiller.com/invitations/90224982-2017-4098-bfc8-48f7b60ec01d"
    }
  }
}

POST /invitations

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

Request Body:

email
Type: String Required
The candidate's email address
firstName
Type: String Optional
The candidate's first name
lastName
Type: String Optional
The candidate's last name
tags
Type: Array Optional
The candidate's tags (array of strings)
externalId
Type: String Optional
Unique identifier of the candidate used in your system
disableCommunication
Type: Boolean Optional
Should the outbound communication to the candidate be disabled. Default: `false`
testId
Type: String Required
The unique identifier of the test
validityInDays
Type: Number Optional
Invitation validity in days
note
Type: String Optional
Additional note that should be included in the email to the candidate

Response Headers:

Location
URI of the created invitation

Response Body:

The method returns two embedded objects:

Listing invitations

Request

GET /invitations?query=John&count=10&page=1&status=ASSESSMENT_COMPLETED&tags=Phoenix&tags=TeamLeader&startDate=2020-04-22 HTTP/1.1
Devskiller-Api-Key: TEST-API-KEY
Accept: application/vnd.devskiller.v2.hal+json
Host: api.devskiller.com

$ curl 'https://api.devskiller.com/invitations?query=John&count=10&page=1&status=ASSESSMENT_COMPLETED&tags=Phoenix&tags=TeamLeader&startDate=2020-04-22' -i -X GET \
    -H 'Devskiller-Api-Key: TEST-API-KEY' \
    -H 'Accept: application/vnd.devskiller.v2.hal+json'

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.devskiller.v2.hal+json;charset=UTF-8

{
  "_embedded" : {
    "invitations" : [ {
      "id" : "90224982-2017-4098-bfc8-48f7b60ec01d",
      "_embedded" : {
        "assessment" : {
          "id" : "90224982-2017-4098-bfc8-48f7b60ec01d",
          "status" : "ASSESSMENT_COMPLETED",
          "creationDate" : "2018-11-23T11:12:13Z",
          "startDate" : "2018-11-23T12:12:13Z",
          "finishDate" : "2018-11-23T13:12:13Z",
          "_links" : {
            "candidateAccess" : {
              "href" : "https://exam.devskiller.com/exam.html?2Y4D-9R2G-6WT7"
            },
            "onlineReport" : {
              "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
            },
            "pdfReport" : {
              "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
            },
            "candidateUrl" : {
              "href" : "https://app.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/detail/overview"
            }
          }
        },
        "candidate" : {
          "id" : "1024138f-684f-4311-b539-774fd3ef3a9c",
          "firstName" : "John",
          "lastName" : "Smith",
          "email" : "john@smith.com",
          "tags" : [ "Phoenix", "TeamLeader" ],
          "disableCommunication" : false,
          "externalId" : "553c8ceb",
          "status" : "NEW",
          "assignedUser" : "d493e6d3-6a6a-4cf2-8990-46366c75064f",
          "assignedTeam" : "dc1087ed-97d5-43bc-ba31-5e8593fe3083",
          "creationDate" : "2018-11-23T11:12:13Z",
          "_links" : {
            "onlineReport" : {
              "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
            },
            "pdfReport" : {
              "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
            }
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://api.devskiller.com/invitations/90224982-2017-4098-bfc8-48f7b60ec01d"
        }
      }
    } ]
  },
  "page" : {
    "size" : 1,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 1
  }
}
{
  "_embedded" : {
    "invitations" : [ {
      "id" : "90224982-2017-4098-bfc8-48f7b60ec01d",
      "_embedded" : {
        "assessment" : {
          "id" : "90224982-2017-4098-bfc8-48f7b60ec01d",
          "status" : "ASSESSMENT_COMPLETED",
          "creationDate" : "2018-11-23T11:12:13Z",
          "startDate" : "2018-11-23T12:12:13Z",
          "finishDate" : "2018-11-23T13:12:13Z",
          "_links" : {
            "candidateAccess" : {
              "href" : "https://exam.devskiller.com/exam.html?2Y4D-9R2G-6WT7"
            },
            "onlineReport" : {
              "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
            },
            "pdfReport" : {
              "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
            },
            "candidateUrl" : {
              "href" : "https://app.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/detail/overview"
            }
          }
        },
        "candidate" : {
          "id" : "1024138f-684f-4311-b539-774fd3ef3a9c",
          "firstName" : "John",
          "lastName" : "Smith",
          "email" : "john@smith.com",
          "tags" : [ "Phoenix", "TeamLeader" ],
          "disableCommunication" : false,
          "externalId" : "553c8ceb",
          "status" : "NEW",
          "assignedUser" : "d493e6d3-6a6a-4cf2-8990-46366c75064f",
          "assignedTeam" : "dc1087ed-97d5-43bc-ba31-5e8593fe3083",
          "creationDate" : "2018-11-23T11:12:13Z",
          "_links" : {
            "onlineReport" : {
              "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
            },
            "pdfReport" : {
              "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
            }
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://api.devskiller.com/invitations/90224982-2017-4098-bfc8-48f7b60ec01d"
        }
      }
    } ]
  },
  "page" : {
    "size" : 1,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 1
  }
}

GET /invitations

A GET request will list all invitations.

Request parameters:

query
Optional
Search by name,email or token
status
Optional
Filter invitations by status. Add multiple status parameters to search for several statuses.
tags
Optional
Filter invitations by tags. Add multiple tags parameters to search for several tags.
startDate
Optional
Filter invitations by exam start date.
count
Optional
Maximum number of invitations to get. Default: `10`, Max: `100`
page
Optional
Number of the page to fetch, starting with `0`. Default: `0`

Response Body:

The method returns list of two embedded objects:

Details of the invitation

Request

GET /invitations/5wxgYgs41BZoohKMdwrMKj HTTP/1.1
Devskiller-Api-Key: TEST-API-KEY
Accept: application/vnd.devskiller.v2.hal+json
Host: api.devskiller.com

$ curl 'https://api.devskiller.com/invitations/5wxgYgs41BZoohKMdwrMKj' -i -X GET \
    -H 'Devskiller-Api-Key: TEST-API-KEY' \
    -H 'Accept: application/vnd.devskiller.v2.hal+json'

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.devskiller.v2.hal+json;charset=UTF-8

{
  "id" : "5wxgYgs41BZoohKMdwrMKj",
  "_embedded" : {
    "assessment" : {
      "id" : "90224982-2017-4098-bfc8-48f7b60ec01d",
      "status" : "ASSESSMENT_COMPLETED",
      "timeTakenInSeconds" : 480,
      "timeLimitInSeconds" : 600,
      "score" : {
        "scoredPoints" : 45,
        "maxPoints" : 50,
        "percentage" : 90
      },
      "skills" : [ {
        "name" : "Java",
        "percentage" : 90
      }, {
        "name" : "SQL",
        "percentage" : 80
      } ],
      "sections" : [ {
        "timeTakenInSeconds" : 480,
        "timeLimitInSeconds" : 600,
        "score" : {
          "scoredPoints" : 20,
          "maxPoints" : 20,
          "percentage" : 100
        },
        "answers" : [ {
          "taskId" : "2tMX6eEu30TBTNGyFDdCx8",
          "title" : "SQL Left joins",
          "type" : "DATABASE",
          "score" : {
            "scoredPoints" : 20,
            "maxPoints" : 20,
            "percentage" : 100
          },
          "difficulty" : "EASY",
          "gitUrl" : "https://git.devskiller.com/d2f17e98-90fa-44cb-ad3c-6ef70a193e72.git"
        } ]
      }, {
        "timeTakenInSeconds" : 720,
        "timeLimitInSeconds" : 900,
        "score" : {
          "scoredPoints" : 25,
          "maxPoints" : 30,
          "percentage" : 83
        },
        "answers" : [ {
          "taskId" : "3roXXLB3P9GGpB5wR4lYj9",
          "title" : "Multithreading in Java",
          "type" : "PROGRAMMING",
          "score" : {
            "scoredPoints" : 25,
            "maxPoints" : 30,
            "percentage" : 83
          },
          "difficulty" : "MEDIUM",
          "gitUrl" : "https://git.devskiller.com/6a670f01-8395-4027-a6f1-d112d62a9140.git"
        } ]
      } ],
      "creationDate" : "2018-11-23T11:12:13Z",
      "startDate" : "2018-11-23T12:12:13Z",
      "finishDate" : "2018-11-23T13:12:13Z",
      "_embedded" : {
        "test" : {
          "id" : "d2d55c15-cb0e-4328-8699-ad957ba239c5",
          "name" : "Senior Java Developer"
        }
      },
      "_links" : {
        "candidateAccess" : {
          "href" : "https://exam.devskiller.com/exam.html?2Y4D-9R2G-6WT7"
        },
        "onlineReport" : {
          "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        },
        "pdfReport" : {
          "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        },
        "candidateUrl" : {
          "href" : "https://app.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/detail/overview"
        }
      }
    },
    "candidate" : {
      "id" : "1024138f-684f-4311-b539-774fd3ef3a9c",
      "firstName" : "John",
      "lastName" : "Smith",
      "email" : "john@smith.com",
      "tags" : [ "Phoenix", "TeamLeader" ],
      "disableCommunication" : false,
      "externalId" : "553c8ceb",
      "status" : "IN_EVALUATION",
      "_embedded" : {
        "assessments" : [ {
          "id" : "90224982-2017-4098-bfc8-48f7b60ec01d",
          "status" : "ASSESSMENT_COMPLETED",
          "creationDate" : "2018-11-23T11:12:13Z",
          "startDate" : "2018-11-23T12:12:13Z",
          "finishDate" : "2018-11-23T13:12:13Z",
          "_links" : {
            "candidateAccess" : {
              "href" : "https://exam.devskiller.com/exam.html?2Y4D-9R2G-6WT7"
            },
            "onlineReport" : {
              "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
            },
            "pdfReport" : {
              "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
            },
            "candidateUrl" : {
              "href" : "https://app.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/detail/overview"
            }
          }
        } ]
      },
      "assignedUser" : "d493e6d3-6a6a-4cf2-8990-46366c75064f",
      "assignedTeam" : "dc1087ed-97d5-43bc-ba31-5e8593fe3083",
      "creationDate" : "2018-11-23T11:12:13Z",
      "_links" : {
        "onlineReport" : {
          "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        },
        "pdfReport" : {
          "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        }
      }
    }
  }
}
{
  "id" : "5wxgYgs41BZoohKMdwrMKj",
  "_embedded" : {
    "assessment" : {
      "id" : "90224982-2017-4098-bfc8-48f7b60ec01d",
      "status" : "ASSESSMENT_COMPLETED",
      "timeTakenInSeconds" : 480,
      "timeLimitInSeconds" : 600,
      "score" : {
        "scoredPoints" : 45,
        "maxPoints" : 50,
        "percentage" : 90
      },
      "skills" : [ {
        "name" : "Java",
        "percentage" : 90
      }, {
        "name" : "SQL",
        "percentage" : 80
      } ],
      "sections" : [ {
        "timeTakenInSeconds" : 480,
        "timeLimitInSeconds" : 600,
        "score" : {
          "scoredPoints" : 20,
          "maxPoints" : 20,
          "percentage" : 100
        },
        "answers" : [ {
          "taskId" : "2tMX6eEu30TBTNGyFDdCx8",
          "title" : "SQL Left joins",
          "type" : "DATABASE",
          "score" : {
            "scoredPoints" : 20,
            "maxPoints" : 20,
            "percentage" : 100
          },
          "difficulty" : "EASY",
          "gitUrl" : "https://git.devskiller.com/d2f17e98-90fa-44cb-ad3c-6ef70a193e72.git"
        } ]
      }, {
        "timeTakenInSeconds" : 720,
        "timeLimitInSeconds" : 900,
        "score" : {
          "scoredPoints" : 25,
          "maxPoints" : 30,
          "percentage" : 83
        },
        "answers" : [ {
          "taskId" : "3roXXLB3P9GGpB5wR4lYj9",
          "title" : "Multithreading in Java",
          "type" : "PROGRAMMING",
          "score" : {
            "scoredPoints" : 25,
            "maxPoints" : 30,
            "percentage" : 83
          },
          "difficulty" : "MEDIUM",
          "gitUrl" : "https://git.devskiller.com/6a670f01-8395-4027-a6f1-d112d62a9140.git"
        } ]
      } ],
      "creationDate" : "2018-11-23T11:12:13Z",
      "startDate" : "2018-11-23T12:12:13Z",
      "finishDate" : "2018-11-23T13:12:13Z",
      "_embedded" : {
        "test" : {
          "id" : "d2d55c15-cb0e-4328-8699-ad957ba239c5",
          "name" : "Senior Java Developer"
        }
      },
      "_links" : {
        "candidateAccess" : {
          "href" : "https://exam.devskiller.com/exam.html?2Y4D-9R2G-6WT7"
        },
        "onlineReport" : {
          "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        },
        "pdfReport" : {
          "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        },
        "candidateUrl" : {
          "href" : "https://app.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/detail/overview"
        }
      }
    },
    "candidate" : {
      "id" : "1024138f-684f-4311-b539-774fd3ef3a9c",
      "firstName" : "John",
      "lastName" : "Smith",
      "email" : "john@smith.com",
      "tags" : [ "Phoenix", "TeamLeader" ],
      "disableCommunication" : false,
      "externalId" : "553c8ceb",
      "status" : "IN_EVALUATION",
      "_embedded" : {
        "assessments" : [ {
          "id" : "90224982-2017-4098-bfc8-48f7b60ec01d",
          "status" : "ASSESSMENT_COMPLETED",
          "creationDate" : "2018-11-23T11:12:13Z",
          "startDate" : "2018-11-23T12:12:13Z",
          "finishDate" : "2018-11-23T13:12:13Z",
          "_links" : {
            "candidateAccess" : {
              "href" : "https://exam.devskiller.com/exam.html?2Y4D-9R2G-6WT7"
            },
            "onlineReport" : {
              "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
            },
            "pdfReport" : {
              "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
            },
            "candidateUrl" : {
              "href" : "https://app.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/detail/overview"
            }
          }
        } ]
      },
      "assignedUser" : "d493e6d3-6a6a-4cf2-8990-46366c75064f",
      "assignedTeam" : "dc1087ed-97d5-43bc-ba31-5e8593fe3083",
      "creationDate" : "2018-11-23T11:12:13Z",
      "_links" : {
        "onlineReport" : {
          "href" : "https://report.devskiller.com/candidate-report.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        },
        "pdfReport" : {
          "href" : "https://report.devskiller.com/candidate-pdf.html?1024138f-684f-4311-b539-774fd3ef3a9c"
        }
      }
    }
  }
}

GET /invitations/{id}

A GET request will retrieve the details of an invitation

Response Body:

The method returns two embedded objects:

Deleting the invitation

Request

DELETE /invitations/5wxgYgs41BZoohKMdwrMKj HTTP/1.1
Devskiller-Api-Key: TEST-API-KEY
Host: api.devskiller.com

$ curl 'https://api.devskiller.com/invitations/5wxgYgs41BZoohKMdwrMKj' -i -X DELETE \
    -H 'Devskiller-Api-Key: TEST-API-KEY'

Response

HTTP/1.1 204 No Content


DELETE /invitations/{id}

A DELETE request will remove the invitation

Tests

The Tests resources is used to list test

List tests

Request

GET /tests?query=Java&count=10&page=1 HTTP/1.1
Devskiller-Api-Key: TEST-API-KEY
Accept: application/vnd.devskiller.v2.hal+json
Host: api.devskiller.com

$ curl 'https://api.devskiller.com/tests?query=Java&count=10&page=1' -i -X GET \
    -H 'Devskiller-Api-Key: TEST-API-KEY' \
    -H 'Accept: application/vnd.devskiller.v2.hal+json'

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.devskiller.v2.hal+json;charset=UTF-8

{
  "_embedded" : {
    "tests" : [ {
      "id" : "d2d55c15-cb0e-4328-8699-ad957ba239c5",
      "name" : "Senior Java Developer",
      "skills" : [ "Java", "SQL" ],
      "durationInMinutes" : 60,
      "_links" : {
        "self" : {
          "href" : "https://api.devskiller.com/tests/d2d55c15-cb0e-4328-8699-ad957ba239c5"
        }
      }
    } ]
  },
  "page" : {
    "size" : 1,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 1
  }
}
{
  "_embedded" : {
    "tests" : [ {
      "id" : "d2d55c15-cb0e-4328-8699-ad957ba239c5",
      "name" : "Senior Java Developer",
      "skills" : [ "Java", "SQL" ],
      "durationInMinutes" : 60,
      "_links" : {
        "self" : {
          "href" : "https://api.devskiller.com/tests/d2d55c15-cb0e-4328-8699-ad957ba239c5"
        }
      }
    } ]
  },
  "page" : {
    "size" : 1,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 1
  }
}

GET /tests

A GET request will list all tests.

Request parameters:

query
Optional
Filter tests by query
count
Optional
Maximum number of tests to get. Default: `10`, Max: `100`
page
Optional
Number of the page to fetch, starting with `1`. Default: `1`

Response structure

page.number
Type: Number Content: Standard
Number of the current page
page.size
Type: Number Content: Standard
Maximum number of elements for a page
page.totalElements
Type: Number Content: Standard
Total number of candidates matching criteria
page.totalPages
Type: Number Content: Standard
Total number of pages matching criteria
_embedded.tests
Type: Array Content: Standard
Arrays of tests
_embedded.tests[].id
Type: String Content: Standard
Test id
_embedded.tests[].name
Type: String Content: Standard
Test name
_embedded.tests[].skills
Type: Array Content: Standard
List of skills verified in the test
_embedded.tests[].durationInMinutes
Type: Number Content: Standard
Test duration in minutes

Creating a test using a predefined test

Request

POST /tests HTTP/1.1
Content-Type: application/vnd.devskiller.v2.hal+json
Devskiller-Api-Key: TEST-API-KEY
Accept: application/vnd.devskiller.v2.hal+json
Host: api.devskiller.com

{
    "predefinedTestId": "4pMQiiqQ7o5XfM2MekmEiq"
}
$ curl 'https://api.devskiller.com/tests' -i -X POST \
    -H 'Content-Type: application/vnd.devskiller.v2.hal+json' \
    -H 'Devskiller-Api-Key: TEST-API-KEY' \
    -H 'Accept: application/vnd.devskiller.v2.hal+json' \
    -d '{
    "predefinedTestId": "4pMQiiqQ7o5XfM2MekmEiq"
}'

Response

HTTP/1.1 201 Created
Location: https://api.devskiller.com/tests/d2d55c15-cb0e-4328-8699-ad957ba239c5
Content-Type: application/vnd.devskiller.v2.hal+json;charset=UTF-8

{
  "id" : "d2d55c15-cb0e-4328-8699-ad957ba239c5",
  "name" : "Senior Java Developer",
  "skills" : [ "Java", "SQL" ],
  "durationInMinutes" : 60,
  "_links" : {
    "self" : {
      "href" : "https://api.devskiller.com/tests/d2d55c15-cb0e-4328-8699-ad957ba239c5"
    }
  }
}
{
  "id" : "d2d55c15-cb0e-4328-8699-ad957ba239c5",
  "name" : "Senior Java Developer",
  "skills" : [ "Java", "SQL" ],
  "durationInMinutes" : 60,
  "_links" : {
    "self" : {
      "href" : "https://api.devskiller.com/tests/d2d55c15-cb0e-4328-8699-ad957ba239c5"
    }
  }
}

POST /tests

A POST request is used to create a test.

Request Body:

predefinedTestId
Type: String Required if there are no generatorCriteria
The id of the predefined tests which should be used as the template for the new test

Response Headers:

Location
URI of the created test

Creating a test using generator

Request

POST /tests HTTP/1.1
Content-Type: application/vnd.devskiller.v2.hal+json;charset=UTF-8
Devskiller-Api-Key: TEST-API-KEY
Accept: application/vnd.devskiller.v2.hal+json
Host: api.devskiller.com

{
    "generatorCriteria": {
        "skills": [
            "Java"
        ],
        "difficulties": [
            "EASY",
            "MEDIUM",
            "HARD"
        ],
        "taskTypes": [
            "MULTI_CHOICE",
            "PROGRAMMING",
            "SQL",
            "DEVOPS"
        ]
    }
}
$ curl 'https://api.devskiller.com/tests' -i -X POST \
    -H 'Content-Type: application/vnd.devskiller.v2.hal+json;charset=UTF-8' \
    -H 'Devskiller-Api-Key: TEST-API-KEY' \
    -H 'Accept: application/vnd.devskiller.v2.hal+json' \
    -d '{
    "generatorCriteria": {
        "skills": [
            "Java"
        ],
        "difficulties": [
            "EASY",
            "MEDIUM",
            "HARD"
        ],
        "taskTypes": [
            "MULTI_CHOICE",
            "PROGRAMMING",
            "SQL",
            "DEVOPS"
        ]
    }
}'

Response

HTTP/1.1 201 Created
Location: https://api.devskiller.com/tests/d2d55c15-cb0e-4328-8699-ad957ba239c5
Content-Type: application/vnd.devskiller.v2.hal+json;charset=UTF-8

{
  "id" : "d2d55c15-cb0e-4328-8699-ad957ba239c5",
  "name" : "Middle Java",
  "skills" : [ "Java" ],
  "durationInMinutes" : 40,
  "_links" : {
    "self" : {
      "href" : "https://api.devskiller.com/tests/d2d55c15-cb0e-4328-8699-ad957ba239c5"
    }
  }
}
{
  "id" : "d2d55c15-cb0e-4328-8699-ad957ba239c5",
  "name" : "Middle Java",
  "skills" : [ "Java" ],
  "durationInMinutes" : 40,
  "_links" : {
    "self" : {
      "href" : "https://api.devskiller.com/tests/d2d55c15-cb0e-4328-8699-ad957ba239c5"
    }
  }
}

POST /tests

A POST request is used to create a test.

Request Body:

generatorCriteria
Type: Object Required if predefinedTestId is not specified
The criteria that will be used to generate a new test by randomly choosing tasks matching criteria
generatorCriteria.skills
Type: Array Required
The list of skills that should be tested by a generated test
generatorCriteria.difficulties
Type: Array Optional
The list of allowed difficulties (possible values: EASY, MEDIUM, HARD)
generatorCriteria.taskTypes
Type: Array Optional
The list of allowed task types (possible values: MULTI_CHOICE,ESSAY,PROGRAMMING,CODE_REVIEW,SQL,DEVOPS,CODE_GAPS,TESTING)

Response Headers:

Location
URI of the created test

Predefined Tests

The Predefined Tests resources is used to list predefined test

List predefined tests

Request

GET /predefined-tests?query=implement&skills=Java&skills=SQL&seniorityLevels=JUNIOR&seniorityLevels=MIDDLE&count=10&page=1 HTTP/1.1
Devskiller-Api-Key: TEST-API-KEY
Accept: application/vnd.devskiller.v2.hal+json
Host: api.devskiller.com

$ curl 'https://api.devskiller.com/predefined-tests?query=implement&skills=Java&skills=SQL&seniorityLevels=JUNIOR&seniorityLevels=MIDDLE&count=10&page=1' -i -X GET \
    -H 'Devskiller-Api-Key: TEST-API-KEY' \
    -H 'Accept: application/vnd.devskiller.v2.hal+json'

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.devskiller.v2.hal+json;charset=UTF-8

{
  "_embedded" : {
    "predefinedTests" : [ {
      "id" : "f3f7c764-992e-497a-9b3c-6b9d13a80356",
      "name" : "Senior Java Developer",
      "seniorityLevel" : "SENIOR",
      "skills" : [ "Java" ],
      "durationInMinutes" : 30,
      "_links" : {
        "self" : {
          "href" : "https://api.devskiller.com/predefined-tests/f3f7c764-992e-497a-9b3c-6b9d13a80356"
        }
      },
      "description" : "Test for senior java developer"
    } ]
  },
  "page" : {
    "size" : 1,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 1
  }
}
{
  "_embedded" : {
    "predefinedTests" : [ {
      "id" : "f3f7c764-992e-497a-9b3c-6b9d13a80356",
      "name" : "Senior Java Developer",
      "seniorityLevel" : "SENIOR",
      "skills" : [ "Java" ],
      "durationInMinutes" : 30,
      "_links" : {
        "self" : {
          "href" : "https://api.devskiller.com/predefined-tests/f3f7c764-992e-497a-9b3c-6b9d13a80356"
        }
      },
      "description" : "Test for senior java developer"
    } ]
  },
  "page" : {
    "size" : 1,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 1
  }
}

GET /predefinedTests

A GET request will list all predefined tests.

Request parameters:

query
Optional
Search by name, description or skills
skills
Optional
Filter tests by skills. Add multiple skills parameters to search for several skills.
seniorityLevels
Optional
Filter tests by seniority level. Add multiple parameters to search for several seniority levels. Valid values: JUNIOR, MIDDLE, SENIOR
count
Optional
Maximum number of tests to get. Default: `10`, Max: `100`
page
Optional
Number of the page to fetch, starting with `1`. Default: `1`

Response structure

page.number
Type: Number Content: Standard
Number of the current page
page.size
Type: Number Content: Standard
Maximum number of elements for a page
page.totalElements
Type: Number Content: Standard
Total number of candidates matching criteria
page.totalPages
Type: Number Content: Standard
Total number of pages matching criteria
_embedded.predefinedTests
Type: Array Content: Standard
Arrays of tests
_embedded.predefinedTests[].id
Type: String Content: Standard
Predefined test id
_embedded.predefinedTests[].name
Type: String Content: Standard
Predefined test name
_embedded.predefinedTests[].description
Type: String Content: Standard
Predefined test description
_embedded.predefinedTests[].durationInMinutes
Type: Number Content: Standard
Predefined test duration (in minutes)
_embedded.predefinedTests[].skills
Type: Array Content: Standard
List of skills verified in the test
_embedded.predefinedTests[].seniorityLevel
Type: String Content: Standard
Predefined test seniority level (JUNIOR, MIDDLE or SENIOR)

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 here the webhook secret which is used to secure all requests sent by Devskiller. The secret is always passed in the "Devskiller-Hook-Secret" header.

Receive push notification

Request

POST /devskillerWebhooks HTTP/1.1
Content-Type: application/vnd.devskiller.v2.hal+json
Devskiller-Hook-Secret: TEST-SECRET
User-Agent: Devskiller
Host: api.yourdomain.com

[
    {
        "candidateId": "1024138f-684f-4311-b539-774fd3ef3a9c",
        "candidateExternalId": "553c8ceb",
        "assessmentId": "90224982-2017-4098-bfc8-48f7b60ec01d",
        "candidateEmail": "test@email.com",
        "testId": "70Wvi8uyl9mFFM4xuVdI5o",
        "examName": "Senior Java Developer",
        "event": "ASSESSMENT_COMPLETED",
        "_links": {
            "candidate": {
                "href": "https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c"
            },
            "assessment": {
                "href": "https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/assessments/90224982-2017-4098-bfc8-48f7b60ec01d"
            },
            "invitation": {
                "href": "https://api.devskiller.com/invitations/90224982-2017-4098-bfc8-48f7b60ec01d"
            }
        }
    }
]
$ curl 'https://api.yourdomain.com/devskillerWebhooks' -i -X POST \
    -H 'Content-Type: application/vnd.devskiller.v2.hal+json' \
    -H 'Devskiller-Hook-Secret: TEST-SECRET' \
    -H 'User-Agent: Devskiller' \
    -d '[
    {
        "candidateId": "1024138f-684f-4311-b539-774fd3ef3a9c",
        "candidateExternalId": "553c8ceb",
        "assessmentId": "90224982-2017-4098-bfc8-48f7b60ec01d",
        "candidateEmail": "test@email.com",
        "testId": "70Wvi8uyl9mFFM4xuVdI5o",
        "examName": "Senior Java Developer",
        "event": "ASSESSMENT_COMPLETED",
        "_links": {
            "candidate": {
                "href": "https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c"
            },
            "assessment": {
                "href": "https://api.devskiller.com/candidates/1024138f-684f-4311-b539-774fd3ef3a9c/assessments/90224982-2017-4098-bfc8-48f7b60ec01d"
            },
            "invitation": {
                "href": "https://api.devskiller.com/invitations/90224982-2017-4098-bfc8-48f7b60ec01d"
            }
        }
    }
]'

POST https://your_endpoint_address_here

A POST request will push events to your endpoint.

If your endpoint responded 4xx or 5xx Devskiller will retry the request with a given schedule:

Request headers

Name Description
Devskiller-Hook-Secret The webhook secret key

Request structure

[]
Type: Array Always
Array of the events
[].candidateId
Type: String Always
The candidate's id
[].candidateExternalId
Type: String If used
The candidate's external id
[].assessmentId
Type: String If used
The assessment id
[].candidateEmail
Type: String Always
The candidate's email
[].testId
Type: String Always
The id of the test
[].examName
Type: String Always
The name of the exam
[].event
Type: String Always
Event type status. Possible values: WAITING_FOR_ASSESSMENT, ASSESSMENT_STARTED, ASSESSMENT_COMPLETED, ASSESSMENT_EXPIRED, ERROR
[]._links.candidate.href
Type: String Always
Link to the candidate
[]._links.assessment.href
Type: String Always
Link to the assessment
[]._links.invitation.href
Type: String Always
Link to the invitation

Errors

Response

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 245

{
  "code" : 400,
  "errorId" : "c31038ef-6843-4323-9a8d-8029b5e30e33",
  "details" : "Validation error",
  "validationErrors" : [ {
    "field" : "email",
    "value" : "incorrect mail",
    "message" : "not a well-formed email address"
  } ]
}
{
  "code" : 400,
  "errorId" : "c31038ef-6843-4323-9a8d-8029b5e30e33",
  "details" : "Validation error",
  "validationErrors" : [ {
    "field" : "email",
    "value" : "incorrect mail",
    "message" : "not a well-formed email address"
  } ]
}

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:

code
Type: Number Content: Standard
Error code
errorId
Type: String Content: Standard
Unique error id, you can use it when contacting with us
details
Type: String Content: Standard
Error description
validationErrors
Type: Array Content: Standard
Validation errors details
validationErrors[].field
Type: String Content: Standard
Name of the field
validationErrors[].value
Type: String Content: Standard
Rejected value
validationErrors[].message
Type: String Content: Standard
Message

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