Core Concepts

Every integration call is really just reading or writing one of a handful of concepts. Getting these straight first makes every endpoint in the REST API Reference self-explanatory.

Organization

Your account. Every API call is scoped to your organization — you never see or touch another organization's data.

Task

The delivery vehicle for one or more tests — see Tasks Overview for the full concept. Most integration calls need a Task ID: you create candidates under a specific task, and you read test sessions and results from a specific task.

Test

The actual assessment content — questions, structure, and scoring. A Task references one or more tests as its steps; the REST API lets you read test metadata, but tests are authored and edited in the Question Bank and Test editor, not through the API.

Candidate

A person invited to a task. Candidates are always scoped to one task — there's no organization-wide candidate list, only a per-task one. Creating a candidate through the API is how you get someone into a task programmatically; each candidate gets an invitation code and, depending on the task's access method, a direct access link that skips the login page entirely.

Test Instance

One candidate's attempt at one test — created the moment they start. A candidate can have more than one test instance if the task has multiple steps or allows retakes. Status is one of Started, Complete, or Resetup (reinstated by an admin). Results — score, section/dimension breakdowns — live on the test instance, not on the candidate.

The hierarchy to keep in mind: an Organization has Tasks; a Task has Candidates and references Tests; a Candidate produces Test Instances as they work through the task's steps.

Good to know