Integrations API Reference

This document describes how to interact with the GoodBridge Integrations API to retrieve respondent data for your projects.

Overview

The Integrations API allows platform users to programmatically export respondent data from their projects in JSON format.

Base URL: https://bk.analysis.goodbridge.kz/integrations

Authentication

All requests to the Integrations API require an OAuth2 Bearer Token.

1. Obtain an access token from the GoodBridge authentication service.
2. Include the token in the Authorization header of your HTTP requests:

Authorization: Bearer <your_access_token>

Note: The Uploading data via API feature must be available for your workspace’s tariff plan to use this endpoint.

---

Get Respondents Data

Retrieve filtered and paginated respondent data for a specific project.

Endpoint

GET /{project_id}/respondents

Path Parameters

Parameter	Type	Description
project_id	string	The unique ID of the project.

Query Parameters

Parameter	Type	Required	Description
page	integer	Yes	Page number (minimum: 1).
page_size	integer	Yes	Number of items per page (1-100).
display_lang_code	string	Yes	Language for displaying data: ru, kz, kk, en, fr, de, tr.
filters.starttime_ge	string	No	Filter respondents who started after this time (ISO 8601 format, e.g., 2023-01-01T12:00:00).
filters.endtime_le	string	No	Filter respondents who finished before this time (ISO 8601 format).
filters.classificator	string	No	Filter by classificator value.
filters.classificator_2	string	No	Filter by secondary classificator value.
filters.lang_code	string	No	Filter by form filling language (ru, kz, etc.).
filters.channel_id	string	No	Filter by specific channel (collector) ID.
sorting.endtime	string	No	Sort results by end time: asc or desc.

Example Request (cURL)

curl -X GET "https://bk.analysis.goodbridge.kz/integrations/PROJ123/respondents?page=1&page_size=20&output_format=json&display_lang_code=en" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response Format

The response will follow this structure:

{
  "page": 1,
  "page_size": 20,
  "total": 150,
  "respondents": [
    {
      "info": {
        "id": 1001,
        "collector_id": "CHAN789",
        "collector_name": "Web Survey",
        "is_manual_input": false,
        "starttime": "2023-10-27T10:00:00.817000Z",
        "endtime": "2023-10-27T10:05:00.817000Z",
        "finish_reason": 1,
        "classificator": null,
        "classificator_2": null,
        "lang": "en",
        "created_at": "2023-10-27T10:05:01.817000Z",
        "updated_at": "2023-10-27T10:05:01.817000Z"
      },
      "questions": [
        {
          "id": "Q1",
          "title": "What is your satisfaction level?",
          "type": "scale",
          "answers": [
            {
              "id": "A1_1",
              "label": "High",
              "answer": 9,
              "comment": null,
              "data_type": "number"
            }
          ],
          "sub_questions": [],
          "params": {
            "date_format": null
          }
        }
      ]
    }
  ]
}

Error Responses

Status Code	Description
401 Unauthorized	Invalid or missing authentication token.
403 Forbidden	Access token expired, inactive, or the feature is not available for your tariff.
404 Not Found	Workspace or project not found.
422 Unprocessable Entity	Validation error (e.g., missing required parameters or invalid values).
429 Too Many Requests	Request rate limit exceeded.