How to send employee testing invitations via API

The POST /api/v1/tests/invitations/employees endpoint sends testing invitations to employees in bulk. The request body must include non-empty employeeIds and testIds arrays. The lang parameter controls the invitation email language and the language of test-taking links.

Which endpoint is used?

Use POST /api/v1/tests/invitations/employees. The endpoint sends testing invitations to a list of employees.

What is this API endpoint used for?

This endpoint is used to send testing invitations in bulk to company employees. It is used in HR integrations when an external system has a list of employees and a list of tests.

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 employeeId within the current company is required.

• At least one testId 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/employees?lang=en' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "employeeIds": [101, 102],
    "testIds": [5, 200001]
  }'

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, invitations are sent in English (en).

• employeeIds and testIds must contain at least one element.

• If at least one employee is absent within the current company, the API returns 404 Not Found.

• Access requires the tests.write scope.

Which edge cases should be considered?

Which errors can the API return?

How to use the result in subsequent API requests?

Before sending invitations in bulk, retrieve available testId values through the test catalogue. Send employees in employeeIds and tests in testIds.

Example of getting the test catalogue:

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 empty employeeIds or testIds arrays.

• Sending employeeIds that do not belong to the current company.

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

• Calling the endpoint without the tests.write scope.

FAQ

Which status is returned after a successful bulk send?

The API returns 202 Accepted.

Do I need to send idCompany?

No. idCompany is taken from the Bearer token.

What happens if one employee is not found?

The API returns 404 Not Found if at least one employee is not found within the current tenant.

Which arrays are required?

Non-empty employeeIds and testIds are required.

Which scope is required?

The tests.write scope is required.