Book a demo
Sign Up
Integrations

REST API Reference

The conventions shared by every REST API endpoint — authentication, the basic/detailed response toggle, and how List, Fetch, and Search differ — plus where to find each resource's specific endpoints.

Published 2026/08/26

Every REST API endpoint shares the same base URL, the same authentication, and one of a small number of repeating patterns. Learn these once here, and each resource page below only needs to cover what's actually specific to it.

Base URL & Authentication

Every endpoint is under https://www.testinvite.com/api/integration/rest/v1. Every request needs an Authorization header set to your access key's authorization token — see Enabling the API for where to get one:

  • GET /api/integration/rest/hello-world — a no-op endpoint to verify your token works before building anything real against it.

basic vs. detailed

Every List, Fetch, and Search endpoint accepts a mode query parameter: basic (default) or detailed. Detailed always returns everything basic does, plus the resource's full fields — request it only when you need those extra fields, since it's a heavier response.

List, Fetch, and Search

Every resource offers the same three ways to read it:

  • List — GET the resource's root path. Simple filters go in the query string; returns a paginated array.
  • Fetch one — GET .../:id. No filters, just mode; returns a single object.
  • Search — POST .../filter. Richer filters go in the JSON body (arrays, booleans, multiple conditions, all AND-combined) — use this whenever a query string can't express what you need. Same paginated response shape as List.

Pagination — Two Different Models

Most List and Search endpoints use offset pagination: pass page and limit (default 10) query parameters, and the response includes { totalItems, totalPages, currentPage, limit, next, previous }.

Searching Test Sessions & Results is the one exception — it uses cursor pagination instead: pass limit and, for subsequent pages, lastDocId from the previous response. The response includes { limit, lastDocId, next }, where next is a ready-to-use query string for the following page. This is called out again on that endpoint's own page — it's easy to assume every endpoint paginates the same way and get a confusing result if you don't check.

Expand — Optional Extra Fields

Users and Test Sessions & Results additionally offer an expand endpoint: POST .../:id/expand with a body of { expand: [...] } naming which optional fields to include. These are fields expensive or unusual enough that they're never included even in detailed mode — you opt into exactly the ones you need.

* * *

In This Section

In this section

Tasks List, fetch, search, and update Tasks through the REST API — including the beta Update endpoint's field constraints and per-step overrides. Tests List, fetch, and search Tests through the REST API — tests are read-only via this API; author and edit them in the Test editor. Users List, fetch, search, and expand Users through the REST API — teammates and learners across your whole organization, not scoped to a single task. Candidates Create, list, fetch, update, and delete Candidates under a Task through the REST API — the only resource with full write access, since registering candidates is the core integration use case. Test Sessions & Results Read test sessions and their results through the REST API — the richest resource in the API, with score breakdowns by section, dimension, and effect, plus proctoring evidence and answer sub-resources. Integration Workflow The typical end-to-end integration: create a candidate, get them into the task, and learn how their session went — usually just two round trips per candidate. Webhooks & Callbacks Get notified the moment a candidate finishes, instead of polling for results — set a callback URL when you create the candidate and TestInvite posts the result to it automatically.

The REST API uses standard HTTP status codes — 2xx for success, 4xx when the request itself is the problem, 5xx when TestInvite's the problem.

The TestInvite REST API Postman collection includes a ready request for every endpoint documented here, with example bodies, query parameters, and placeholder values like <task-id> and <your-authorization-token> — swap those for your own values and adjust the body to match what you actually need.