Machine-readable description: /openapi/v1.json (OpenAPI 3). Liveness: /health.

Index Data API — Client Specification

Version 1. This document describes how to authenticate against the Index Data API, how requests and responses are shaped, and what each endpoint returns. It is written for the engineers integrating with the API.

1. Overview

The API gives an organisation read access to its Index survey data: the questions asked, the answers given, and the media and sentiment derived from free-text answers.

Base URL:

https://api.index.gslglobal.com

All endpoints are under /v1, use GET, and return JSON. TLS is required; plain HTTP is not served.

This document is served at /docs. A machine-readable OpenAPI 3 description is at /openapi/v1.json; it declares the endpoints, parameters, response schemas and the HTTP Basic security scheme, and can be used to generate a client.

2. Authentication

You are issued a client id and a client secret. GSL will supply you with a client secret and is not recoverable; if lost, a new one can be issued. Send both on every request under /v1 using one of two forms.

HTTP Basic (preferred). Standard Authorization header with the client id as the user name and the secret as the password:

Authorization: Basic base64(clientId:clientSecret)

Custom headers. Equivalent, for tooling that cannot set an Authorization header:

X-Client-Id: <clientId>
X-Client-Secret: <clientSecret>

If both are present the Authorization header is used. Credentials are never accepted in the query string.

A missing, malformed or incorrect credential returns 401 Unauthorized with a WWW-Authenticate: Basic realm="Index Data API" header and no further detail. Treat every 401 as "check the credential"; the API does not distinguish an unknown client from a wrong secret.

Secrets can be rotated or revoked on request. Allow up to one minute for a revocation to take effect.

3. Data model

A response is one completed survey, identified by an integer responseId that is stable and unique across the whole dataset. A question is identified by a string questionId (examples: OneThingChange, AccommodationExpectations.AvailabilityCommunal, and GUID-based ids for some question types). An accommodation (hall) is identified by a GUID.

Every response also carries four pseudo-questions that appear alongside real questions in the answer data:

Responses are organised into waves, named survey periods such as 2026 Q2, each with a start date, an end date, and a set of halls. A response is in scope for your organisation when it was submitted to one of your halls during a wave in which that hall was part of your programme.

4. Common request parameters

Every /v1 endpoint accepts the same query parameters. Names are case-insensitive.

Constraints, all enforced with a 400 response naming the parameter:

• to must be on or after from.
• The window may span at most 90 days inclusive. Cover a longer period with consecutive windows.
• pageSize must be at least 1; values above 5000 are silently clamped to 5000.
• cursor must be a value the API produced.
• Each list parameter accepts at most 200 ids; accommodation values must be GUIDs.

5. Response envelope

Every successful call returns 200 with this shape:

{
  "data": [ ... ],
  "meta": {
    "from": "2026-02-01",
    "to": "2026-03-30",
    "wave": null,
    "question": null,
    "accommodation": null,
    "count": 1000,
    "nextCursor": "pVflEQ==",
    "nextLink": "https://.../v1/responses?from=2026-02-01&to=2026-03-30&pageSize=1000&cursor=pVflEQ%3D%3D",
    "generatedAt": "2026-09-04T10:22:19.437Z"
  }
}

• data is always an array, even for /summary which contains one element.
• meta.from, meta.to, meta.wave, meta.question, meta.accommodation echo the parameters as applied. to is filled in when you omitted it. The list filters are null when not supplied.
• meta.count is the number of elements in data for this page.
• meta.nextCursor and meta.nextLink describe the next page and are both null on the last page.
• meta.generatedAt is the UTC time the page was produced.

Property names are camelCase. Nulls are emitted explicitly, never omitted. Dates are ISO 8601; timestamps are UTC with a Z suffix.

5.1 Pagination

Paginated endpoints divide the responses in scope into pages of pageSize responses, ordered by responseId. A page always contains whole responses: all rows belonging to a response are on the same page, in every dataset. Rows within a page are ordered by responseId, then questionId.

To read everything, request the first page without a cursor, then repeat with cursor set to meta.nextCursor until nextCursor is null. meta.nextLink is the same thing as a ready-made absolute URL: this request with cursor replaced and every other parameter preserved.

Rules:

• Stop on a null cursor, not on an empty page. The final page can legitimately contain zero rows.
• Cursors are opaque. Do not construct, decode or compare them. They are stable: the same cursor with the same parameters returns the same page, and a job can resume from a stored cursor.
• Cursors are not interchangeable between different parameter sets. Changing from, to, wave or a filter means starting again without a cursor.
• Because pages are counted in responses, the number of rows per page varies. A response typically contributes 150 to 200 rows to /responses.

/questions and /summary are not paginated: they return their whole result in one call and always have a null cursor.

5.2 Compression

Responses are compressed with Brotli or gzip when the request includes Accept-Encoding: br or Accept-Encoding: gzip. Pages are large and highly repetitive JSON, and compression reduces transfer size by roughly five times. Always send Accept-Encoding.

6. Filtering

Two optional filters narrow results. Both accept a repeated parameter or a comma-separated value, and the two forms can be mixed:

?question=OneThingChange&question=CommunityFreeText
?question=OneThingChange,CommunityFreeText

accommodation restricts which responses are in scope, by hall GUID. It affects every endpoint identically, including pagination and the counts in /summary. Hall GUIDs are found in the answerId of AccommodationName rows.

question restricts which answers are returned:

The pseudo-questions are ordinary questions for this purpose: to receive submitdate or AccommodationName alongside a filtered set, include them in the list.

Matching is exact and case-insensitive. Unknown ids match nothing and are not an error. A question filter does not change which responses are in scope, so a response with no matching answers still occupies a place in a page but contributes no rows; /summary reports this as the difference between responsesInScope and responsesReturned.

7. Endpoints

7.1 GET /v1/questions

The questions that have at least one answer within the window for your organisation, in the default language, ordered by questionId. One entry per question. Not paginated.

The pseudo-questions are not listed here because they are not survey questions, but they do appear in the answer datasets.

7.2 GET /v1/responses

Long (entity-attribute-value) form. One row per response per answered question. Paginated by response.

All values are strings; apply your own typing downstream. A question that permits several selections may produce more than one row for the same responseId and questionId.

7.3 GET /v1/responses/wide

Wide form. One JSON object per response. Paginated by response, with exactly the same page boundaries as /responses for the same parameters.

Each object has a responseid key (integer) first, then one key per question in case-insensitive alphabetical order. Keys are the questionId strings verbatim, including dots. Values are strings, except submitdate, which is an ISO 8601 UTC timestamp. A question the response did not answer is present with a null value. If a question produced several values for one response they are joined with ; .

The set of keys is derived from the answers on that page, so it can differ between pages: a question nobody on a page answered is absent from that page. Consumers that need a fixed column set should take it from /questions plus the pseudo-questions, or pass an explicit question list.

7.4 GET /v1/media

Attachments supplied with free-text answers. Paginated by response.

Media URLs point at Index-hosted storage and are readable without further credentials at the time of writing; do not assume they are permanent.

7.5 GET /v1/sentiment

Themes detected in free-text answers, with sentiment. Paginated by response.

A single answer can carry several themes and therefore several rows. Rows for the same response and question are ordered by descending sentiment.

7.6 GET /v1/summary

Diagnostic. Runs the same scope and filters as a data request and returns one object of counts instead of the data. Use it to size a job, to reconcile a completed extraction, or to check that filters do what you expect.

8. Errors

Errors use the application/problem+json format (RFC 9457).

Example validation error:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": { "to": ["Date range cannot exceed 90 days."] },
  "traceId": "00-8997b680aca486475dc2c4a9bcad815b-3acca9299daa428b-00"
}

10. Performance expectations

• A page of 1000 responses from /responses is roughly 20 MB uncompressed, about 4 MB compressed, and takes a few seconds.
• /questions and /summary process the whole window and take a few seconds for a full wave.
• The first request touching a wave that has not been read recently can take significantly longer, up to a minute for a large wave, while data is loaded on the server side. Subsequent requests on the same window are fast. Set client timeouts to at least 120 seconds and do not treat a slow first page as a failure.
• Prefer larger pages (1000 to 2000) over many small ones.

11. Recommended extraction pattern

1. Call /v1/summary for the window and filters to learn responsesInScope and pages.
2. Pull /v1/questions once for the window to get titles for the ids you will see.
3. Page through the dataset you need, storing meta.nextCursor after each page so an interrupted job can resume. Stop when nextCursor is null.
4. Reconcile: the number of distinct responseId values received should equal responsesReturned, and the total row count should equal the corresponding *Rows figure from the summary.
5. For incremental loads, keep the last submitdate seen and use it as the next from. Because responses are keyed by responseId, re-pulling an overlapping window is safe if you upsert on responseId (and questionId for long rows).

12. Example

BASE=https://api.index.gslglobal.com
AUTH="clientId:clientSecret"

# size the job
curl -s --compressed -u "$AUTH" \
  "$BASE/v1/summary?from=2026-02-01&to=2026-03-30&pageSize=1000"

# first page of long-form answers, two questions plus the submit date
curl -s --compressed -u "$AUTH" \
  "$BASE/v1/responses?from=2026-02-01&to=2026-03-30&pageSize=1000&question=OneThingChange,CommunityFreeText,submitdate"

# next page: either follow meta.nextLink verbatim, or pass the cursor
curl -s --compressed -u "$AUTH" \
  "$BASE/v1/responses?from=2026-02-01&to=2026-03-30&pageSize=1000&question=OneThingChange,CommunityFreeText,submitdate&cursor=pVflEQ%3D%3D"