Using the API to Deliver Assessments in Your Own Application

This functionality will be avaiable from Monday November 2, 2026 (UK, US time)  

Overview

Brilliant Assessments provides a set of Assessment Delivery APIs that allow developers to build their own assessment response screens within their applications, websites, or other systems.

Previously, API integrations allowed developers to create assessment responses, direct respondents to Brilliant Assessments to complete their assessments, and retrieve the completed results.

The Assessment Delivery APIs extend this functionality, allowing respondents to complete assessments entirely within your own application, without using the standard Brilliant Assessments response screens.

Your application controls the user interface, while Brilliant Assessments continues to manage the assessment structure, navigation rules, answer validation, scoring, feedback, and reporting.

This is particularly useful for organizations wanting to embed assessments seamlessly into their existing applications or provide a fully customized respondent experience.

To help developers get started, we have developed a simple sample application demonstrating how the APIs work together. The sample application and its source code are available on request from Brilliant Assessments Support.

Full technical documentation for all API endpoints is available in our Swagger API Documentation.

How Assessment Delivery Works

The Assessment Delivery APIs work alongside the existing API V2 endpoints to support the complete assessment process.

The typical process is:

1. Identify the assessment and create a response.
2. Retrieve the assessment's presentation information and questions.
3. Display questions and collect answers within your application.
4. Submit answers and navigate through the assessment.
5. Complete the response and initiate scoring and reporting.
6. Retrieve the completed results.

The following sections explain each step. For full endpoint definitions, request parameters, response models, and examples, refer to the Swagger API Documentation.

Step 1: Identify the Assessment and Create a Response

List available assessments (New API)

GET /api/v2/assessments

Returns the assessments available to your API key, including their External IDs, availability windows, and whether they can be delivered using the Assessment Delivery APIs.

Some assessments may use functionality that requires the standard Brilliant Assessments response screens. These will be identified as not deliverable, with a reason provided. Offer only deliverable assessments in your application. For the others, create the response with the existing Create Response API (Option A below) and send the respondent to the responseUrl it returns, which opens the standard Brilliant Assessments response screen.

Create a response

There are two ways to create a response.

Option A: Existing Create Response API

POST /api/v2/responses

Use this API when you want to create a response with respondent details such as name, email address, organization information, or classifiers. First name, last name and email address are required, and the respondent is sent the assessment's welcome email unless you set suppressWelcomeEmail.

This is the existing API V2 endpoint and remains available.

Option B: New Assessment Delivery API

POST /api/v2/assessments/{externalId}/responses

Creates a new anonymous response and returns its ResponseID together with the assessment's presentation information and section structure.

Respondent details are collected through the assessment's own questions. You can also pass an organization path and classifiers when creating the response.

Both methods create a response within Brilliant Assessments that can be used with the Assessment Delivery APIs.

Important: Store the returned ResponseID. This identifies the response throughout the assessment process and is needed to resume an incomplete assessment.

Step 2: Retrieve the Assessment Structure and Questions

Retrieve assessment presentation information (New API)

GET /api/v2/responses/{id}/background

Returns the information needed to construct the assessment's response screens, including presentation settings, button text, and section structure.

This is particularly useful when using the existing Create Response API or resuming an assessment.

Retrieve questions (New API)

POST /api/v2/responses/{id}/questions

Returns the questions to be presented at the current navigation step, including the information needed to display the questions and available answers.

Rather than requiring your application to interpret the entire assessment structure and determine which questions should be displayed, Brilliant Assessments manages the assessment navigation and provides the appropriate questions.

Your application is responsible for displaying these questions using its own interface. This includes showing and hiding questions as the respondent answers: each question is returned with its display conditions, together with the answers already given elsewhere in the assessment that those conditions may depend on.

Step 3: Collect Answers and Navigate Through the Assessment

The same Questions API is used to save answers and navigate through the assessment.

POST /api/v2/responses/{id}/questions

The API supports navigation commands including:

• Current questions
• Next or previous section
• Next or previous subsection
• Next or previous question group
• Navigation to a specified section or subsection
• Save answers without navigating

Your application submits the respondent's answers together with the required navigation command. Use the Next and Previous commands that match the assessment's page structure (responseStructure in the presentation information), and show a Previous button only when the assessment allows it (showPreviousButton). Other commands are refused.

Brilliant Assessments validates the answers against the assessment's rules, including mandatory questions, permitted answer values, and answer types.

If validation fails, the API returns details of the problem so that your application can display an appropriate message to the respondent. The details include a code (for example RequiredUnanswered) and the IDs of the questions concerned. Nothing is saved when a page is refused.

Important: When saving a page of answers, submit the complete set of answers for that page, not just the answers that have changed. The submitted answers replace the previously stored answers for that page. This includes answers the respondent did not type, such as default answers and answers to questions hidden from the respondent: the API returns them as saved answers, and they are kept only if you submit them.

The API also returns previously saved answers when revisiting questions, allowing your application to prepopulate the response screens.

Step 4: Resume an Incomplete Assessment

The APIs support respondents returning to an assessment they have already started.

List in-progress responses

GET /api/v2/assessments/{externalId}/responses

Returns in-progress responses for the selected assessment, subject to the access permissions of the API key.

To resume a response:

1. Identify the appropriate ResponseID.
2. Retrieve its presentation information using the Background API.
3. Call the Questions API with the Current navigation command.

The API returns the relevant question group and saved answers so the respondent can continue.

Your application is responsible for identifying the correct respondent and ensuring that they can only access their own response.

Step 5: Complete the Assessment

Complete response (New API)

POST /api/v2/responses/{id}/complete

Once the respondent has reached the end of the assessment, call this API to complete the response. The end is reached when a navigation step returns no question group and no questions. A page that has a question group but no questions (for example, an empty section) is not the end: move on with Next.

Brilliant Assessments then initiates the configured completion processing, which may include:

• Scoring and calculations
• AI interpretations
• Feedback and report generation
• Certificates
• Completion emails

These activities are processed in the background. Calling the Complete Response API again is safe: it reports that the response is already complete and does not repeat the processing.

The API will not allow an assessment to be completed prematurely while questions remain ahead in the assessment flow.

Retrieve completion screen information (New API)

GET /api/v2/responses/{id}/completion

Returns the information configured for the assessment's completion screen, including thank-you content and any return action.

Your application can use this information to display its own completion screen.

Retrieving the completion screen does not itself complete the response. The Complete Response API must be called separately.

Step 6: Retrieve Results and Reports

Once the assessment has been completed, your application can retrieve the results using the existing API V2 functionality or the new, more specialized endpoints.

Existing API

GET /api/v2/responses/{id}

Returns the completed response data, including answers, scores, ratings, and other response information.

Additional Assessment Delivery APIs

The endpoints in this table use the /api/v2 prefix.

These APIs allow developers to incorporate assessment results into their own applications while retaining Brilliant Assessments' scoring and reporting capabilities.

Additional Functionality

The Assessment Delivery APIs also provide functionality for more specialized assessment requirements.

File Uploads

The APIs support uploading files in response to questions configured for image, video, or document uploads.

POST /api/v2/responses/{id}/questions/{questionId}/content

Additional endpoints allow uploaded files to be retrieved or deleted.

Timed Assessments

For assessments with time limits, the APIs provide information about the time remaining.

GET /api/v2/responses/{id}/time

This allows your application to display countdown timers while Brilliant Assessments maintains the assessment's timing rules.

Assessment Presentation

The APIs provide access to presentation information and graphics used by the assessment.

Developers can use these settings to reproduce aspects of the assessment's configured appearance or apply their own styling. Images such as header and footer logos are retrieved with GET /api/v2/responses/graphics/{id}.

Standard vs Custom Assessment Delivery

Both approaches use the same Brilliant Assessments platform. The key difference is who provides the respondent-facing screens.

Authentication and API Access

The Assessment Delivery APIs are part of API V2 and use the same authentication mechanism as the existing APIs.

Every API request requires two headers:

API keys are configured under:

Administer > Site Settings > Integrations > API & Webhooks

For detailed instructions on setting up API access, including organization-specific API keys, see Using the API V2.

API credentials should be stored securely and never exposed in client-side application code. Your respondents' browsers and mobile apps should call your own server, and your server calls the Brilliant Assessments API: anyone holding both keys can act as your account.

Rate limits: API requests are limited per account according to your subscription plan. Requests above the limit are first slowed down; beyond that, the API returns HTTP 429 with a Retry-After header giving the number of seconds to wait. Trial accounts do not have API access.

Swagger API Documentation

Complete technical documentation for the Assessment Delivery APIs and all existing API V2 endpoints is available in Swagger.

View the Swagger API Documentation

Swagger provides developers with:

• A complete list of available API endpoints.
• Required parameters and request bodies.
• Response structures and data models.
• Validation requirements and possible error responses.
• The ability to explore API operations and, where enabled, test requests.

The new endpoints are grouped under Assessment Delivery, while the existing response APIs are grouped under AssessmentResponse.

Swagger is the definitive technical reference for implementing the APIs. Developers should use this documentation alongside the workflow described in this article.

Sample Application

To make integration easier, Brilliant Assessments has developed a simple sample application demonstrating how to build custom assessment response screens using the Assessment Delivery APIs.

The sample application provides a practical starting point for developers wanting to understand the API workflow and build their own implementation. It is a small web application written in plain HTML and JavaScript, with a lightweight Node.js server that keeps your API keys out of the browser. It runs on any computer with Node.js 18 or later, needs nothing else installed, and shows every API request and response it makes.

The sample application and source code are available on request.

Please contact Brilliant Assessments Support to request a copy.

Related Articles

• Using the API V2 – API authentication, existing endpoints, and response data.
• Swagger API Documentation – Complete technical specifications for the Assessment Delivery APIs and existing API V2 endpoints.