Leads, boards and activities

Overview

A lead is a person or company in a team's pipeline: their contact details, where they stand (board and stage), their status and their contact_permissions. A record with record_kind: "client" is a client rather than a lead: it has no pipeline status, so its status is null. Leads and clients come from the same endpoints.

The eight statuses are new, contacted, qualified, negotiating, converted, lost, archived and unreachable. converted does not mean "won". A lead whose status this version of the API does not know keeps record_kind: "lead" and reads status: null. An archived lead says why in archive_reason, including merged and family_transfer for the leads that merges and transfers leave behind.

Apply contact_permissions before any of your systems contacts the person: Keep a copy in sync explains each one.

Attribution and response

GET /v1/leads/{id} returns the lead with two facets: attribution, where it came from, and response, how the team has answered it across its conversations and calls. Each facet has its own version, so a new message changes the lead's response without changing the lead. A facet is null while Totem is still preparing it. Lists return the lead alone. The changes feed delivers the facets as items of their own, lead_attribution and lead_response, with the lead's id. Data coverage explains what each facet can and cannot tell you.

Search by phone or email

POST /v1/leads/search finds a team's leads by exact phone or email. Send exactly one of phone or email in the JSON body, never in a URL:

curl https://api.totemstudio.ai/v1/leads/search \
  -H "Authorization: Bearer $TOTEM_API_KEY" \
  -H "Totem-Team: $TOTEM_TEAM_ID" \
  -H "Content-Type: application/json" \
  -d '{"email": "alex.rivera@example.com"}'

Matching is exact on the number as Totem stores it, not on the normalized phone a lead shows. A phone matches a record stored in E.164, with or without its leading +; a record stored with spaces or without its country prefix is not found, even by the phone the API returns for it. An email matches the address as you sent it or in lower case. Records Totem has not delivered to the API yet are skipped until it does. Search returns archived, merged and client records too; follow merged_into to the lead that was kept. It returns at most 10 leads, in one response that never pages, so when many records share a phone number or an email address, it may not return them all.

Activities

GET /v1/leads/{id}/activities returns a lead's history, a page at a time: each change of its stage, status or assigned members, and when it happened. actor_kind says who made it: a person (human), the AI (ai), Totem automation (system), an API caller (api), or unknown. Totem knows who made a change only when the same save wrote the lead's status, so a stage or assignee change made on its own reads unknown. Pages are not in date order, so sort by occurred_at. Activities never change once written, but they are removed together with their lead, and new ones also arrive in the changes feed.

Boards and stages

A board is a pipeline, with its stages in order. A lead's stage names the step it is on. Each stage has a mode that says who moves leads: people only (standard), people and the AI, which may move leads in (supervised), or the AI, which runs outreach and moves leads in and out (automated).

GET /v1/boards returns a team's boards with their stages, a page at a time. Boards also travel in the changes feed; read this list when a lead names a stage you have not seen yet. A stage with no stored position is left out of its board, so do not re-read the list for a stage it did not include last time.

List leads

GET /v1/leads

Returns a page of the team's leads and clients, in a stable order that carries no meaning. Filter by at most one of board, stage or status; a board or stage the team does not have returns an empty page. To keep a copy up to date, follow the changes feed instead of re-reading this list.

Scopes: crm:read
Rate limit: Sync

Query parameters

limit integer Range 1–100 Default 25
Items per page, 1–100. Defaults to 25.
cursor string 1–512 chars
The next_cursor of the previous page. Omit it for the first page.
board string ID prefix brd_…
Only leads on this board. At most one of board, stage and status.
stage string ID prefix stg_…
Only leads in this stage. At most one of board, stage and status.
status string
Only leads with this status. At most one of board, stage and status.
Possible values
- new
- contacted
- qualified
- negotiating
- converted
- lost
- archived
- unreachable

Headers

Totem-Team string Conditional ID prefix team_…
The team to read, as a team_… id. Omit it when the key reads one team; it is required when the key reads several (400 team_required). When you send it, it must name a team the key reads: a malformed id gets 400 invalid_request, and a team outside the key gets 404 team_not_accessible, as does a request without it once the key reads no team at all.

Returns

Returns a list of Lead objects.

object string
Always list.
data Array<Lead>
The items of this page.
has_more boolean
true when another page follows: fetch it with next_cursor, even if this page holds fewer items than limit.
next_cursor string Nullable
Opaque cursor for the next page, or null on the last page. Never parse it.

Errors

400 team_required Team required
403 team_state_restricted Team restricted
403 sector_restricted Sector restricted
404 team_not_accessible Team not accessible
409 capture_not_ready Team data is still being prepared
429 quota_exceeded Daily quota exceeded

+ 12 common errors

curl 'https://api.totemstudio.ai/v1/leads?limit=25' \
  -H "Authorization: Bearer $TOTEM_API_KEY" \
  -H "Totem-Team: $TOTEM_TEAM_ID"

{
  "object": "list",
  "data": [
    {
      "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
      "object": "lead",
      "livemode": false,
      "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
      "record_kind": "lead",
      "name": "Alex",
      "surname": "Rivera",
      "email": "alex.rivera@example.com",
      "company": "Example Dental",
      "phone": "+12025550123",
      "phone_status": "valid",
      "status": "contacted",
      "status_set_by": "ai",
      "archive_reason": null,
      "archived_from_status": null,
      "contact_permissions": {
        "do_not_contact": false,
        "email_opt_out": false,
        "email_opt_out_at": null,
        "whatsapp_consent": null,
        "provenance": {
          "do_not_contact": null,
          "email_opt_out": null,
          "whatsapp_consent": null
        }
      },
      "merged_into": null,
      "transferred_to": null,
      "revived_at": null,
      "pipeline_cleared": false,
      "converted_at": null,
      "value_at_conversion": null,
      "priority": "high",
      "tags": [
        "spring-check-up"
      ],
      "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst",
      "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
      "assignees": [
        "mem_h548E7UiYhutHhucVrQCzkM0eaea0"
      ],
      "estimated_value": 1200,
      "estimated_value_currency": null,
      "source": "meta_lead_ads",
      "source_channel": null,
      "source_detail": null,
      "source_provenance": "member_editable",
      "created_at": "2026-09-28T10:15:00.000Z",
      "version": 3,
      "updated_at": "2026-09-28T10:20:01.250Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJ2IjoxLCJrIjoibGVhZCIsImEiOiJsZWFkX3I3MkVmYlJOVXp1cU9SRkpSME84SHhBd0VYZDkzakdVVFlNYU1NWEtTRjBRYkxTOENpVUtKcEVQMzRMRlFHIiwicyI6ImYzNTI3NzI2MTkwYiJ93iHyRg"
}

Get a lead with its attribution and response

GET /v1/leads/{id}

Returns one lead with its two facets: attribution (where it came from) and response (how the team has answered it), each with its own version. A lead created moments ago can answer 404 resource_missing until Totem has prepared it; the changes feed delivers it then.

Scopes: crm:read
Rate limit: Read

Path parameters

id string Required ID prefix lead_…
The lead's public id.

Returns

Returns a LeadDetail object.

id string ID prefix lead_…
Public id of the record.
object string
Always lead.
livemode boolean
true for real data; false in example data.
team string ID prefix team_…
The team the record belongs to.
record_kind string
lead when the record has a pipeline status, otherwise client. A lead whose status this version does not know reads status: null.
Possible values
- lead
- client
name string Nullable
First name or display name, or null.
surname string Nullable
Surname, or null.
email string Nullable
Email address as stored, or null.
company string Nullable
Company, or null.
phone string Nullable
Phone in E.164, only when the stored number validates; otherwise null.
phone_status string
valid (see phone), invalid (a number is stored but does not validate, for example one stored without its country prefix) or missing.
Possible values
- valid
- invalid
- missing
status string Nullable
Pipeline status; null for a client record, or for a status this version does not know. converted is not "won".
Possible values
- new
- contacted
- qualified
- negotiating
- converted
- lost
- archived
- unreachable
status_set_by string Nullable
Who set the current status: a person, the AI, Totem automation, an API caller, or unknown (no recorded transition lands on it). Null when status is null.
Possible values
- human
- ai
- system
- api
- unknown
archive_reason string Nullable
Why the record was archived, as a closed code; stored free text is other. Null when none is stored.
Possible values
- opt_out
- no_consent
- not_interested
- not_qualified
- no_contact
- merged
- family_transfer
- other
archived_from_status string Nullable
The status the lead had before its current archive; null while it is not archived or when unknown.
Possible values
- new
- contacted
- qualified
- negotiating
- converted
- lost
- archived
- unreachable
contact_permissions object
Contact permissions. Apply them before any outreach from your own systems.
- do_not_contact boolean
  True when the person asked never to be contacted (the opt_out archive reason). Stop every channel.
- email_opt_out boolean
  True when the person unsubscribed from marketing and follow-up email.
- email_opt_out_at string Nullable Format date-time
  When the email opt-out was recorded, or null.
- whatsapp_consent boolean Nullable
  WhatsApp consent: false when refused, true when recorded, null when unknown.
- provenance object
  The source of each permission.
merged_into string Nullable ID prefix lead_…
The lead this record was merged into, or null (also when that lead no longer exists).
transferred_to object Nullable
Where a transfer to another team of your organization sent this lead, or null. The team may be one your key does not read.
- team string ID prefix team_…
  The destination team.
- lead string Nullable ID prefix lead_…
  The destination lead, or null when its id cannot be named across teams: an assistant handoff created it, or the transfer landed on an existing lead-ads lead (Meta, Google Ads or LinkedIn) or another lead with a fixed id.
revived_at string Nullable Format date-time
When the contact last came back on their own and revived an archived lead, or null.
pipeline_cleared boolean
True when the lead was converted with "clear pipeline data": board, stage, priority, assignees, estimated value and the source fields other than source_channel are null because they were cleared.
converted_at string Nullable Format date-time
When the lead was converted, while its status is converted; otherwise null.
value_at_conversion number Nullable
The estimated value when it was converted, in major units. Survives "clear pipeline data".
priority string Nullable
Priority, or null.
Possible values
- low
- medium
- high
- urgent
tags Array<string>
Labels as stored. lead and booking are system labels.
board string Nullable ID prefix brd_…
The board, resolved through the stage when it has one; or null.
stage string Nullable ID prefix stg_…
The stage, or null.
assignees Array<string> Nullable ID prefix mem_…
Assigned members, sorted. Null when the record has no pipeline data.
estimated_value number Nullable
Estimated value in major units as stored (decimals allowed), or null.
estimated_value_currency null Nullable
Always null: Totem stores no currency with the value.
source string Nullable
The stored lead source; api also covers leads created by Totem itself (for example from a conversation or a call), see source_detail. Null when none is stored.
Possible values
- meta_lead_ads
- manual
- website_form
- booking_page
- csv_import
- api
- chatbot
- google_ads
- linkedin
- other
source_channel string Nullable
The channel the record started on (for example whatsapp, phone, widget), or null. Team members can edit it.
source_detail string Nullable
conversation, call, external:<provider>, gated_ad:<source>, family_handoff, api_intake or unknown; null when source needs no detail.
source_provenance string Nullable
server_written when Totem set the source from what the ad platform reported; otherwise member_editable (team members can change it). Null with source.
Possible values
- server_written
- member_editable
created_at string Format date-time
When the record was created.
version integer Range ≥ 1
Increases every time one of the record's exported fields changes. Apply a change only when its version is greater than the one you hold.
updated_at string Format date-time
When Totem recorded this version (UTC). It is not the time the business event happened.
attribution LeadAttribution Nullable
The lead's attribution facet, or null while Totem is still preparing it.
response LeadResponse Nullable
The lead's response facet, or null while Totem is still preparing it.

Errors

403 team_state_restricted Team restricted
403 sector_restricted Sector restricted
404 resource_missing Resource not found
409 capture_not_ready Team data is still being prepared

+ 12 common errors

curl 'https://api.totemstudio.ai/v1/leads/lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG' \
  -H "Authorization: Bearer $TOTEM_API_KEY"

{
  "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
  "object": "lead",
  "livemode": false,
  "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "record_kind": "lead",
  "name": "Alex",
  "surname": "Rivera",
  "email": "alex.rivera@example.com",
  "company": "Example Dental",
  "phone": "+12025550123",
  "phone_status": "valid",
  "status": "contacted",
  "status_set_by": "ai",
  "archive_reason": null,
  "archived_from_status": null,
  "contact_permissions": {
    "do_not_contact": false,
    "email_opt_out": false,
    "email_opt_out_at": null,
    "whatsapp_consent": null,
    "provenance": {
      "do_not_contact": null,
      "email_opt_out": null,
      "whatsapp_consent": null
    }
  },
  "merged_into": null,
  "transferred_to": null,
  "revived_at": null,
  "pipeline_cleared": false,
  "converted_at": null,
  "value_at_conversion": null,
  "priority": "high",
  "tags": [
    "spring-check-up"
  ],
  "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst",
  "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
  "assignees": [
    "mem_h548E7UiYhutHhucVrQCzkM0eaea0"
  ],
  "estimated_value": 1200,
  "estimated_value_currency": null,
  "source": "meta_lead_ads",
  "source_channel": null,
  "source_detail": null,
  "source_provenance": "member_editable",
  "created_at": "2026-09-28T10:15:00.000Z",
  "version": 3,
  "updated_at": "2026-09-28T10:20:01.250Z",
  "attribution": {
    "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
    "object": "lead_attribution",
    "livemode": false,
    "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
    "original_capture": {
      "capture": "at_creation",
      "captured_at": "2026-09-28T10:15:00.000Z",
      "source": "meta_lead_ads",
      "source_hint": null,
      "source_channel": null,
      "external_provider": null,
      "received_at": "2026-09-28T10:15:00.000Z",
      "submitted_at": "2026-09-28T10:14:30.000Z",
      "origin": null,
      "campaign": {
        "id": {
          "value": "120210000000000101",
          "provenance": "provider"
        },
        "name": {
          "value": "Spring check-up",
          "provenance": "provider"
        }
      },
      "ad": {
        "id": {
          "value": "120210000000000303",
          "provenance": "provider"
        },
        "name": {
          "value": "Free first visit",
          "provenance": "provider"
        }
      },
      "ad_set": {
        "id": {
          "value": "120210000000000202",
          "provenance": "provider"
        },
        "name": {
          "value": "Families nearby",
          "provenance": "provider"
        }
      },
      "ad_group": {
        "id": {
          "value": null,
          "provenance": "not_captured"
        }
      },
      "form": {
        "id": {
          "value": "900000000000000404",
          "provenance": "provider"
        },
        "name": {
          "value": "Book a check-up",
          "provenance": "provider"
        }
      },
      "creative": {
        "id": {
          "value": null,
          "provenance": "not_captured"
        }
      },
      "asset_group": {
        "id": {
          "value": null,
          "provenance": "not_captured"
        }
      },
      "page": {
        "id": {
          "value": "100000000000000505",
          "provenance": "provider"
        },
        "name": {
          "value": "Example Dental",
          "provenance": "provider"
        }
      },
      "utm": null,
      "click_network": {
        "value": null,
        "provenance": "not_captured"
      },
      "ad_referral": null,
      "family_origin": null,
      "audience": {
        "value": null,
        "missing_reason": "unsupported"
      }
    },
    "original_capture_missing_reason": null,
    "latest_submission": null,
    "latest_submission_missing_reason": "not_captured",
    "version": 1,
    "updated_at": "2026-09-28T10:15:02.100Z"
  },
  "response": {
    "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
    "object": "lead_response",
    "livemode": false,
    "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
    "last_inbound_at": "2026-10-01T08:58:00.000Z",
    "last_outbound_at": "2026-10-01T08:59:30.000Z",
    "awaiting_reply": false,
    "last_answered_call_at": "2026-09-28T10:17:00.000Z",
    "last_whatsapp_delivery_status": "read",
    "coverage": {
      "conversations": 2,
      "calls": 1,
      "channels_without_delivery_data": [
        "email"
      ],
      "truncated": false
    },
    "version": 7,
    "updated_at": "2026-10-01T08:59:31.040Z"
  }
}

Find leads by exact phone or email

POST /v1/leads/search

Finds the team's leads whose phone or email matches exactly, including archived, merged and client records (follow merged_into to the lead that was kept). Send exactly one of phone or email in the JSON body, never in the URL. Returns at most 10 leads, chosen from the first 20 records that match, in one response that never paginates.

Scopes: crm:read
Rate limit: Read

Headers

Totem-Team string Conditional ID prefix team_…
The team to read, as a team_… id. Omit it when the key reads one team; it is required when the key reads several (400 team_required). When you send it, it must name a team the key reads: a malformed id gets 400 invalid_request, and a team outside the key gets 404 team_not_accessible, as does a request without it once the key reads no team at all.

Request body

Exactly one of phone or email, in the JSON body and never in the URL.

phone string Conditional 3–40 chars
A phone number in E.164 (+12025550123). It finds the number stored in E.164, with or without the +, and in the layouts phone libraries write: +1 202-555-0123, (202) 555-0123 and 2025550123. Other layouts, such as 202 555 0123, are not found.
email string Conditional 3–254 chars
An email address. It finds records stored exactly as sent, or stored in lowercase.

Returns

Returns a list of Lead objects.

object string
Always list.
data Array<Lead> ≤ 10 items
The matching leads: at most 10.
has_more boolean
Always false, even when more records match: search returns at most 10 leads and has no next page.
next_cursor null Nullable
Always null: search does not paginate.

Errors

400 team_required Team required
403 team_state_restricted Team restricted
403 sector_restricted Sector restricted
404 team_not_accessible Team not accessible
409 capture_not_ready Team data is still being prepared

+ 12 common errors

curl -X POST 'https://api.totemstudio.ai/v1/leads/search' \
  -H "Authorization: Bearer $TOTEM_API_KEY" \
  -H "Totem-Team: $TOTEM_TEAM_ID" \
  -H "Content-Type: application/json" \
  --data '{"phone": "+12025550123"}'

{
  "object": "list",
  "data": [
    {
      "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
      "object": "lead",
      "livemode": false,
      "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
      "record_kind": "lead",
      "name": "Alex",
      "surname": "Rivera",
      "email": "alex.rivera@example.com",
      "company": "Example Dental",
      "phone": "+12025550123",
      "phone_status": "valid",
      "status": "contacted",
      "status_set_by": "ai",
      "archive_reason": null,
      "archived_from_status": null,
      "contact_permissions": {
        "do_not_contact": false,
        "email_opt_out": false,
        "email_opt_out_at": null,
        "whatsapp_consent": null,
        "provenance": {
          "do_not_contact": null,
          "email_opt_out": null,
          "whatsapp_consent": null
        }
      },
      "merged_into": null,
      "transferred_to": null,
      "revived_at": null,
      "pipeline_cleared": false,
      "converted_at": null,
      "value_at_conversion": null,
      "priority": "high",
      "tags": [
        "spring-check-up"
      ],
      "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst",
      "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
      "assignees": [
        "mem_h548E7UiYhutHhucVrQCzkM0eaea0"
      ],
      "estimated_value": 1200,
      "estimated_value_currency": null,
      "source": "meta_lead_ads",
      "source_channel": null,
      "source_detail": null,
      "source_provenance": "member_editable",
      "created_at": "2026-09-28T10:15:00.000Z",
      "version": 3,
      "updated_at": "2026-09-28T10:20:01.250Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

List a lead's activities

GET /v1/leads/{id}/activities

Returns a page of the lead's activities: each change of its stage, status or assigned members, with when it happened and, when Totem recorded it, who made it. Pages are not in date order, so sort by occurred_at. Activities never change once written, and new ones also arrive in the changes feed.

Scopes: crm:read
Rate limit: Sync

Path parameters

id string Required ID prefix lead_…
The lead's public id.

Query parameters

limit integer Range 1–100 Default 25
Items per page, 1–100. Defaults to 25.
cursor string 1–512 chars
The next_cursor of the previous page. Omit it for the first page.

Returns

Returns a list of Activity objects.

object string
Always list.
data Array<Activity>
The items of this page.
has_more boolean
true when another page follows: fetch it with next_cursor, even if this page holds fewer items than limit.
next_cursor string Nullable
Opaque cursor for the next page, or null on the last page. Never parse it.

Errors

403 team_state_restricted Team restricted
403 sector_restricted Sector restricted
404 resource_missing Resource not found
409 capture_not_ready Team data is still being prepared
429 quota_exceeded Daily quota exceeded

+ 12 common errors

curl 'https://api.totemstudio.ai/v1/leads/lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG/activities?limit=25' \
  -H "Authorization: Bearer $TOTEM_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "act_aBgzeetVKDEjpAAkXfEFF53ZGd2ZMmGhUDKgagqLbh6c7R1GqOl0xsFw7pyRhD3SqqYWGMdb371xxj",
      "object": "activity",
      "livemode": false,
      "type": "stage_changed",
      "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
      "lead": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
      "occurred_at": "2026-09-28T10:20:00.000Z",
      "actor_kind": "ai",
      "stage_snapshot": {
        "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
        "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst",
        "name": "Contacted"
      },
      "value_snapshot": 1200,
      "from": {
        "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVR3422Yg",
        "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst"
      },
      "to": {
        "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
        "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst"
      },
      "version": 1,
      "updated_at": "2026-09-28T10:20:01.500Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

List boards with their stages

GET /v1/boards

Returns a page of the team's boards, each with its stages in pipeline order. Boards also arrive in the changes feed; read this list when you need them at once, for example when a lead names a stage you have not seen yet.

Scopes: crm:read
Rate limit: Sync

Query parameters

limit integer Range 1–100 Default 25
Items per page, 1–100. Defaults to 25.
cursor string 1–512 chars
The next_cursor of the previous page. Omit it for the first page.

Headers

Totem-Team string Conditional ID prefix team_…
The team to read, as a team_… id. Omit it when the key reads one team; it is required when the key reads several (400 team_required). When you send it, it must name a team the key reads: a malformed id gets 400 invalid_request, and a team outside the key gets 404 team_not_accessible, as does a request without it once the key reads no team at all.

Returns

Returns a list of Board objects.

object string
Always list.
data Array<Board>
The items of this page.
has_more boolean
true when another page follows: fetch it with next_cursor, even if this page holds fewer items than limit.
next_cursor string Nullable
Opaque cursor for the next page, or null on the last page. Never parse it.

Errors

400 team_required Team required
403 team_state_restricted Team restricted
403 sector_restricted Sector restricted
404 team_not_accessible Team not accessible
409 capture_not_ready Team data is still being prepared
429 quota_exceeded Daily quota exceeded

+ 12 common errors

curl 'https://api.totemstudio.ai/v1/boards?limit=25' \
  -H "Authorization: Bearer $TOTEM_API_KEY" \
  -H "Totem-Team: $TOTEM_TEAM_ID"

{
  "object": "list",
  "data": [
    {
      "id": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst",
      "object": "board",
      "livemode": false,
      "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
      "name": "New patients",
      "is_default": true,
      "is_archived": false,
      "appointment_booked_stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVT1QpfZ5",
      "stages": [
        {
          "object": "stage",
          "id": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVR3422Yg",
          "name": "New",
          "position": 0,
          "is_default": true,
          "is_final": false,
          "is_archive": false,
          "mode": "automated"
        },
        {
          "object": "stage",
          "id": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
          "name": "Contacted",
          "position": 1,
          "is_default": false,
          "is_final": false,
          "is_archive": false,
          "mode": "supervised"
        },
        {
          "object": "stage",
          "id": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVT1QpfZ5",
          "name": "Visit booked",
          "position": 2,
          "is_default": false,
          "is_final": true,
          "is_archive": false,
          "mode": "standard"
        }
      ],
      "version": 4,
      "updated_at": "2026-09-02T16:40:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

The `Lead` object

A lead or client record: lead fields only.

Attributes

id string ID prefix lead_…
Public id of the record.
object string
Always lead.
livemode boolean
true for real data; false in example data.
team string ID prefix team_…
The team the record belongs to.
record_kind string
lead when the record has a pipeline status, otherwise client. A lead whose status this version does not know reads status: null.
Possible values
- lead
- client
name string Nullable
First name or display name, or null.
surname string Nullable
Surname, or null.
email string Nullable
Email address as stored, or null.
company string Nullable
Company, or null.
phone string Nullable
Phone in E.164, only when the stored number validates; otherwise null.
phone_status string
valid (see phone), invalid (a number is stored but does not validate, for example one stored without its country prefix) or missing.
Possible values
- valid
- invalid
- missing
status string Nullable
Pipeline status; null for a client record, or for a status this version does not know. converted is not "won".
Possible values
- new
- contacted
- qualified
- negotiating
- converted
- lost
- archived
- unreachable
status_set_by string Nullable
Who set the current status: a person, the AI, Totem automation, an API caller, or unknown (no recorded transition lands on it). Null when status is null.
Possible values
- human
- ai
- system
- api
- unknown
archive_reason string Nullable
Why the record was archived, as a closed code; stored free text is other. Null when none is stored.
Possible values
- opt_out
- no_consent
- not_interested
- not_qualified
- no_contact
- merged
- family_transfer
- other
archived_from_status string Nullable
The status the lead had before its current archive; null while it is not archived or when unknown.
Possible values
- new
- contacted
- qualified
- negotiating
- converted
- lost
- archived
- unreachable
contact_permissions object
Contact permissions. Apply them before any outreach from your own systems.
- do_not_contact boolean
  True when the person asked never to be contacted (the opt_out archive reason). Stop every channel.
- email_opt_out boolean
  True when the person unsubscribed from marketing and follow-up email.
- email_opt_out_at string Nullable Format date-time
  When the email opt-out was recorded, or null.
- whatsapp_consent boolean Nullable
  WhatsApp consent: false when refused, true when recorded, null when unknown.
- provenance object
  The source of each permission.
merged_into string Nullable ID prefix lead_…
The lead this record was merged into, or null (also when that lead no longer exists).
transferred_to object Nullable
Where a transfer to another team of your organization sent this lead, or null. The team may be one your key does not read.
- team string ID prefix team_…
  The destination team.
- lead string Nullable ID prefix lead_…
  The destination lead, or null when its id cannot be named across teams: an assistant handoff created it, or the transfer landed on an existing lead-ads lead (Meta, Google Ads or LinkedIn) or another lead with a fixed id.
revived_at string Nullable Format date-time
When the contact last came back on their own and revived an archived lead, or null.
pipeline_cleared boolean
True when the lead was converted with "clear pipeline data": board, stage, priority, assignees, estimated value and the source fields other than source_channel are null because they were cleared.
converted_at string Nullable Format date-time
When the lead was converted, while its status is converted; otherwise null.
value_at_conversion number Nullable
The estimated value when it was converted, in major units. Survives "clear pipeline data".
priority string Nullable
Priority, or null.
Possible values
- low
- medium
- high
- urgent
tags Array<string>
Labels as stored. lead and booking are system labels.
board string Nullable ID prefix brd_…
The board, resolved through the stage when it has one; or null.
stage string Nullable ID prefix stg_…
The stage, or null.
assignees Array<string> Nullable ID prefix mem_…
Assigned members, sorted. Null when the record has no pipeline data.
estimated_value number Nullable
Estimated value in major units as stored (decimals allowed), or null.
estimated_value_currency null Nullable
Always null: Totem stores no currency with the value.
source string Nullable
The stored lead source; api also covers leads created by Totem itself (for example from a conversation or a call), see source_detail. Null when none is stored.
Possible values
- meta_lead_ads
- manual
- website_form
- booking_page
- csv_import
- api
- chatbot
- google_ads
- linkedin
- other
source_channel string Nullable
The channel the record started on (for example whatsapp, phone, widget), or null. Team members can edit it.
source_detail string Nullable
conversation, call, external:<provider>, gated_ad:<source>, family_handoff, api_intake or unknown; null when source needs no detail.
source_provenance string Nullable
server_written when Totem set the source from what the ad platform reported; otherwise member_editable (team members can change it). Null with source.
Possible values
- server_written
- member_editable
created_at string Format date-time
When the record was created.
version integer Range ≥ 1
Increases every time one of the record's exported fields changes. Apply a change only when its version is greater than the one you hold.
updated_at string Format date-time
When Totem recorded this version (UTC). It is not the time the business event happened.

{
  "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
  "object": "lead",
  "livemode": false,
  "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "record_kind": "lead",
  "name": "Alex",
  "surname": "Rivera",
  "email": "alex.rivera@example.com",
  "company": "Example Dental",
  "phone": "+12025550123",
  "phone_status": "valid",
  "status": "contacted",
  "status_set_by": "ai",
  "archive_reason": null,
  "archived_from_status": null,
  "contact_permissions": {
    "do_not_contact": false,
    "email_opt_out": false,
    "email_opt_out_at": null,
    "whatsapp_consent": null,
    "provenance": {
      "do_not_contact": null,
      "email_opt_out": null,
      "whatsapp_consent": null
    }
  },
  "merged_into": null,
  "transferred_to": null,
  "revived_at": null,
  "pipeline_cleared": false,
  "converted_at": null,
  "value_at_conversion": null,
  "priority": "high",
  "tags": [
    "spring-check-up"
  ],
  "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst",
  "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
  "assignees": [
    "mem_h548E7UiYhutHhucVrQCzkM0eaea0"
  ],
  "estimated_value": 1200,
  "estimated_value_currency": null,
  "source": "meta_lead_ads",
  "source_channel": null,
  "source_detail": null,
  "source_provenance": "member_editable",
  "created_at": "2026-09-28T10:15:00.000Z",
  "version": 3,
  "updated_at": "2026-09-28T10:20:01.250Z"
}

The `LeadDetail` object

A lead with its attribution and response facets, each with its own version. A facet is null only while Totem is still preparing it.

Attributes

id string ID prefix lead_…
Public id of the record.
object string
Always lead.
livemode boolean
true for real data; false in example data.
team string ID prefix team_…
The team the record belongs to.
record_kind string
lead when the record has a pipeline status, otherwise client. A lead whose status this version does not know reads status: null.
Possible values
- lead
- client
name string Nullable
First name or display name, or null.
surname string Nullable
Surname, or null.
email string Nullable
Email address as stored, or null.
company string Nullable
Company, or null.
phone string Nullable
Phone in E.164, only when the stored number validates; otherwise null.
phone_status string
valid (see phone), invalid (a number is stored but does not validate, for example one stored without its country prefix) or missing.
Possible values
- valid
- invalid
- missing
status string Nullable
Pipeline status; null for a client record, or for a status this version does not know. converted is not "won".
Possible values
- new
- contacted
- qualified
- negotiating
- converted
- lost
- archived
- unreachable
status_set_by string Nullable
Who set the current status: a person, the AI, Totem automation, an API caller, or unknown (no recorded transition lands on it). Null when status is null.
Possible values
- human
- ai
- system
- api
- unknown
archive_reason string Nullable
Why the record was archived, as a closed code; stored free text is other. Null when none is stored.
Possible values
- opt_out
- no_consent
- not_interested
- not_qualified
- no_contact
- merged
- family_transfer
- other
archived_from_status string Nullable
The status the lead had before its current archive; null while it is not archived or when unknown.
Possible values
- new
- contacted
- qualified
- negotiating
- converted
- lost
- archived
- unreachable
contact_permissions object
Contact permissions. Apply them before any outreach from your own systems.
- do_not_contact boolean
  True when the person asked never to be contacted (the opt_out archive reason). Stop every channel.
- email_opt_out boolean
  True when the person unsubscribed from marketing and follow-up email.
- email_opt_out_at string Nullable Format date-time
  When the email opt-out was recorded, or null.
- whatsapp_consent boolean Nullable
  WhatsApp consent: false when refused, true when recorded, null when unknown.
- provenance object
  The source of each permission.
merged_into string Nullable ID prefix lead_…
The lead this record was merged into, or null (also when that lead no longer exists).
transferred_to object Nullable
Where a transfer to another team of your organization sent this lead, or null. The team may be one your key does not read.
- team string ID prefix team_…
  The destination team.
- lead string Nullable ID prefix lead_…
  The destination lead, or null when its id cannot be named across teams: an assistant handoff created it, or the transfer landed on an existing lead-ads lead (Meta, Google Ads or LinkedIn) or another lead with a fixed id.
revived_at string Nullable Format date-time
When the contact last came back on their own and revived an archived lead, or null.
pipeline_cleared boolean
True when the lead was converted with "clear pipeline data": board, stage, priority, assignees, estimated value and the source fields other than source_channel are null because they were cleared.
converted_at string Nullable Format date-time
When the lead was converted, while its status is converted; otherwise null.
value_at_conversion number Nullable
The estimated value when it was converted, in major units. Survives "clear pipeline data".
priority string Nullable
Priority, or null.
Possible values
- low
- medium
- high
- urgent
tags Array<string>
Labels as stored. lead and booking are system labels.
board string Nullable ID prefix brd_…
The board, resolved through the stage when it has one; or null.
stage string Nullable ID prefix stg_…
The stage, or null.
assignees Array<string> Nullable ID prefix mem_…
Assigned members, sorted. Null when the record has no pipeline data.
estimated_value number Nullable
Estimated value in major units as stored (decimals allowed), or null.
estimated_value_currency null Nullable
Always null: Totem stores no currency with the value.
source string Nullable
The stored lead source; api also covers leads created by Totem itself (for example from a conversation or a call), see source_detail. Null when none is stored.
Possible values
- meta_lead_ads
- manual
- website_form
- booking_page
- csv_import
- api
- chatbot
- google_ads
- linkedin
- other
source_channel string Nullable
The channel the record started on (for example whatsapp, phone, widget), or null. Team members can edit it.
source_detail string Nullable
conversation, call, external:<provider>, gated_ad:<source>, family_handoff, api_intake or unknown; null when source needs no detail.
source_provenance string Nullable
server_written when Totem set the source from what the ad platform reported; otherwise member_editable (team members can change it). Null with source.
Possible values
- server_written
- member_editable
created_at string Format date-time
When the record was created.
version integer Range ≥ 1
Increases every time one of the record's exported fields changes. Apply a change only when its version is greater than the one you hold.
updated_at string Format date-time
When Totem recorded this version (UTC). It is not the time the business event happened.
attribution LeadAttribution Nullable
The lead's attribution facet, or null while Totem is still preparing it.
response LeadResponse Nullable
The lead's response facet, or null while Totem is still preparing it.

{
  "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
  "object": "lead",
  "livemode": false,
  "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "record_kind": "lead",
  "name": "Alex",
  "surname": "Rivera",
  "email": "alex.rivera@example.com",
  "company": "Example Dental",
  "phone": "+12025550123",
  "phone_status": "valid",
  "status": "contacted",
  "status_set_by": "ai",
  "archive_reason": null,
  "archived_from_status": null,
  "contact_permissions": {
    "do_not_contact": false,
    "email_opt_out": false,
    "email_opt_out_at": null,
    "whatsapp_consent": null,
    "provenance": {
      "do_not_contact": null,
      "email_opt_out": null,
      "whatsapp_consent": null
    }
  },
  "merged_into": null,
  "transferred_to": null,
  "revived_at": null,
  "pipeline_cleared": false,
  "converted_at": null,
  "value_at_conversion": null,
  "priority": "high",
  "tags": [
    "spring-check-up"
  ],
  "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst",
  "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
  "assignees": [
    "mem_h548E7UiYhutHhucVrQCzkM0eaea0"
  ],
  "estimated_value": 1200,
  "estimated_value_currency": null,
  "source": "meta_lead_ads",
  "source_channel": null,
  "source_detail": null,
  "source_provenance": "member_editable",
  "created_at": "2026-09-28T10:15:00.000Z",
  "version": 3,
  "updated_at": "2026-09-28T10:20:01.250Z",
  "attribution": {
    "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
    "object": "lead_attribution",
    "livemode": false,
    "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
    "original_capture": {
      "capture": "at_creation",
      "captured_at": "2026-09-28T10:15:00.000Z",
      "source": "meta_lead_ads",
      "source_hint": null,
      "source_channel": null,
      "external_provider": null,
      "received_at": "2026-09-28T10:15:00.000Z",
      "submitted_at": "2026-09-28T10:14:30.000Z",
      "origin": null,
      "campaign": {
        "id": {
          "value": "120210000000000101",
          "provenance": "provider"
        },
        "name": {
          "value": "Spring check-up",
          "provenance": "provider"
        }
      },
      "ad": {
        "id": {
          "value": "120210000000000303",
          "provenance": "provider"
        },
        "name": {
          "value": "Free first visit",
          "provenance": "provider"
        }
      },
      "ad_set": {
        "id": {
          "value": "120210000000000202",
          "provenance": "provider"
        },
        "name": {
          "value": "Families nearby",
          "provenance": "provider"
        }
      },
      "ad_group": {
        "id": {
          "value": null,
          "provenance": "not_captured"
        }
      },
      "form": {
        "id": {
          "value": "900000000000000404",
          "provenance": "provider"
        },
        "name": {
          "value": "Book a check-up",
          "provenance": "provider"
        }
      },
      "creative": {
        "id": {
          "value": null,
          "provenance": "not_captured"
        }
      },
      "asset_group": {
        "id": {
          "value": null,
          "provenance": "not_captured"
        }
      },
      "page": {
        "id": {
          "value": "100000000000000505",
          "provenance": "provider"
        },
        "name": {
          "value": "Example Dental",
          "provenance": "provider"
        }
      },
      "utm": null,
      "click_network": {
        "value": null,
        "provenance": "not_captured"
      },
      "ad_referral": null,
      "family_origin": null,
      "audience": {
        "value": null,
        "missing_reason": "unsupported"
      }
    },
    "original_capture_missing_reason": null,
    "latest_submission": null,
    "latest_submission_missing_reason": "not_captured",
    "version": 1,
    "updated_at": "2026-09-28T10:15:02.100Z"
  },
  "response": {
    "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
    "object": "lead_response",
    "livemode": false,
    "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
    "last_inbound_at": "2026-10-01T08:58:00.000Z",
    "last_outbound_at": "2026-10-01T08:59:30.000Z",
    "awaiting_reply": false,
    "last_answered_call_at": "2026-09-28T10:17:00.000Z",
    "last_whatsapp_delivery_status": "read",
    "coverage": {
      "conversations": 2,
      "calls": 1,
      "channels_without_delivery_data": [
        "email"
      ],
      "truncated": false
    },
    "version": 7,
    "updated_at": "2026-10-01T08:59:31.040Z"
  }
}

The `LeadAttribution` object

Where a lead came from: its original capture and latest submission.

Attributes

id string ID prefix lead_…
Public id of the record.
object string
Always lead_attribution.
livemode boolean
true for real data; false in example data.
team string ID prefix team_…
The team the lead belongs to.
original_capture object Nullable
How the lead first entered the CRM, frozen once; null when it was not captured. "Original" is the first time the contact entered the CRM, not the first ad it answered.
- capture string
  at_creation: frozen from the lead as it was first saved. at_activation: copied once from the lead as it was when the API was activated, for a lead with no capture record (created before Totem started recording attribution, or whose creation was not recorded).
  Possible values
  at_creation
  at_activation
- captured_at string Format date-time
  When the record was written.
- source string Nullable
  The lead source at capture, from the same set as the lead's source; api also covers leads created by Totem itself (for example from a conversation or a call, see origin). Null when none was stored.
  Possible values
  meta_lead_ads
  manual
  website_form
  booking_page
  csv_import
  api
- source_hint string Nullable
  The real source of a gated ad lead stored as api, or null.
- source_channel string Nullable
  The channel at capture, or null.
- external_provider string Nullable
  The portal or booking platform of a forwarded or synced lead, or null.
- received_at string Nullable Format date-time
  When the lead was received, as first written, or null.
- submitted_at string Nullable Format date-time
  When the ad platform says the form was submitted, or null.
- origin object Nullable
  The conversation or call that created the lead (never its id), or null (also for an origin of another kind).
- campaign object
  The campaign.
- ad object
  The ad.
- ad_set object
  The Meta ad set.
- ad_group object
  The Google Ads ad group.
- form object
  The lead form.
- creative object
  The creative.
- asset_group object
  The Google Ads asset group.
- page object
  The Facebook page.
- utm object Nullable
  The five standard UTM keys, or null when none was captured.
- click_network object
  The network of the first click id (google or meta). The click id itself is never kept.
- ad_referral object Nullable
  The first Meta ad referral of the conversation that created the lead, or null.
- family_origin object Nullable
  The transfer from another team of your organization that created the lead, or null.
- audience object
  Not available in this version.
original_capture_missing_reason string Nullable
not_captured when original_capture is null, otherwise null.
Possible values
- not_captured
latest_submission object Nullable
The newest ad submission recorded for this lead, including a repeat on an existing contact; null when none is recorded. A submission the ad platform reports deleted (a LinkedIn member deleting their form response) is no longer shown, and once the newest one expires or is withdrawn an older one can show instead.
- provider string
  The ad platform.
  Possible values
  meta
  google_ads
  linkedin
- submitted_at string Nullable Format date-time
  When the platform says it was submitted, or null.
- campaign object
  The campaign.
- ad object
  The ad.
- ad_set object
  The Meta ad set.
- ad_group object
  The Google Ads ad group.
- form object
  The lead form.
- creative object
  The creative.
- asset_group object
  The Google Ads asset group.
- utm object Nullable
  Its UTM keys, or null.
- expires_at string Nullable Format date-time
  When this submission stops being readable (Google Ads and LinkedIn keep it 90 days); null for Meta.
latest_submission_missing_reason string Nullable
not_captured when latest_submission is null, otherwise null.
Possible values
- not_captured
version integer Range ≥ 1
Increases every time one of the record's exported fields changes. Apply a change only when its version is greater than the one you hold.
updated_at string Format date-time
When Totem recorded this version (UTC). It is not the time the business event happened.

{
  "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
  "object": "lead_attribution",
  "livemode": false,
  "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "original_capture": {
    "capture": "at_creation",
    "captured_at": "2026-09-28T10:15:00.000Z",
    "source": "meta_lead_ads",
    "source_hint": null,
    "source_channel": null,
    "external_provider": null,
    "received_at": "2026-09-28T10:15:00.000Z",
    "submitted_at": "2026-09-28T10:14:30.000Z",
    "origin": null,
    "campaign": {
      "id": {
        "value": "120210000000000101",
        "provenance": "provider"
      },
      "name": {
        "value": "Spring check-up",
        "provenance": "provider"
      }
    },
    "ad": {
      "id": {
        "value": "120210000000000303",
        "provenance": "provider"
      },
      "name": {
        "value": "Free first visit",
        "provenance": "provider"
      }
    },
    "ad_set": {
      "id": {
        "value": "120210000000000202",
        "provenance": "provider"
      },
      "name": {
        "value": "Families nearby",
        "provenance": "provider"
      }
    },
    "ad_group": {
      "id": {
        "value": null,
        "provenance": "not_captured"
      }
    },
    "form": {
      "id": {
        "value": "900000000000000404",
        "provenance": "provider"
      },
      "name": {
        "value": "Book a check-up",
        "provenance": "provider"
      }
    },
    "creative": {
      "id": {
        "value": null,
        "provenance": "not_captured"
      }
    },
    "asset_group": {
      "id": {
        "value": null,
        "provenance": "not_captured"
      }
    },
    "page": {
      "id": {
        "value": "100000000000000505",
        "provenance": "provider"
      },
      "name": {
        "value": "Example Dental",
        "provenance": "provider"
      }
    },
    "utm": null,
    "click_network": {
      "value": null,
      "provenance": "not_captured"
    },
    "ad_referral": null,
    "family_origin": null,
    "audience": {
      "value": null,
      "missing_reason": "unsupported"
    }
  },
  "original_capture_missing_reason": null,
  "latest_submission": null,
  "latest_submission_missing_reason": "not_captured",
  "version": 1,
  "updated_at": "2026-09-28T10:15:02.100Z"
}

The `LeadResponse` object

How the team has answered a lead across its conversations and calls: the latest messages each way and whether a reply is due. It uses its lead's id.

Attributes

id string ID prefix lead_…
Public id of the record.
object string
Always lead_response.
livemode boolean
true for real data; false in example data.
team string ID prefix team_…
The team this record belongs to.
last_inbound_at string Nullable Format date-time
The latest message from the customer on any of the lead's conversations (UTC), or null. Not counted: erased messages, imported WhatsApp history and web-chat visitor turns. Instagram shares cannot be told apart and count.
last_outbound_at string Nullable Format date-time
The latest message sent to the customer that did not fail, on any of the lead's conversations and whoever sent it (UTC), or null. Imported WhatsApp history counts.
awaiting_reply boolean
True when last_inbound_at is newer than the latest reply on any of the lead's conversations. A reply is a sent message that did not fail and was recorded as a conversation reply or with no purpose; outreach, transactional messages (such as reminders) and imported history do not count. Most stored messages carry no purpose, so an automated send recorded without one also counts as a reply. False when the customer has never written.
last_answered_call_at string Nullable Format date-time
When the latest of the lead's calls whose outcome is answered_human or answered_ai started (UTC), or null. A connected outbound call on Totem's phone lines reads unknown, so it is not counted.
last_whatsapp_delivery_status string Nullable
delivered, read or failed for the latest message sent to the lead on WhatsApp. Null when that message has no receipt yet (sent is never stored) or the lead has no message sent on WhatsApp.
Possible values
- delivered
- read
- failed
coverage object
What these facts were computed from.
- conversations integer Range 0–20
  The lead's conversations these facts were computed from, newest first; at most 20.
- calls integer Range 0–50
  The lead's calls last_answered_call_at was computed from, newest first; at most 50.
- channels_without_delivery_data Array<string>
  The channels of those conversations that store no delivery receipts (every channel but WhatsApp), sorted.
  Possible values
  sms
  facebook
  instagram
  tiktok
  chatbot
  email
- truncated boolean
  True when a read limit was reached (20 conversations, 200 messages or 50 calls): older activity was not read, so a time can be null or older than the truth, and awaiting_reply can miss an older reply.
version integer Range ≥ 1
Increases every time one of the record's exported fields changes. Apply a change only when its version is greater than the one you hold.
updated_at string Format date-time
When Totem recorded this version (UTC). It is not the time the business event happened.

{
  "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
  "object": "lead_response",
  "livemode": false,
  "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "last_inbound_at": "2026-10-01T08:58:00.000Z",
  "last_outbound_at": "2026-10-01T08:59:30.000Z",
  "awaiting_reply": false,
  "last_answered_call_at": "2026-09-28T10:17:00.000Z",
  "last_whatsapp_delivery_status": "read",
  "coverage": {
    "conversations": 2,
    "calls": 1,
    "channels_without_delivery_data": [
      "email"
    ],
    "truncated": false
  },
  "version": 7,
  "updated_at": "2026-10-01T08:59:31.040Z"
}

The `Activity` object

One stage, status or assignee transition of a lead. Activities never change once written.

Attributes of every variant

id string ID prefix act_…
Public id of the record.
object string
Always activity.
livemode boolean
true for real data; false in example data.
team string ID prefix team_…
The team the lead belongs to.
lead string Nullable ID prefix lead_…
The lead that moved. Null only while Totem has not yet assigned the lead its id.
occurred_at string Format date-time
When the change was saved.
actor_kind string
Who made the change: a person, the AI, Totem automation, an API caller, or unknown. Totem knows who made a change only when the same save wrote the lead's status, so a stage or assignee change made on its own reads unknown.
Possible values
- human
- ai
- system
- api
- unknown
stage_snapshot object Nullable
The stage the lead was in after the change (for "clear pipeline data", the stage it left), or null.
- stage string Nullable ID prefix stg_…
  The stage.
- board string Nullable ID prefix brd_…
  Its board, or null for a legacy stage without one.
- name string Nullable
  The stage name when the change was recorded, or null when the stage was already deleted.
value_snapshot number Nullable
The estimated value at that moment, in major units, or null.
version integer Range ≥ 1
Increases every time one of the record's exported fields changes. Apply a change only when its version is greater than the one you hold.
updated_at string Format date-time
When Totem recorded this version (UTC). It is not the time the business event happened.

Variants

Each Activity is exactly one of these 3 variants.

A status transition

When type is one of status_changed archived unarchived revived

type string
status_changed, archived, unarchived, or revived (the contact came back on their own and reopened an archived lead).
Possible values
- status_changed
- archived
- unarchived
- revived
from string Nullable
The status before, or null when there was none.
Possible values
- new
- contacted
- qualified
- negotiating
- converted
- lost
- archived
- unreachable
to string
The status after.
Possible values
- new
- contacted
- qualified
- negotiating
- converted
- lost
- archived
- unreachable

A stage move

When type is stage_changed

type string
Always stage_changed.
from object Nullable
The stage and board before, or null when the lead had neither.
- stage string Nullable ID prefix stg_…
  The stage.
- board string Nullable ID prefix brd_…
  The board, or null for a legacy stage without one.
to object
The stage and board after.
- stage string Nullable ID prefix stg_…
  The stage.
- board string Nullable ID prefix brd_…
  The board, or null for a legacy stage without one.

A change of assigned members

When type is assignees_changed

type string
Always assignees_changed.
from Array<string> ID prefix mem_…
The assigned members before, sorted.
to Array<string> ID prefix mem_…
The assigned members after, sorted.

{
  "id": "act_aBgzeetVKDEjpAAkXfEFF53ZGd2ZMmGhUDKgagqLbh6c7R1GqOl0xsFw7pyRhD3SqqYWGMdb371xxj",
  "object": "activity",
  "livemode": false,
  "type": "stage_changed",
  "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "lead": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
  "occurred_at": "2026-09-28T10:20:00.000Z",
  "actor_kind": "ai",
  "stage_snapshot": {
    "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
    "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst",
    "name": "Contacted"
  },
  "value_snapshot": 1200,
  "from": {
    "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVR3422Yg",
    "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst"
  },
  "to": {
    "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
    "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst"
  },
  "version": 1,
  "updated_at": "2026-09-28T10:20:01.500Z"
}

The `Board` object

A board with its stages in pipeline order.

Attributes

id string ID prefix brd_…
Public id of the record.
object string
Always board.
livemode boolean
true for real data; false in example data.
team string ID prefix team_…
The team this record belongs to.
name string Nullable ≥ 1 chars
The board's name, or null when none is stored.
is_default boolean
True for the team's default board, where new leads land unless routed elsewhere.
is_archived boolean
True when the board is archived (hidden from the board selector). Its leads still export.
appointment_booked_stage string Nullable ID prefix stg_…
The stage of this board a lead moves to when its first appointment is confirmed, or null when none is set or it names no stage of this board.
stages Array<object>
The board's stages, ordered by position, then by id. A stage with no position stored at all is left out, although a lead can still name it.
- object string
  Always stage.
- id string ID prefix stg_…
  Public id of the stage; a lead's stage names it.
- name string Nullable ≥ 1 chars
  The stage's name, or null when none is stored.
- position number Nullable
  The stage's position on its board, left to right; null when the stored position is not a number. Stages are listed in this order.
- is_default boolean
  True for the stage new leads of this board enter.
- is_final boolean
  True for a final stage: moving a lead here marks it converted.
- is_archive boolean
  True for an archive stage, whose leads are hidden from the main board view.
- mode string Nullable
  Who moves leads: standard (people only), supervised (AI may move leads in, people move them out) or automated (AI runs outreach and moves leads in and out); null for a value this version does not know.
  Possible values
  standard
  supervised
  automated
version integer Range ≥ 1
Increases every time one of the record's exported fields changes. Apply a change only when its version is greater than the one you hold.
updated_at string Format date-time
When Totem recorded this version (UTC). It is not the time the business event happened.

{
  "id": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst",
  "object": "board",
  "livemode": false,
  "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "name": "New patients",
  "is_default": true,
  "is_archived": false,
  "appointment_booked_stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVT1QpfZ5",
  "stages": [
    {
      "object": "stage",
      "id": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVR3422Yg",
      "name": "New",
      "position": 0,
      "is_default": true,
      "is_final": false,
      "is_archive": false,
      "mode": "automated"
    },
    {
      "object": "stage",
      "id": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
      "name": "Contacted",
      "position": 1,
      "is_default": false,
      "is_final": false,
      "is_archive": false,
      "mode": "supervised"
    },
    {
      "object": "stage",
      "id": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVT1QpfZ5",
      "name": "Visit booked",
      "position": 2,
      "is_default": false,
      "is_final": true,
      "is_archive": false,
      "mode": "standard"
    }
  ],
  "version": 4,
  "updated_at": "2026-09-02T16:40:00.000Z"
}

Overview

Attribution and response

Search by phone or email

Activities

Boards and stages

Query parameters

Headers

Returns

Errors

Path parameters

Returns

Errors

Headers

Request body

Returns

Errors

Path parameters

Query parameters

Returns

Errors

Query parameters

Headers

Returns

Errors

The Lead object

Attributes

The LeadDetail object

Attributes

The LeadAttribution object

Attributes

The LeadResponse object

Attributes

The Activity object

Attributes of every variant

Variants

A status transition

A stage move

A change of assigned members

The Board object

Attributes

The `Lead` object

The `LeadDetail` object

The `LeadAttribution` object

The `LeadResponse` object

The `Activity` object

The `Board` object