Главная API Как отправить кандидату приглашение на тестирование через API

Как отправить кандидату приглашение на тестирование через API

Обновлено Apr 28, 2026

Endpoint POST /api/v1/tests/invitations/candidates создаёт HR-приглашение кандидату на тестирование. В body нужно передать имя, фамилию, email, gender и список testIds; sendCopyToHr является необязательным. Параметр lang управляет языком письма-приглашения и языком ссылки на прохождение теста.

Какой endpoint используется?

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

Параметр Значение
Method POST
Endpoint /api/v1/tests/invitations/candidates
Base URL [https://smartway.pro](https://smartway.pro)
Auth Bearer token
Content-Type application/json

Для чего используется этот API endpoint?

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

Какие предварительные условия нужны перед выполнением запроса?

  • Нужен Bearer token с company context.

  • Token должен содержать scope tests.write.

  • Нужен хотя бы один активный testId, доступный текущей компании.

Предусловие Описание Обязательно
access_token Bearer token с company context Да
tests.write Scope для создания приглашения Да
testIds Список ID активных тестов Да

Какие параметры нужно передать в запросе?

Headers

Header Тип Обязательно Описание
Authorization string Да Bearer token в формате Bearer <access_token>
Accept string Да application/json
Content-Type string Да application/json

Path parameters

Path parameters отсутствуют.

Query parameters

Параметр Тип Обязательно Описание
lang string Нет Язык приглашения. Поддерживаются uk, ru, en. Если параметр отсутствует или передано другое значение, сервер использует en.

Request body

Параметр Тип Обязательно Описание
name string Да Имя кандидата
surname string Да Фамилия кандидата
email string Да Email кандидата
gender string Да Допустимы только значения Male или Female
testIds int64[] Да Список ID тестов; должен содержать хотя бы один элемент
sendCopyToHr boolean Нет Если true, сервер дополнительно отправляет копию приглашения на HR email из токена

curl-пример

curl -X POST 'https://smartway.pro/api/v1/tests/invitations/candidates?lang=ru' \
  -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 Что сделать интегратору
lang отсутствует или не поддерживается Сервер использует en Передавать uk, ru или en, если нужен конкретный язык
gender не Male или Female API возвращает 400 Bad Request Передавать только Male или Female
testIds пустой API возвращает 400 Bad Request Передавать хотя бы один testId
Один или несколько testIds не существуют либо неактивны API возвращает один 400 Bad Request с перечнем всех проблемных testId Предварительно проверять testIds через каталог или детали теста

Какие ошибки может вернуть API?

HTTP status Описание
400 Bad Request Отсутствует required-параметр, gender не равен Male / Female, или хотя бы один testId не существует либо неактивен
401 Unauthorized Отсутствует или невалидный Bearer token
403 Forbidden Недостаточно прав
500 Internal Server Error Неожиданная ошибка
503 Service Unavailable Сбой сервиса

Пример 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 с перечнем всех проблемных элементов.