Skip to main content
The Operata API gives you programmatic access to every contact, observation, and insight your collectors have stored. You authenticate with HTTP Basic — your Group ID as username, your API token as password — then hit https://api.operata.io. This guide walks you through generating credentials, making your first call, and reading the response in the v2 data model. Using the v1 format? See Getting started (v1).

​
Before you start

  • An Operata account. Your Operata Group ID is the UUID in the console URL.
  • The Admin role on that account. The console exposes token creation under Settings → Config → API.
  • curl (any recent version) and a shell that exports environment variables.

​
Steps

​
1. Generate an API token

In the Operata console, go to Settings → Config → API and click Create token. Copy the token immediately — the console shows it once. Treat tokens like passwords.
You now have credentials in your shell. See Authentication for the full credential lifecycle.

​
2. Make your first call

Operata uses HTTP Basic. The Group ID is the username, the token is the password. Hit the v2 contact summary endpoint with a small window:
A 200 OK confirms your credentials are valid and the account has access to contact data.

​
3. Read the response

List endpoints return a plain JSON array. The RecordCount response header holds how many records match in total. Each v2 contact carries accountProperties, contact, serviceAgent, webRTCSession, and billing; the contact ID is contact.id.current. This example is shortened:
To get the next page, re-send the request with from set to the number of records you’ve already read. See Pagination for the loop pattern.

​
4. Handle errors

Errors come back as an HTTP status code with a short plain-text body. A bad query parameter returns 400 with a message naming it:
Branch on the status code and log the body. See Errors for every status, and Rate limits for request budgets.

​
Verify

Run the call from step 2 again and confirm three things:
  • The HTTP status is 200.
  • The body parses as a JSON array.
  • The RecordCount response header is present.
If you see 401, your Group ID and token don’t pair correctly. Re-check the env vars. If you see 400, read the body: it names the query parameter to fix.