Getting started

Five minutes from nothing to a working integration. Everything here runs against stage — swap the host for production once it works.

Stage        https://api.stage.theattco.net
Production   https://api.theattco.net

1. Get a token

Every request carries a bearer token. As a person, log in:

TOKEN=$(curl -s https://api.stage.theattco.net/v2/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"you@example.com","password":"…"}' | jq -r .access_token)

As a machine, exchange an API key for one instead — see Authentication for how the two halves of a key work:

TOKEN=$(curl -s https://api.stage.theattco.net/v2/auth/api-token \
  -H 'X-Access-Key-Id: tac_live_7Qk2RfNp4xZ1mVdB' \
  -H 'X-Access-Key-Secret: …' | jq -r .access_token)

2. Make a call

curl -s https://api.stage.theattco.net/v2/locations \
  -H "Authorization: Bearer $TOKEN"

{
  "entries": [
    {
      "id": "loc_018f5a01-1c2d-7e3f-8a4b-5c6d7e8f9012",
      "name": "Kungsgatan",
      "timezone": "Europe/Stockholm"
    }
  ],
  "next_cursor": null
}

That is the whole shape of the API: a JSON object, snake_case throughout, with list endpoints returning entries and a next_cursor.

3. The token already knows who you are

Almost no endpoint takes an account id. The token identifies both the person and the account they are working in, and everything you can reach is scoped to that account automatically.

If you find yourself looking for somewhere to pass an account id, you are probably calling an internal endpoint that was not meant for you.

4. Walk a list

next_cursor is how you get the rest. Feed it back as cursor, and stop when it comes back null — not when a page looks short:

cursor=""
while :; do
  page=$(curl -s "https://api.stage.theattco.net/v2/locations?limit=100${cursor:+&cursor=$cursor}" \
    -H "Authorization: Bearer $TOKEN")
  echo "$page" | jq -c '.entries[]'
  cursor=$(echo "$page" | jq -r '.next_cursor // empty')
  [ -z "$cursor" ] && break
done

Pagination covers why it is a cursor and not a page number.

5. Handle a failure

Every failure, from every part of the API, comes back in the same shape:

{
  "type": "https://api.theattco.com/problems/validation-error",
  "title": "Validation failed",
  "status": 400,
  "detail": "timezone must be an IANA zone name, got 'CET+1'"
}

Switch on type, show detail, log all four. Errors lists every type the API can return and which ones are worth retrying.

Where to go next

A note on ids

Ids carry a type prefix — loc_, cmp_, usr_. It makes an id self-describing in a log or a support ticket, and makes passing the wrong one obvious immediately. Treat them as opaque strings; never build one.

TAC API

The Attribution Company platform is one HTTPS API. It is assembled from several services, each owning a part of the domain, but they sit behind a single gateway and share one base URL, one authentication scheme, one error format and one set of naming rules. You should rarely need to care which service answers a call.

Production   https://api.theattco.net
Stage        https://api.stage.theattco.net

Everything is JSON over HTTPS. Every field, query parameter and path parameter is snake_case. Every call carries a bearer token. Every failure comes back in the same shape.

What each part owns

How to read this reference

If you have not called the API before, start with Getting started — it goes from no token to a working request in five minutes.

Endpoints are grouped by area in the sidebar. Each one lists its parameters, its response shape and the failures it can return. Before you start, three pages are worth five minutes each: Authentication for how tokens and API keys work, Errors for the one failure shape, and Conventions for naming, ids and timestamps.

Endpoints marked Internal are service-to-service and are not available to ordinary callers, even with a valid token.

Authentication

Every request carries a bearer token:

Authorization: Bearer <token>

Tokens are HS256 JWTs. There are two ways to get one — as a person, or as a machine — and they produce tokens with different powers.

As a person

curl -s https://api.theattco.net/v2/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"you@example.com","password":"…"}'

You get a short-lived access token and a refresh token. When the access token expires, exchange the refresh token at POST /v2/auth/refresh rather than logging in again. POST /v2/auth/logout revokes the refresh token.

As a machine

API key credentials come in two halves, issued together:

They are split so the two halves can be handled with different levels of care — the id identifies a key in the UI and in logs without revealing anything.

Exchange them for a token, and use that token everywhere else:

curl -s https://api.theattco.net/v2/auth/api-token \
  -H 'X-Access-Key-Id: tac_live_7Qk2RfNp4xZ1mVdB' \
  -H 'X-Access-Key-Secret: …'

Those two headers are accepted by this one endpoint and nowhere else. Never send the secret to any other path, never in a query string, and never log it.

What a key token cannot do

A key token is deliberately weaker than a person's:

• If the key is read-only, it may use GET and HEAD only, anywhere in the API.
• /v2/users, /v2/invitations, /v2/api-keys and account switching refuse

every key token, reads included — a key that could invite a user, mint another key or switch accounts would escape its own scope.

What is inside the token

{
  "sub": "usr_018f4ea1-3b6c-7d24-8e90-1f2a3b4c5d6e",
  "account": "acc_018f4e9a-7c2d-7e3b-9f1a-2b3c4d5e6f70",
  "role": "admin",
  "account_type": "neuro",
  "exp": 1780000000
}

Because the account rides on the token, endpoints do not take an account id. Anything you can reach, you can reach for that account only.

Group scope

Two optional claims narrow a caller to part of the estate:

{ "group_scope": "selected", "groups": { "018f5a01-…-9012": "a" } }

group_scope is all or selected. When selected, groups maps a group id to a (group admin) or m (group member), and that map is the only estate access the caller has.

Both claims are absent for an account-wide caller — including every token minted before the feature existed. Absent therefore means account-wide, which is why unrestricted tokens do not grow over time. Unknown role letters are ignored rather than treated as access.

Scope rides on the token, so a change to someone's grants lands on their next mint. Changing grants revokes their refresh tokens, which bounds the window to one access-token lifetime.

Devices

Devices do not use bearer tokens. They present a client TLS certificate issued during bootstrap by the device CA. First contact, before any certificate exists, is authenticated by signing the request body with the device's factory-issued private key and sending the signature in X-Device-Signature; the server verifies it against the public key recorded for that device, and replays are rejected.

Device endpoints are documented for the firmware that calls them. They are not reachable with a user or key token.

Errors

Every failure, from every service, comes back in the same shape: RFC 9457 problem details, sent as application/problem+json.

{
  "type": "https://api.theattco.com/problems/validation-error",
  "title": "Validation failed",
  "status": 400,
  "detail": "timezone must be an IANA zone name, got 'CET+1'"
}

The rule of thumb: switch on type, show detail, log all four.

Kinds

404 deserves a note: the API does not distinguish "does not exist" from "exists but is not yours". Both are not-found, deliberately, so that ids cannot be discovered by probing.

Status codes in use

410 Gone means a one-time thing has been spent: an email verification code that expired, was already used, or was attempted too many times, or an invitation past its expiry. Unlike 404, it is a definite "this existed and is finished" — issue a new one rather than retrying.

Retrying

Retry 429, 502 and 503. Do not retry 4xx otherwise — the request will fail the same way. Use exponential backoff with jitter, and treat 429 as a signal to slow down generally, not just to repeat the one call.

Rate limits apply per API key.

Validation failures

A validation-error names the offending value in detail. It reports the first problem found rather than every problem at once, so fix and resubmit rather than expecting a complete list.

Pagination

List endpoints are cursor-paginated. You ask for a page, and the response tells you how to ask for the next one.

GET /v2/locations?limit=50

{
  "entries": [ { "id": "loc_018f5a01-…", "name": "Kungsgatan" } ],
  "next_cursor": "eyJpZCI6ImxvY18wMTk1In0"
}

Stop on next_cursor: null, not on a short page — a full page can still be the last one, and a short page can still have more behind it.

cursor=""
while :; do
  page=$(curl -s "$BASE/v2/locations?limit=100${cursor:+&cursor=$cursor}" \
    -H "Authorization: Bearer $TOKEN")
  echo "$page" | jq -c '.entries[]'
  cursor=$(echo "$page" | jq -r '.next_cursor // empty')
  [ -z "$cursor" ] && break
done

The cursor is opaque

It is an encoded position, not an id, an offset or a page number. Do not parse it, build one, or keep one for later — pass back exactly what you were given. Its contents are free to change without notice; its meaning as "resume here" is not.

Cursors are not stable across filter changes. Change any query parameter and start again from the first page, or you will get results that answer neither query.

Why not page numbers

Rows are being written while you read. With offsets, a row inserted before your position shifts everything down and you silently skip an entry; a deletion shows you one twice. A cursor is anchored to a row, so a full walk sees each row once even under writes.

One inconsistency to know about

Most list endpoints return their rows under entries. The campaign endpoints return them under data. Both use next_cursor in the same way. If you write a shared pagination helper, take the array key as a parameter.

Versioning

The version is in the path:

https://api.theattco.net/v2/locations

There is one current version, v2, across every service. There is no version header and no per-account pinning — everyone is on the same version at the same time. v1 has been retired and its endpoints no longer answer.

What we may change without a new version

These are additive, and your client must tolerate them:

• A new endpoint.
• A new optional request parameter or body field.
• A new field in a response.
• A new value in an enum, where the field already documents that it may grow.
• A new type in an error, alongside the existing status code.

The practical consequence: ignore fields you do not recognise, and do not validate responses so strictly that an added field is an error. A client that rejects unknown fields will break on a routine release.

What we will not do inside v2

• Remove or rename a field, parameter or endpoint.
• Change a field's type, or make an optional request field required.
• Change what an existing value means.
• Change a success status code.

Anything in that list needs a new version.

Retiring things

When something is going away it is marked deprecated in this reference first, with what to use instead. Deprecation is announced before it happens, and retirement follows only once the replacement has been available long enough to move to.

Not yet settled: what a retired endpoint should answer. 404 is what it

would do today by default, which reads like a typo rather than a removal.

Worth deciding before the first v2 retirement.

Naming is settled

Every field, query parameter and path parameter is snake_case, across every service. Where you find camelCase, treat it as a bug worth reporting rather than a convention to copy — the last of it was removed in August 2026, and nothing new should carry it.

Conventions

The rules below hold everywhere. If an endpoint appears to break one, it is a bug worth reporting.

Naming

Every field, query parameter and path parameter is snake_case — account_id, avg_dwell_seconds, from, to, next_cursor. Never camelCase, in either direction, in request or response.

Identifiers

Ids are a short type prefix, an underscore, and a UUIDv7:

loc_018f5a01-1c2d-7e3f-8a4b-5c6d7e8f9012

The prefix makes an id self-describing in a log, a URL or a support ticket, and makes it obvious when the wrong one has been passed. Match on the whole string — prefixes are stable, but treat the id as opaque and never build one yourself.

Because UUIDv7 leads with a timestamp, ids from the same type sort roughly by creation time. Convenient, but not a substitute for a created_at field.

Two are easy to confuse: `cmp_` is a campaign, `cam_` is a camera.

Dates and times

Timestamps are always UTC on the wire. Anything a person sees in local time is converted by the client, or by an analytics rollup that knows the location's timezone — which is why a location carries an IANA zone name.

Date ranges use from and to, and both are inclusive. Omit them for "all time" where an endpoint allows it.

Absent values

A field that is genuinely unknown or not set is null. A field that does not apply is omitted. Both arrive in JavaScript as a falsy value, so check for presence rather than truth when zero is a legitimate answer — several analytics fields can honestly be 0.

Comma-separated filters

Where a filter accepts several values it takes one comma-separated parameter, not a repeated one:

?campaign_ids=cmp_018f6a01-…,cmp_018f6a02-…

Money and counts

Counts are integers. Rates and percentages are numbers, expressed as percentages rather than fractions — an attention rate of 36.9 means 36.9%.