Customers & Journey

Customer List

GET /api/v1/customers

Returns a paginated list of customers who achieved a specific conversion goal within the date range. Each row includes the customer's identity, the conversion details, channel attribution, and lifetime metrics.

Scope: customers:read

Parameters

Request

curl -H "Authorization: Bearer atb_live_YOUR_KEY" \
  "https://www.atribu.app/api/v1/customers?date_from=2026-03-01&date_to=2026-03-25&goal=payment_received&limit=5"

const res = await fetch(
  "https://www.atribu.app/api/v1/customers?date_from=2026-03-01&date_to=2026-03-25&goal=payment_received&limit=5",
  { headers: { Authorization: "Bearer atb_live_YOUR_KEY" } }
);
const { data, pagination } = await res.json();

import requests

res = requests.get(
    "https://www.atribu.app/api/v1/customers",
    headers={"Authorization": "Bearer atb_live_YOUR_KEY"},
    params={
        "date_from": "2026-03-01",
        "date_to": "2026-03-25",
        "goal": "payment_received",
        "limit": 5,
    },
)
body = res.json()
data = body["data"]
has_next = body["pagination"]["has_next"]

Response

{
  "data": [
    {
      "conversion_id": "uuid",
      "customer_profile_id": "uuid",
      "name": "Jane Smith",
      "email": "[email protected]",
      "country": "US",
      "device": "mobile",
      "channel": "Paid Social",
      "source": "ig",
      "revenue": 299.00,
      "revenue_type": "cash",
      "conversion_time": "2026-03-22T14:30:00Z",
      "time_to_complete_seconds": 172800,
      "touch_count": 3,
      "touch_channels": ["Paid Social", "Direct"],
      "conversion_count": 2,
      "total_revenue": 598.00
    }
  ],
  "pagination": {
    "has_next": true,
    "cursor": "2026-03-22T14:30:00Z|uuid"
  },
  "meta": {
    "date_from": "2026-03-01",
    "date_to": "2026-03-25",
    "profile_id": "uuid"
  }
}

Response fields

Pagination

This endpoint uses cursor-based pagination. The pagination.cursor field in the response contains the values needed to fetch the next page.

curl -H "Authorization: Bearer atb_live_YOUR_KEY" \
  "https://www.atribu.app/api/v1/customers?date_from=2026-03-01&date_to=2026-03-25&goal=payment_received&cursor_time=2026-03-22T14:30:00Z&cursor_id=uuid"

let allCustomers = [];
let cursorTime = undefined;
let cursorId = undefined;

while (true) {
  const url = new URL("https://www.atribu.app/api/v1/customers");
  url.searchParams.set("date_from", "2026-03-01");
  url.searchParams.set("date_to", "2026-03-25");
  url.searchParams.set("goal", "payment_received");
  url.searchParams.set("limit", "50");
  if (cursorTime) url.searchParams.set("cursor_time", cursorTime);
  if (cursorId) url.searchParams.set("cursor_id", cursorId);

  const res = await fetch(url, {
    headers: { Authorization: "Bearer atb_live_YOUR_KEY" },
  });
  const body = await res.json();
  allCustomers.push(...body.data);

  if (!body.pagination.has_next) break;
  [cursorTime, cursorId] = body.pagination.cursor.split("|");
}

import requests

all_customers = []
cursor_time = None
cursor_id = None

while True:
    params = {
        "date_from": "2026-03-01",
        "date_to": "2026-03-25",
        "goal": "payment_received",
        "limit": 50,
    }
    if cursor_time:
        params["cursor_time"] = cursor_time
        params["cursor_id"] = cursor_id

    body = requests.get(
        "https://www.atribu.app/api/v1/customers",
        headers={"Authorization": "Bearer atb_live_YOUR_KEY"},
        params=params,
    ).json()

    all_customers.extend(body["data"])

    if not body["pagination"]["has_next"]:
        break
    cursor_time, cursor_id = body["pagination"]["cursor"].split("|")

Import Customers

POST /api/v1/customers

Batch-upserts customer identities directly into the identity graph — a practice-management export (Dentalink, Medilink, a spreadsheet) or a CSV, not an event. No outcome_events row is written and no event name is picked; this is the write sibling of the Customer List endpoint above.

Scope: attribution:write

Request body

Each entry in rows:

Request

curl -X POST "https://www.atribu.app/api/v1/customers" \
  -H "Authorization: Bearer atb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "CL",
    "rows": [
      { "phone": "+56911112222", "national_id": "14.146.609-7", "first_name": "María", "last_name": "Pérez" },
      { "email": "[email protected]", "national_id": "20473794-0" }
    ]
  }'

const res = await fetch("https://www.atribu.app/api/v1/customers", {
  method: "POST",
  headers: {
    Authorization: "Bearer atb_live_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    country: "CL",
    rows: [
      { phone: "+56911112222", national_id: "14.146.609-7", first_name: "María" },
      { email: "[email protected]", national_id: "20473794-0" },
    ],
  }),
});
const { data } = await res.json();

import requests

res = requests.post(
    "https://www.atribu.app/api/v1/customers",
    headers={"Authorization": "Bearer atb_live_YOUR_KEY"},
    json={
        "country": "CL",
        "rows": [
            {"phone": "+56911112222", "national_id": "14.146.609-7", "first_name": "María"},
            {"email": "[email protected]", "national_id": "20473794-0"},
        ],
    },
)
data = res.json()["data"]

Response

{
  "data": {
    "results": [
      { "index": 0, "status": "created", "customer_profile_id": "uuid" },
      { "index": 1, "status": "matched", "customer_profile_id": "uuid" }
    ],
    "summary": { "total": 2, "created": 1, "matched": 1, "rejected": 0 }
  },
  "meta": { "profile_id": "uuid" }
}

Response fields

Customer Journey

GET /api/v1/customers/{id}/journey

Returns the full event timeline for a single customer -- every page view, form submission, booking, payment, and marketing touchpoint in chronological order.

Scope: customers:read

Parameters

Request

curl -H "Authorization: Bearer atb_live_YOUR_KEY" \
  "https://www.atribu.app/api/v1/customers/customer-uuid/journey?limit=20"

const customerId = "customer-uuid";
const res = await fetch(
  `https://www.atribu.app/api/v1/customers/${customerId}/journey?limit=20`,
  { headers: { Authorization: "Bearer atb_live_YOUR_KEY" } }
);
const { data } = await res.json();
console.log(`${data.total_count} events in journey`);

import requests

customer_id = "customer-uuid"
res = requests.get(
    f"https://www.atribu.app/api/v1/customers/{customer_id}/journey",
    headers={"Authorization": "Bearer atb_live_YOUR_KEY"},
    params={"limit": 20},
)
events = res.json()["data"]["events"]

Response

{
  "data": {
    "events": [
      {
        "event_type": "page_view",
        "event_name": "page_view",
        "event_time": "2026-03-18T10:15:00Z",
        "url": "https://example.com/pricing",
        "path": "/pricing",
        "channel": "Paid Social",
        "source": "ig",
        "medium": "paid",
        "campaign": "Spring Sale",
        "value_amount": null,
        "currency": null,
        "device": "mobile",
        "browser": "Safari",
        "os": "iOS",
        "country": "US",
        "city": "New York",
        "is_synthetic": false
      },
      {
        "event_type": "payment_received",
        "event_name": "payment_received",
        "event_time": "2026-03-20T16:45:00Z",
        "url": null,
        "path": null,
        "channel": null,
        "source": "stripe",
        "medium": null,
        "campaign": null,
        "value_amount": 299.00,
        "currency": "USD",
        "device": null,
        "browser": null,
        "os": null,
        "country": null,
        "city": null,
        "is_synthetic": false
      }
    ],
    "total_count": 12
  },
  "meta": {
    "profile_id": "uuid"
  }
}

Response fields

Journey by Your Customer Key

GET /api/v1/customers/journey?customer_key={your_customer_id}
GET /api/v1/conversions/{id}/journey

The first returns one person's whole timeline, named by the customer id you send as user_traits.external_id on every event, so you never store Atribu's customer id. The second returns the timeline behind one conversion, named by its outcome_event_id, a conversions.id, or your own event key.

Scope: conversions:read or customers:read. The scope decides the shape: with customers:read, the rows above plus the person's name and identifiers in meta.person; without it, a projection with the touches, channels, campaigns, ad sets, ads and credit, and no person, page, device, location or session fields. ?email= / ?phone= instead of customer_key need customers:read. The projected shape is documented in Partner apps.

A key that names nobody in this profile (unknown, erased, or another profile's customer) answers 404 customer_not_found; a conversion handle that names nothing answers 404 conversion_not_found. Both are distinct from not_found, which also means "this deployment does not serve that route".

Customer Search

GET /api/v1/customers/search — find a customer by name, email or phone.

Built for a picker: an operator choosing which customer an unlinked conversation or payment belongs to. A query shorter than two characters returns an empty list rather than the whole book, so it is safe to call on every keystroke behind a short debounce.

Parameters

Requires the customers:read scope, the same tier as the customer list.

Each candidate carries customer_profile_id, first_name, last_name, primary_email, primary_phone, first_seen_at, last_seen_at, conversion_count, cash_revenue and sources. cash_revenue is an exact decimal string — parse it before doing arithmetic.

Journey Summary

GET /api/v1/customers/{id}/journey-summary returns the stored AI summary of one customer's journey, and never calls a model: a null summary with cached: false means none has been generated yet.

POST /api/v1/customers/{id}/journey-summary generates one from the first 100 events of the timeline and stores it, replacing any previous summary. It draws one unit from the workspace's daily AI allowance; when that is spent the call answers 429 with a Retry-After naming the next UTC midnight. A customer with no events returns a null summary and costs nothing.

A healthcare-family profile — its workspace is a healthcare agency, or the profile runs in platform_safe or hipaa privacy mode — never sends a patient's journey to a model: the call answers 403 forbidden, and so does a profile whose status cannot be read.

{id} is the same visitor id the customer list publishes — a customer id, or an anonymous id for a visitor who was never identified.

Link Identity Tokens

POST /api/v1/customers/link-tokens

Mints an atb_t token for each customer you name, to put on the links in your emails, WhatsApp messages and CRM sequences. When the customer clicks — on their phone, their laptop, any device — the Atribu tracker reads the token, removes it from the address bar, and links that browser to the customer. The visits it makes from then on, and the anonymous ones it already made, count toward that customer.

Scope: attribution:write

Only customers Atribu already knows get a token — a row that matches nobody comes back not_found, and nothing is created. A browser that is already linked to a different customer is never re-assigned by a token.

Request body

Each row uses one selector. If a row carries several, the first in this order wins:

A selector that is present but malformed makes the row invalid. The row does not fall back to another selector.

curl -X POST "https://www.atribu.app/api/v1/customers/link-tokens" \
  -H "Authorization: Bearer atb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expires_in_days": 30,
    "customers": [
      { "customer_key": "c9d2e8f1-cust-8841" },
      { "customer_key": "c9d2e8f1-cust-9107" }
    ]
  }'

Response

{
  "data": {
    "param": "atb_t",
    "minted": 1,
    "not_found": 1,
    "invalid": 0,
    "results": [
      {
        "index": 0,
        "status": "minted",
        "customer_key": "c9d2e8f1-cust-8841",
        "token": "AZ3kq0sV1mN8x4Lr7cTzYbQw2eJp6uHf9gDk5aSx0vWn3oIm8tRc1yUe4hGj7lKb2zXq6pNs9dMf0wVa3rTy5uIo8eQ",
        "expires_at": "2026-10-25T14:00:00.000Z"
      },
      {
        "index": 1,
        "status": "not_found",
        "customer_key": "c9d2e8f1-cust-9107",
        "reason": "no_match",
        "message": "No customer in this profile matches this row. Nothing was created."
      }
    ],
    "recipes": [
      { "channel": "gohighlevel", "store_token_in": "…", "link_template": "…", "merge_tag": "…", "requires": "…" }
    ]
  },
  "meta": { "profile_id": "0b6f1c2e-5d4a-4f3b-9e8d-7c6b5a4f3e2d" }
}

Every row carries customer_key: on a minted row, the key the customer holds (after a merge, the surviving customer's key); on any other row, the key you sent, or null. customer_profile_id appears on minted rows only for a key with customers:read. Partner keys on healthcare profiles never hold that scope, so they never receive it.

A row that did not mint carries a reason your screen can branch on, and an English message. For example, a row sent with an unsupported identifier_type comes back as:

{
  "index": 0,
  "status": "invalid",
  "customer_key": null,
  "reason": "unknown_identifier_type",
  "message": "identifier_type must be one of external_customer_id, ghl_contact_id, shopify_customer_id, stripe_customer_id, national_id."
}

All reasons:

A row's status: "not_found" is a per-row result inside a 200 response, not an HTTP error code; the request itself succeeded.

When the deployment has no token secret configured, the endpoint answers 503 with code link_tokens_disabled. The feature is off, not down, so don't retry. Send your links without atb_t.

Merge-tag recipes

No email or messaging tool can create a token at send time, so the setup is the same two steps everywhere: save each customer's token on their contact (from the response above), then add the tool's merge tag to your links. If your link already has a ?, use &atb_t= instead of ?atb_t=.

The Atribu tracker must be installed on the landing page. Links that point at a page without it are not linked.

Pages your app renders (partner_page)

A partner app that renders the page itself, such as a quote to accept or a booking to confirm, already knows the customer by its own key:

1. When you build the message, mint by customer_key and put the token on the link: https://your-app.com/quotes/q_48213?atb_t=<token>.
2. Serve the profile's tracker on that page. Serve it through a same-origin collector, so the visitor id is a first-party cookie that Safari does not cap at 7 days.
3. When the customer opens the link, the tracker removes atb_t from the address bar and links the browser to the customer. Later visits from that browser, with or without a token, count toward them.

A tampered or expired token is ignored. The page still loads and the visit still counts, just not toward the customer.

Customer erasure by your key

POST /api/v1/customers/erasures
GET  /api/v1/customers/erasures/{erasure_id}

For a partner app that deletes a contact on its side, through its own archive flow or a data-subject request, and must cascade that erasure to Atribu. Call it when your contact is deleted and keep the receipt.

Scope: attribution:write (healthcare keys hold it). The attribution add-on is not required: a profile without it can still erase.

API keys only. A console session or an MCP user token gets 403 api_key_required. To erase as a person, use POST /api/v1/workspaces/{workspaceId}/customer-erasures as a workspace owner or admin. The receipt records the API key that asked.

The erasure removes the customer's personal data from this profile: name, email, phone and every identifier, conversation content, and the personal fields of their raw events. Their conversions, touches and attribution stay, without a person attached, so reports and ROAS do not change. Afterwards:

• GET /api/v1/customers/journey?customer_key= for that key answers 404 customer_not_found.
• Link tokens minted for the customer no longer link a browser, and minting by the key answers not_found with reason erased.

It cannot be undone. Conversions already delivered to Meta or Google are outside Atribu's reach.

Request body

Name the customer with exactly one selector. A body with none, or with two, is refused, because an erasure cannot be undone.

curl -X POST "https://www.atribu.app/api/v1/customers/erasures" \
  -H "Authorization: Bearer atb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_ref": "crm:contact-archive:8f1a2c",
    "customer_key": "c9d2e8f1-cust-8841",
    "reason": "data_subject_request"
  }'

Response

{
  "data": {
    "erasure_id": "3f0b8c1e-6a2d-4c7b-9e15-2d8a4f6b1c90",
    "request_ref": "crm:contact-archive:8f1a2c",
    "status": "done",
    "customer_key": "c9d2e8f1-cust-8841",
    "reason": "data_subject_request",
    "requested_at": "2026-09-25T18:04:11.201Z",
    "completed_at": "2026-09-25T18:04:11.305Z"
  },
  "meta": { "profile_id": "0b6f1c2e-5d4a-4f3b-9e8d-7c6b5a4f3e2d" }
}

The receipt never carries customer_profile_id, for any key.

GET /api/v1/customers/erasures/{erasure_id} answers 404 erasure_not_found for an id that is not a receipt of this profile. Both codes are distinct from not_found, which also means "this deployment does not serve that route", so branch on the code, not the status.

Receipts live with the profile: deleting the profile deletes them. Atribu's own audit record of each erasure stays.

Related