How to send a candidate testing invitation via API

The POST /api/v1/tests/invitations/candidates endpoint creates an HR testing invitation for a candidate. The request body must include first name, surname, email, gender and a list of testIds; sendCopyToHr is optional. The lang parameter controls the invitation email language and the language of the test-taking link.

Which endpoint is used?

Use POST /api/v1/tests/invitations/candidates. The endpoint creates a candidate invitation to take one or more tests.

What is this API endpoint used for?

This endpoint is used to send an HR testing invitation to a candidate. It is used in recruitment integrations when an external system sends candidate data and the list of tests to be taken.

What prerequisites are required before sending the request?

• A Bearer token with company context is required.

• The token must include the tests.write scope.

• At least one active testId available to the current company is required.

Which parameters must be sent in the request?

Headers

Path parameters

Path parameters are absent.

Query parameters

Request body

curl example

curl -X POST 'https://smartway.pro/api/v1/tests/invitations/candidates?lang=en' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Ivan",
    "surname": "Petrenko",
    "email": "candidate@company.test",
    "gender": "Male",
    "testIds": [5, 200001],
    "sendCopyToHr": true
  }'

What response does the API return?

A successful request returns 202 Accepted.

What happens under the hood?

• idCompany is not sent in the body or query string: it is taken from the Bearer token.

• hrEmail is not sent by the external client: it is taken from the Bearer token.

• lang accepts only uk, ru, en; if it is not sent or the value is unsupported, the invitation is sent in English (en).

• gender accepts only Male or Female.

• testIds must contain at least one element.

• Before creating the invitation, the server checks each testId: the test must exist and be active.

• If the request contains multiple invalid testIds, the API returns one 400 Bad Request listing all problematic elements.

• Access requires the tests.write scope.

Which edge cases should be considered?

Which errors can the API return?

Error response example:

{
  "type": "https://smartway.pro/problems/public-api",
  "title": "Bad Request",
  "status": 400,
  "detail": "Candidate invitation contains invalid testIds: testId 2 does not exist; testId 3 is inactive.",
  "instance": "/api/v1/tests/invitations/candidates"
}

How to use the result in subsequent API requests?

Before creating the invitation, retrieve available testId values through the test catalogue. Send the returned testIds in the request body as the testIds array.

Example of getting the test catalogue before creating an invitation:

curl -X GET 'https://smartway.pro/api/v1/tests' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json'

Which mistakes should integrators avoid?

• Sending idCompany or hrEmail in the body.

• Sending gender values other than Male or Female.

• Sending an empty testIds array.

• Using inactive or non-existent testIds.

• Expecting an error for unsupported lang, although the API uses en.

FAQ

Which status is returned after a successful invitation?

The API returns 202 Accepted.

Do I need to send idCompany?

No. idCompany is taken from the Bearer token.

Where does HR email come from?

hrEmail is taken from the Bearer token; the external client does not send it.

Which values does gender support?

Only Male and Female are allowed.

What happens if several testIds are invalid?

The API returns one 400 Bad Request with all problematic elements listed.