How to get a list of testing reports via API

Short answer

The POST /api/v1/tests/reports/search endpoint returns testing reports with the current saved filter applied. All request body fields are optional; without a body, the API uses page = 0, size = 50 and view = all. Access requires a Bearer token with the tests.read scope, and lang can control the language of localised testing resources.

Which endpoint is used?

Use POST /api/v1/tests/reports/search. The endpoint returns a page of company testing reports with the current saved filter applied.

What is this API endpoint used for?

This endpoint is used to retrieve company testing reports with pagination, view mode and full-name search. It is used by HR integrations, backend services and technical administrators to build report lists and open PDF reports.

What prerequisites are required before sending the request?

• A Bearer token with company context is required.

• The token must include the tests.read scope.

• The current saved filter must be considered or reset before retrieving the required data.

Which parameters must be sent in the request?

Headers

Path parameters

Path parameters are absent.

Query parameters

Request body

curl example

Example request without body:

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

Example request with parameters:

curl -X POST 'https://smartway.pro/api/v1/tests/reports/search?lang=en' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "page": 0,
    "size": 20,
    "view": "all",
    "query": "Ivan"
  }'

What response does the API return?

A successful request returns 200 OK and a PublicTestReportListResponse object with reports and pagination metadata.

{
  "data": [
    {
      "uniqueId": "abc12345",
      "candidateId": 1001,
      "name": "Ivan Petrenko",
      "dateSend": "2026-03-10",
      "dateReceipt": "2026-03-12",
      "active": true,
      "testNames": "Conflict Test, Adaptive Sales",
      "department": "Sales",
      "jobTitle": "Manager"
    }
  ],
  "meta": {
    "page": 0,
    "size": 20,
    "totalElements": 1,
    "totalPages": 1,
    "hasNext": false
  }
}

What do the API response fields mean?

What happens under the hood?

• Tenant visibility of reports is determined server-side from companyId in the Bearer token as company-level / HRADMIN-equivalent scope.

• Reporting is not limited to candidates invited via the current API key or the HR owner of the key.

• The API returns all company testing reports available at HRADMIN level.

• The current saved filter from GET/PUT /api/v1/tests/reports/filter is additionally applied: active, startDate, endDate, testIds, departments, jobTitles.

• lang is optional; if it is not sent, the API uses en.

• Access requires the tests.read scope.

Which edge cases should be considered?

Which errors can the API return?

How to use the result in subsequent API requests?

Use meta.page, meta.size, meta.totalPages and meta.hasNext for pagination. Use uniqueId from the list to download a PDF report.

Example subsequent request to download a PDF report:

curl -X GET 'https://smartway.pro/api/v1/tests/reports/pdf?uniqueId=abc12345&lang=en' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/pdf' \
  --output test-report-abc12345.pdf

Which mistakes should integrators avoid?

• Treating page = 1 as the first page.

• Ignoring the active saved filter before search.

• Sending a view value other than all, candidate or employee.

• Expecting the API to return only reports for candidates invited via the current API key.

FAQ

Is request body required?

No. If the endpoint is called without a body, the API uses page = 0, size = 50 and view = all.

Which page number starts pagination?

page is 0-based: page = 0 is the first page and page = 1 is the second page.

Which values does view support?

Only all, candidate and employee are allowed.

Is the saved filter applied?

Yes. The filter from GET/PUT /api/v1/tests/reports/filter is applied additionally.

Which scope is required?

The tests.read scope is required.