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.

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. Create something

Reads are the easy half. A write shows the rest of the shape — a JSON body, snake_case in as well as out, and a 201 carrying the thing you made:

curl -s -X POST https://api.stage.theattco.net/v2/campaigns   -H "Authorization: Bearer $TOKEN"   -H 'content-type: application/json'   -d '{"name":"Spring launch"}'

{
  "id": "cmp_018f5a01-1c2d-7e3f-8a4b-5c6d7e8f9012",
  "name": "Spring launch",
  "status": "draft",
  "current_version": null
}

Only name was required. Everything else — description, start_date, priority — is optional, and what you leave out comes back as its default rather than being absent, so you can see what the server decided.

The id is yours to keep: it is how you reach the campaign again, and it is prefixed cmp_ so a glance at a log says what kind of thing it is.

4. 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.

5. 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.

6. 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.

Concepts

Most of the API makes sense once you know how the platform models a retail estate and what a campaign is made of. This page is the mental model; the reference is the detail.

The estate

group  ──▶ location  ──▶ zone  ──▶ screen
                                     ▲
device ───────── installation ───────┘

Read it downwards: a group holds locations, a location holds zones, a zone holds screens. A device is separate — it is a physical thing — and an installation is what puts a device into a location, wired to the screens it drives.

Setting an estate up is done in the product, not through this API. What matters when you are integrating is that this is the shape your analytics come back in: a visit happened at a location, in a zone, and a location's timezone is what makes a day a day.

Campaigns

media asset ──▶ ad ──▶ ad library
                 │
                 └──▶ campaign ad ──▶ campaign

A media asset is an uploaded file. An ad is that asset made playable. Ads are gathered into an ad library, and a campaign ad is one ad placed into a campaign against a screen tag — which is how an ad ends up somewhere rather than merely existing.

A campaign starts as a draft. Publishing it is a separate, deliberate step — creating a campaign does not put anything on a screen.

Accounts and groups

Your token already carries the account. Almost nothing takes an account id, because there is never a question of which account you mean — see Getting started.

Within an account, access can be narrowed to particular groups. A token so scoped sees only those groups' locations, and everything downstream of them, without saying so on each call. If a list looks short, scope is the first thing to check.

Ids

Every id carries its type: loc_018f5a01-1c2d-7e3f-8a4b-5c6d7e8f9012. The prefix makes an id self-describing in a log or a support ticket, and makes passing the wrong one obvious immediately rather than three calls later.

Treat them as opaque strings. Never build one, never parse one, and do not rely on the part after the prefix having any particular shape.

Authentication

Every request carries a bearer token:

Authorization: Bearer <token>

Treat the token as opaque. It is a JWT, signed with RS256, but nothing about its contents is part of this API: claims are added and renamed as the platform changes, and no public key set is published for you to verify it with. Send it back as you received it. A 401 means the token was rejected — expired, malformed, or not verifiable — so get a fresh one rather than inspecting it.

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.

Match on the last segment of type — validation-error, not-found — rather than the whole URI. The prefix is being consolidated, and a client that matches the full string will need changing when it is; one that matches the last segment will not.

Kinds

validation-error

400. The request was malformed, or a value in it was unacceptable.

detail names the offending value: "timezone must be an IANA zone name, got 'CET+1'". It reports the first problem found rather than every problem at once, so a request with two bad fields takes two attempts.

Fix the value it names and send it again. Retrying unchanged fails identically.

unauthorized

401. No token, a token that has expired, or one that does not verify. detail is usually "Missing or invalid bearer token".

It says nothing about whether you would be allowed to do the thing — only that we do not know who you are. For that, see `forbidden`.

As a person, exchange your refresh token at POST /v2/auth/refresh rather than logging in again. As a machine, exchange your key at POST /v2/auth/api-token for a fresh one. Do not retry with the same token.

insufficient-balance

402. The account has no tokens left for this operation.

detail gives both numbers: "Account has 12 tokens; 50 required." The operation was understood and permitted — it was not paid for.

Retrying does not help until the balance changes. Top up, or reduce what you are asking for where the cost scales with size.

forbidden

403. We know who you are, and you may not do this.

The common causes are distinct and worth checking in order: your role within the account is too low; you used an API key on an endpoint that requires a signed-in person; the key is read-only and the request writes; or you asked for a scope — an account, a group — that this credential does not hold.

Do not retry. Nothing about the request will change the answer.

not-found

404. No such resource — or not one this account can see.

The API deliberately does not distinguish the two. A resource that exists but belongs to someone else answers exactly as one that never existed, so ids cannot be discovered by probing. A 404 is therefore not proof that something is gone.

Check the id, and check which account the token is scoped to. For a resource that definitely existed and has been spent, see `gone`.

conflict

409. The request fights the current state of the thing.

Typical: "Installation already ended", "A product with SKU 'X' already exists", "Cannot modify a closed account". Either someone got there first, or the resource is in a state that does not accept this change.

Re-read the resource and decide what to do with what you find. Retrying unchanged repeats the same conflict.

gone

410. A one-time thing has been spent.

An email verification code that expired, was already used, or was attempted too many times. An invitation past its expiry, or already accepted.

Unlike `not-found`, this is a definite "this existed and is finished". Issue a new one rather than retrying the old one.

unprocessable

422. Syntactically fine, but not a thing the domain permits.

Where validation-error means the shape or value was wrong, this means the request was well formed and still cannot be honoured: "Unknown groups for this account: a, b" — real field, real format, not a thing that exists here.

Fix the meaning rather than the syntax.

rate-limited

429. Too many requests.

Limits are applied per client IP, and only to the credential endpoints — logging in, exchanging an API key, resetting a password. They exist to stop guessing, not to shape traffic, so the endpoints you integrate against are not rate limited today. See Rate limits for the figures.

Back off exponentially with jitter, and treat it as a signal to slow down generally rather than to repeat the one call. It is the only 4xx worth retrying unchanged.

upstream-error

502. A dependency we call failed.

Nothing is wrong with your request and it may succeed if repeated. Retry with backoff. If it persists, it is ours, not yours.

Status codes in use

Rate limits

Only the credential endpoints are limited, and the limit is counted per client IP rather than per key or per account — so everyone behind one office NAT shares a budget.

A successful login does not count against the login budget — only failures do.

Everything else is unlimited. That is not a promise: it is where the platform stands today, and limits on the data endpoints would arrive with notice through the usual versioning route. Build as though they exist — back off on 429, do not poll in tight loops — and you will not be caught out.

Retrying

Retry 429, 502 and 503. Do not retry any other 4xx — the request will fail the same way until you change it.

Use exponential backoff with jitter. Retrying in lockstep after a 429 turns one slow client into a thundering herd.

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%.