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 paginated response envelope.

​
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 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 envelope

Every list endpoint returns the same envelope: a data array and a next_cursor you follow for the next page.
You parse data for the records and re-send the request with cursor=<next_cursor> to walk further. See Pagination for the loop pattern.

​
4. Handle errors and rate limits

Operata returns a stable JSON error envelope on every 4xx and 5xx:
Match on error.code, not on error.message. Honor the Retry-After header on 429 rate_limited — the default budget is 100 requests per minute per token. See Errors and Rate limits.

​
Verify

Run the call from step 2 again and confirm three things:
  • The HTTP status is 200.
  • The body parses as JSON with a data array.
  • The response headers include X-RateLimit-Remaining with a value below 100.
If you see 401 unauthorized, your Group ID and token do not pair correctly — re-check the env vars. If you see 400 invalid_range, the time window is malformed; the toTime must be strictly after fromTime.
  • Quickstart — the 90-second version of this guide, when you want the curl line and nothing else.
  • Pagination — walk every page of a result set with one cursor variable.
  • Contact summary — the first endpoint most integrations call.
  • Data redaction — strip sensitive fields before they reach Operata.