Using The API V2

The Brilliant Assessments API allows you to integrate your assessment platform with external applications and automate workflows. It provides endpoints for creating responses, retrieving response data, and polling for changes.

Two versions of the API are currently available:

We recommend all new integrations use API V2. Existing V1 integrations will continue to work during the transition period.

API V2 (Current)

Security and Authentication

API V2 uses a two-key authentication model for increased security, similar to payment providers like Stripe:

• Public Key - Identifies your tenant. Included in API requests.
• Private Key - Used to authenticate requests. Must be kept secret.

Both keys are required for every API request. The private key is encrypted and stored securely. Unlike V1's single key, this two-key model means that even if one key is exposed, both are needed to access your data.

Setting Up API Keys

1. Go to Administer > Site Settings
2. Click the Integrations tab
3. Select the API & Webhooks sub-tab
   
4. Click Generate API Keys
5. Your Public Key and Private Key will be displayed
6. Copy your Private Key immediately and store it securely. The Private Key can be viewed again from this screen, but treat it like a password.
   

Partner/Organization API Access

API V2 allows partners (Organizations) to access the API using their own keys. This means partners can integrate with their own systems while only seeing their own response data.

To set up partner API access:

1. Go to Site Settings > Features > Organizations
2. Click Edit on the organization
3. Under V2 API Key > Click Add API key (or Edit API key if one already exists)
4. The API key fields will appear in the same format as Site Settings

Base URL and Documentation

All requests must include your API keys in the following request headers:

Endpoints

Get Test

Test connectivity to the API.

Endpoint: GET /api/v2/test

Parameters: None

Response: "Test succeeded" string

Get Assessment Response

Gets full data for a single assessment response.

Endpoint: GET /api/v2/responses/{responseID}

URI Parameters

Response Model - Top-level Fields

Response Model - Rating

SegmentationRatings (collection): Same fields as Rating, plus SegmentationId and SegmentationName.

Response Model - SectionRatings (collection)

SubSectionRatings (collection): Same structure as SectionRatings but with SubSectionId, SubSectionNo, SubSectionName instead of Section fields.

Response Model - Answers (collection)

Response Model - Classifiers (collection)

Response Model - ReportDetails (collection)

DashboardUrl: string

For complete response examples, see the Swagger documentation.

Get Changes

Performs a search for completed assessment responses, optionally filtered by date and assessment. Use this endpoint to poll for new completions.

Endpoint: GET /api/v2/changes?since={date}&assessmentId={ExternalID}

Query Parameters

Response Model

Sample Response:

{
  "ResponseIds": [1, 2],
  "ExternalIds": ["LEADERSHIP-001", "LEADERSHIP-001"]
}

Get All Responses for an Assessment

Returns all responses for an assessment regardless of status (completed, in-progress, etc.).

Endpoint: GET /api/v2/responses?assessmentId={ExternalID}

Query Parameters

Post Create Response

Create a new assessment response. The contact details can be set by specifying a ContactId or by providing contact details directly.

The response returns the ResponseID and ResponseURL. You can redirect the user to the URL, or set up a Welcome email template to have the system send them an invitation.

Endpoint: POST /api/v2/responses

Body Parameters

Response Model

Rate Limits

If you need higher limits, contact support@brilliantassessments.com.

API V1 (Legacy)

API V1 continues to work until December 31, 2027. If you have existing integrations using V1, they will continue to function. However, we recommend migrating to V2 for improved security and additional data fields.

Migrating from V1 to V2

What's Changed

Migration Steps

1. Generate your V2 API keys in Site Settings > Integrations > API & Webhooks
2. Update your base URL to https://apiv2.brilliantassessments.com
3. Update your authentication to send both keys via the X-API-PublicKey and X-API-PrivateKey headers
4. Update any code that references removed fields (FeatureName, SegmentationId/SegmentationName in Answers/SectionRatings/SubSectionRatings)
5. Test using the Swagger documentation
6. Consider adding Webhooks to receive ResponseIDs in real time when responses are created or completed, reducing the need to poll with Get Changes

FAQs & Troubleshooting

Use the questions below to troubleshoot common API issues.

Related Articles

• Setting Up Webhooks - Real-time notifications when responses are created or completed
• Connecting Webhooks to Zapier - Step-by-step Zapier integration with webhooks
• Integrating CRMs and Other Systems with Zapier - Polling-based Zapier integration (V1)
• Configuring Site Settings - Integrations tab overview