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

 

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


Error handling

Status code Meaning
200 OK Request was successful
400 Bad Request Invalid parameters (e.g., unknown language code)
401 Unauthorized Missing or invalid token
403 Forbidden Token does not have the required permission

 

Next steps