Skip to content
English
Contact us
  • There are no suggestions because the search field is empty.

API: Getting started

This guide walks you through making your first Insight API call.

Step 1: Get your API token

To get started with the API, contact your Brilliant representative. They will set up an API token for your organization with the appropriate permissions.

Once you receive your token, store it securely — it grants access to your organization's data. Do not share it in code repositories, emails, or chat messages.

Step 2: Authenticate

All API requests require a JWT bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

 

Step 3: Make your first call

A good first call is listing your groups to verify everything works.

Request:

GET /api/public/groups
Authorization: Bearer YOUR_API_TOKEN

Response:

{
  "groups": [
    {
      "groupId": 1,
      "name": "Engineering",
      "externalId": "ENG-001",
      "categoryKey": "team",
      "isDeleted": false
    },
    {
      "groupId": 2,
      "name": "Marketing",
      "externalId": "MKT-001",
      "categoryKey": "team",
      "isDeleted": false
    }
  ]
}

 

Step 4: Explore further

Once authenticated, here's a typical workflow for pulling survey results:

1. GET /api/public/surveys          → Find the survey you're interested in
2. GET /api/public/indexes?languageCode=en   → Get available indexes
3. GET /api/public/groups           → Get your organization's groups
4. GET /api/public/surveys/{id}/results      → Pull the results

For customer-experience (CX) companies, you can also retrieve individual respondent data, useful for analysing free-text answers and tonality:

1. GET /api/public/surveys                       → Find the survey
2. GET /api/public/freetext-categories           → Get categories used for free-text tonality classification
3. GET /api/public/surveys/{id}/responses        → Pull individual responses (CX surveys only)

For HR-system synchronization, the user-management endpoints let you keep Insight aligned with your source of truth:

1. GET /api/public/users                 → Read current users
2. POST /api/public/users                → Create new joiners (bulk, max 100/batch)
3. PUT /api/public/users                 → Update changed users (bulk, max 100/batch)
4. DELETE /api/public/users              → Soft-delete leavers (bulk, max 100/batch)

 

Common patterns

Filtering by group category

Groups are organized into categories (e.g., "team", "department"). You can filter:

GET /api/public/groups?categoryKey=team


Localized content

Indexes and questions support multiple languages. Pass an ISO 639-1 language code:

GET /api/public/indexes?languageCode=sv
GET /api/public/questions?languageCode=en


Survey result filtering

When fetching results, you can narrow down by group, index, or question:

GET /api/public/surveys/42/results?groupId=1&indexId=5


Filtering individual responses by date (CX surveys)

When pulling individual responses for a CX survey, you can limit the time window:

GET /api/public/surveys/42/responses?submittedAfter=2026-01-01&submittedBefore=2026-04-01

Filtering users by status

The user list defaults to active and deactivated users. To include deleted users or filter to a single status, pass status:

GET /api/public/users?status=Active

 


Error handling

Status code Meaning
200 OK Request was successful
204 No Content Successful with no body (e.g., bulk delete)
400 Bad Request Invalid parameters (e.g., unknown language code, or CX-only endpoint called from a non-CX company)
401 Unauthorized Missing or invalid token
403 Forbidden Token does not have the required permission

 

Next steps