Як надіслати кандидату запрошення на тестування через API

Endpoint POST /api/v1/tests/invitations/candidates створює HR-запрошення кандидату на тестування. У body потрібно передати ім’я, прізвище, email, gender і список testIds; sendCopyToHr є необов’язковим. Параметр lang керує мовою листа-запрошення і мовою посилання на проходження тесту.

Який endpoint використовується?

Використовується POST /api/v1/tests/invitations/candidates. Endpoint створює запрошення кандидату на проходження одного або кількох тестів.

Для чого використовується цей API endpoint?

Endpoint використовується для надсилання HR-запрошення кандидату на тестування. Його застосовують у рекрутингових інтеграціях, коли зовнішня система передає кандидата та список тестів для проходження.

Які передумови потрібні перед виконанням запиту?

• Потрібен Bearer token з company context.

• Token має містити scope tests.write.

• Потрібен хоча б один активний testId, доступний поточній компанії.

Які параметри потрібно передати в запиті?

Headers

Path parameters

Path parameters відсутні.

Query parameters

Request body

curl приклад

curl -X POST 'https://smartway.pro/api/v1/tests/invitations/candidates?lang=uk' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Іван",
    "surname": "Петренко",
    "email": "candidate@company.test",
    "gender": "Male",
    "testIds": [5, 200001],
    "sendCopyToHr": true
  }'

Яку відповідь повертає API?

Успішний запит повертає 202 Accepted.

Що відбувається під капотом?

• idCompany не передається у body або query string: його буде взято з Bearer token.

• hrEmail не передається зовнішнім клієнтом: його буде взято з Bearer token.

• lang приймає лише uk, ru, en; якщо параметр не передано або значення не підтримується, запрошення надсилається англійською (en).

• gender приймає лише Male або Female.

• testIds має містити хоча б один елемент.

• Перед створенням запрошення сервер перевіряє кожен testId: тест має існувати та бути активним.

• Якщо в запиті є кілька невалідних testIds, API повертає одну 400 Bad Request з переліком усіх проблемних елементів.

• Для доступу потрібен scope tests.write.

Які edge cases потрібно врахувати?

Які помилки може повернути API?

Приклад error response:

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

Як використовувати результат у наступних API-запитах?

Перед створенням запрошення отримайте доступні testId через каталог тестів. Отримані testIds передавайте в body запиту у масиві testIds.

Приклад отримання каталогу тестів перед створенням запрошення:

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

Яких помилок інтегратору варто уникати?

• Передавати idCompany або hrEmail у body.

• Передавати gender у значеннях, відмінних від Male або Female.

• Передавати порожній testIds.

• Використовувати неактивні або неіснуючі testIds.

• Очікувати помилку для непідтримуваного lang, хоча API використовує en.

FAQ

Який status повертається при успішному створенні запрошення?

API повертає 202 Accepted.

Чи потрібно передавати idCompany?

Ні. idCompany буде взято з Bearer token.

Звідки береться HR email?

hrEmail буде взято з Bearer token; зовнішній клієнт його не передає.

Які значення підтримує gender?

Допустимі лише Male або Female.

Що буде, якщо кілька testIds невалідні?

API поверне одну 400 Bad Request з переліком усіх проблемних елементів.