BrightshoalDocsOpen console
MenuLeads

API reference

Leads

The details an assistant captured from a visitor, and the outcome you report back once your team follows up.

List leads

GET/api/leads

Leads from chat, calls, SMS, WhatsApp and forms, newest first, one cursor page at a time. Merged leads are excluded. A lead is created when the assistant takes the visitor's details and updated as the conversation goes on; subscribe to the lead.captured webhook to hear about each one as it happens.

Secret API key. How it works

Query parameters

  • project_idstring

    Only this project's leads.

  • assistant_idstring

    Only leads captured by this assistant, intersected with the caller's org and project scope. Unknown or inaccessible assistants return an empty page.

  • form_idstring

    Only leads captured by this form, intersected with the caller's project scope. Unknown or inaccessible forms return an empty page.

  • fromstringISO 8601 timestamp

    Created at or after this time.

  • tostringISO 8601 timestamp

    Created at or before this time.

  • modestring

    Live excludes effective test leads (sandbox, rule-caught and marked as test). Test includes non-live chats and leads classified or marked as test. Preview filters capture mode; all includes every mode. Merged leads are always excluded.

    One of live test preview all

    Default "live"

  • trafficstring

    Comma-separated subset of real, sandbox and test: only leads of those kinds. When given it replaces the default view (and include_test); an explicit mode still narrows. Absent: the default view, unchanged.

  • channelstring

    Only leads captured on this channel (the lead's source): web_chat, web_call, phone_call, sms, whatsapp, form, ad_form, scheduling, other. Several, comma separated, list any of them (web_chat,web_call). Absent: every channel.

  • sourcestring

    Another name for channel, with the same values and comma separated lists; read when channel is absent.

  • statusstring

    Only leads with this status: new, contacted, qualified, won or lost. Several, comma separated, list any of them.

  • attentionstring

    Needs attention, oldest first: uncontacted (status new and never contacted, by created_at), overdue (open, with next_follow_up_at before the start of today, by that date), due_today (open, with next_follow_up_at today, by that date) or any (all three, each lead by the earlier of its keys). Days are read in tz. The other filters still apply.

    One of uncontacted overdue due_today any

  • tzstring

    IANA time zone for attention's days. Default: the project's timezone when you see one project, else UTC. An unknown zone is 400.

  • qstring

    Search: a case-insensitive substring of the name, email, phone or any captured field value. A query with digits also matches the phone's digits alone, so 98765 43210 finds +91 98765-43210.

  • cursorstring

    Opaque next_cursor from the previous page. Legacy ISO timestamp cursors are also accepted.

  • limitinteger1 to 200

    Page size.

    Default 50

Returns

200 OK

Response attributes
  • dataarray of Leadrequired

    40 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • assistant_idstring | null

      The assistant that captured the lead; null when no assistant did (a form lead, or one added by hand).

    • conversation_idstring | null

    • namestring | null

    • emailstring | nullemail

    • phonestring | null

    • fact_provenanceobject

      Provenance per field key, including name, email and phone. Legacy values use lead creation time with captured_at_estimated true; edits retain captured_at and set edited_at and edited_by.

      9 attributes
      • sourcestringrequired

        One of conversation channel form manual

      • channelstringrequired

        One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

      • conversation_idstring | nullrequired

      • call_idstring | nullrequired

      • form_submission_idstring | nullrequired

      • captured_atstringrequiredISO 8601 timestamp

      • captured_at_estimatedbooleanrequired

      • edited_atstring | nullrequiredISO 8601 timestamp

      • edited_bystring | nullrequired

    • fieldsobject | null

    • sourcestringrequired

      Where the lead came from: web_chat, web_call (a call from a browser), phone_call, sms, whatsapp, form, ad_form (an ad platform's own lead form, such as a Google lead form), scheduling (a booking) or other (such as a lead added by hand).

      One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

    • modestring

      Capture provenance: the chat mode, independent of email classification.

      One of live test preview

    • testboolean

      Effective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See traffic to tell them apart.

    • trafficstring

      Which traffic this belongs to: sandbox (made through a non-live key: a sandbox key, the console's sandbox chat, a sandbox phone or WhatsApp number, or a preview link), test (a live chat or lead one of our rules caught: a test marker, a staging or preview page, a placeholder or own-domain email, or marked as test by hand) or real. Sandbox wins over test. Sandbox and test are both left out of real numbers.

      One of real sandbox test

    • test_reasonstring | null

      Automatic classification, recomputed when saved: reserved_domain (placeholder email), business_domain (your own email domain) or staging_site (a live chat on a staging or preview page). An email reason wins over staging_site.

      One of reserved_domain business_domain staging_site

    • test_overrideboolean | null

      Member override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox.

    • outcomestring | null

      What became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).

      One of open booked lost

    • outcome_valuestring | null

      Booking value as a decimal string.

    • outcome_currencystring | null

    • outcome_atstring | nullISO 8601 timestamp

    • outcome_refstring | null

      The CRM's own id for the booking.

    • customer_idstring | null

      The customer's own id for this person, set with PUT /v1/leads/{id}/outcome.

    • statusstring

      The front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts new. new, contacted and qualified are open; won and lost close it. Separate from outcome, which your CRM reports.

      One of new contacted qualified won lost

    • status_changed_atstring | nullISO 8601 timestamp

    • status_changed_bystring | null

      A user id, or the agent.id an API key named.

    • status_changed_by_namestring | null

    • attributionChatAttribution | null

      Where the lead's chat came from. Returned by the list and detail reads; null when none was recorded.

      One of 2 shapes

      ChatAttribution

      • chat_pagestring

        The path the visitor started chatting on.

      • visitChatAttributionTouch

        This visit's landing.

        20 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

      • firstobject

        The visitor's first-ever landing.

        21 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

        • atstringISO 8601 timestamp

          When the visitor first landed.

      • latest_paidobject

        The visitor's latest ad click within 90 days: a landing with a click id, or with utm_medium cpc, ppc or paid*. Recorded even when the click came inside a visit that began elsewhere, and kept through later direct visits, so it can differ from visit and first.

        21 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

        • atstringISO 8601 timestamp

          When the visitor landed from this ad click.

      Option 2

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • capture_methodstring

      How the lead was first saved: tool (the assistant saved it during the conversation), analysis (read from the conversation afterwards), form (a form submission) manual (added by hand) or scheduling (a direct booking). Later updates never change it.

      One of tool analysis form manual scheduling

    • call_idstring | null

      The call the lead came from, when it came from one.

    • form_submission_idstring | null

      The form submission the lead came from, when it came from one.

    • phone_e164string | null

      phone in E.164 form when it could be read as a number; phone stays as given.

    • phone_sourcestring | null

      caller_id when a call lead's phone is the number the call came from, because the caller never said one. Null means the person gave it.

      One of given caller_id

    • first_contacted_atstring | nullISO 8601 timestamp

      The first contact: the earliest logged contact, or the first status change out of new by a person or key. Null until contacted.

    • last_contacted_atstring | nullISO 8601 timestamp

      The latest contact.

    • next_follow_up_atstring | nullISO 8601 timestamp

      When to contact the lead again. Cleared when the lead is won or lost.

    • time_to_first_contact_secondsinteger | null

      Wall clock from created_at to first_contacted_at, in seconds. Null until contacted.

    • uncontacted_nudged_atstring | nullISO 8601 timestamp

      When lead.uncontacted was recorded for the lead; null when it never was.

    • merged_into_idstring | null

      The kept lead's id when this lead was merged. Merged leads remain readable by id.

  • next_cursorstring | nullrequired

    Opaque cursor for the next page.

  • has_morebooleanrequired

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
GET /api/leads
curl "https://api.brightshoal.com/api/leads" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": [
    {
      "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "name": "Front desk",
      "email": "ana@example.com",
      "phone": "+14155550123",
      "fact_provenance": {
        "key": {
          "source": "conversation",
          "channel": "web_chat",
          "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "captured_at": "2026-10-28T09:30:00.000Z",
          "captured_at_estimated": true,
          "edited_at": "2026-10-28T09:30:00.000Z",
          "edited_by": "string"
        }
      },
      "fields": {
        "key": "string"
      },
      "source": "web_chat",
      "mode": "live",
      "test": true,
      "traffic": "real",
      "test_reason": "reserved_domain",
      "test_override": true,
      "outcome": "open",
      "outcome_value": "string",
      "outcome_currency": "string",
      "outcome_at": "2026-10-28T09:30:00.000Z",
      "outcome_ref": "string",
      "customer_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "status": "new",
      "status_changed_at": "2026-10-28T09:30:00.000Z",
      "status_changed_by": "string",
      "status_changed_by_name": "string",
      "attribution": {
        "chat_page": "string",
        "visit": {
          "landing_page": {},
          "referrer_host": {},
          "utm_source": {},
          "utm_medium": {},
          "utm_campaign": {},
          "utm_term": {},
          "utm_content": {},
          "gclid": {},
          "gbraid": {},
          "wbraid": {},
          "fbclid": {},
          "msclkid": {},
          "oppref": {},
          "ctwa_clid": {},
          "ad_id": {},
          "ad_source_type": {},
          "ad_source_url": {},
          "ad_headline": {},
          "whatsapp_link_id": {},
          "whatsapp_link_name": {}
        },
        "first": {
          "landing_page": {},
          "referrer_host": {},
          "utm_source": {},
          "utm_medium": {},
          "utm_campaign": {},
          "utm_term": {},
          "utm_content": {},
          "gclid": {},
          "gbraid": {},
          "wbraid": {},
          "fbclid": {},
          "msclkid": {},
          "oppref": {},
          "ctwa_clid": {},
          "ad_id": {},
          "ad_source_type": {},
          "ad_source_url": {},
          "ad_headline": {},
          "whatsapp_link_id": {},
          "whatsapp_link_name": {},
          "at": {}
        },
        "latest_paid": {
          "landing_page": {},
          "referrer_host": {},
          "utm_source": {},
          "utm_medium": {},
          "utm_campaign": {},
          "utm_term": {},
          "utm_content": {},
          "gclid": {},
          "gbraid": {},
          "wbraid": {},
          "fbclid": {},
          "msclkid": {},
          "oppref": {},
          "ctwa_clid": {},
          "ad_id": {},
          "ad_source_type": {},
          "ad_source_url": {},
          "ad_headline": {},
          "whatsapp_link_id": {},
          "whatsapp_link_name": {},
          "at": {}
        }
      },
      "created_at": "2026-10-28T09:30:00.000Z",
      "updated_at": "2026-10-28T09:30:00.000Z",
      "capture_method": "tool",
      "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "phone_e164": "+14155550123",
      "phone_source": "given",
      "first_contacted_at": "2026-10-28T09:30:00.000Z",
      "last_contacted_at": "2026-10-28T09:30:00.000Z",
      "next_follow_up_at": "2026-10-28T09:30:00.000Z",
      "time_to_first_contact_seconds": 1,
      "uncontacted_nudged_at": "2026-10-28T09:30:00.000Z",
      "merged_into_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNi0xMC0yOCJ9",
  "has_more": true
}

Add a lead by hand

POST/api/leads

Requires a member. Saves a lead someone typed in, optionally linked to a call or conversation in the selected project. Capture method is manual. Linked leads retain their assistant, mode and test rules; unlinked leads have no assistant and default to source other. It needs an email or phone. Missing or foreign origins are 404; an origin already linked to a lead is 409 already_has_lead. It sends no lead.captured webhook or owner email. The change is audited.

Secret API key, not a viewer key. How it works

Request body

  • project_idstring

    The project the lead belongs to. Required with an org-wide key; a project key uses its own.

  • call_idstringnot empty

    Save an unknown caller as a lead. Must belong to this org and project; 404 otherwise, 409 already_has_lead if already linked. Mutually exclusive with conversation_id. Origin mode and test rules are retained.

  • conversation_idstringnot empty

    Save a conversation as a lead, with the same scope and duplicate checks as call_id. Mutually exclusive with call_id.

  • namestringup to 200 characters

  • emailstringemailup to 320 characters

  • phonestringup to 64 characters

    As given; include the country code for phone_e164.

  • fieldsobject

    Any other details, keyed by field key.

  • sourcestring

    Defaults to the linked origin channel, or other when unlinked. These are capture channels; search acquisition is not a recorded source value.

    One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

  • testboolean

    Mark it as test (or not) by hand; absent follows the automatic rules.

Returns

201 Created

Response attributes
  • dataLeadDetailrequired

    48 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • assistant_idstring | null

      The assistant that captured the lead; null when no assistant did (a form lead, or one added by hand).

    • conversation_idstring | null

    • namestring | null

    • emailstring | nullemail

    • phonestring | null

    • fact_provenanceobject

      Provenance per field key, including name, email and phone. Legacy values use lead creation time with captured_at_estimated true; edits retain captured_at and set edited_at and edited_by.

      9 attributes
      • sourcestringrequired

        One of conversation channel form manual

      • channelstringrequired

        One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

      • conversation_idstring | nullrequired

      • call_idstring | nullrequired

      • form_submission_idstring | nullrequired

      • captured_atstringrequiredISO 8601 timestamp

      • captured_at_estimatedbooleanrequired

      • edited_atstring | nullrequiredISO 8601 timestamp

      • edited_bystring | nullrequired

    • fieldsobject | null

    • sourcestringrequired

      Where the lead came from: web_chat, web_call (a call from a browser), phone_call, sms, whatsapp, form, ad_form (an ad platform's own lead form, such as a Google lead form), scheduling (a booking) or other (such as a lead added by hand).

      One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

    • modestring

      Capture provenance: the chat mode, independent of email classification.

      One of live test preview

    • testboolean

      Effective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See traffic to tell them apart.

    • trafficstring

      Which traffic this belongs to: sandbox (made through a non-live key: a sandbox key, the console's sandbox chat, a sandbox phone or WhatsApp number, or a preview link), test (a live chat or lead one of our rules caught: a test marker, a staging or preview page, a placeholder or own-domain email, or marked as test by hand) or real. Sandbox wins over test. Sandbox and test are both left out of real numbers.

      One of real sandbox test

    • test_reasonstring | null

      Automatic classification, recomputed when saved: reserved_domain (placeholder email), business_domain (your own email domain) or staging_site (a live chat on a staging or preview page). An email reason wins over staging_site.

      One of reserved_domain business_domain staging_site

    • test_overrideboolean | null

      Member override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox.

    • outcomestring | null

      What became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).

      One of open booked lost

    • outcome_valuestring | null

      Booking value as a decimal string.

    • outcome_currencystring | null

    • outcome_atstring | nullISO 8601 timestamp

    • outcome_refstring | null

      The CRM's own id for the booking.

    • customer_idstring | null

      The customer's own id for this person, set with PUT /v1/leads/{id}/outcome.

    • statusstring

      The front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts new. new, contacted and qualified are open; won and lost close it. Separate from outcome, which your CRM reports.

      One of new contacted qualified won lost

    • status_changed_atstring | nullISO 8601 timestamp

    • status_changed_bystring | null

      A user id, or the agent.id an API key named.

    • status_changed_by_namestring | null

    • attributionChatAttribution | null

      Where the lead's chat came from. Returned by the list and detail reads; null when none was recorded.

      One of 2 shapes

      ChatAttribution

      • chat_pagestring

        The path the visitor started chatting on.

      • visitChatAttributionTouch

        This visit's landing.

        20 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

      • firstobject

        The visitor's first-ever landing.

        21 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

        • atstringISO 8601 timestamp

          When the visitor first landed.

      • latest_paidobject

        The visitor's latest ad click within 90 days: a landing with a click id, or with utm_medium cpc, ppc or paid*. Recorded even when the click came inside a visit that began elsewhere, and kept through later direct visits, so it can differ from visit and first.

        21 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

        • atstringISO 8601 timestamp

          When the visitor landed from this ad click.

      Option 2

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • capture_methodstring

      How the lead was first saved: tool (the assistant saved it during the conversation), analysis (read from the conversation afterwards), form (a form submission) manual (added by hand) or scheduling (a direct booking). Later updates never change it.

      One of tool analysis form manual scheduling

    • call_idstring | null

      The call the lead came from, when it came from one.

    • form_submission_idstring | null

      The form submission the lead came from, when it came from one.

    • phone_e164string | null

      phone in E.164 form when it could be read as a number; phone stays as given.

    • phone_sourcestring | null

      caller_id when a call lead's phone is the number the call came from, because the caller never said one. Null means the person gave it.

      One of given caller_id

    • first_contacted_atstring | nullISO 8601 timestamp

      The first contact: the earliest logged contact, or the first status change out of new by a person or key. Null until contacted.

    • last_contacted_atstring | nullISO 8601 timestamp

      The latest contact.

    • next_follow_up_atstring | nullISO 8601 timestamp

      When to contact the lead again. Cleared when the lead is won or lost.

    • time_to_first_contact_secondsinteger | null

      Wall clock from created_at to first_contacted_at, in seconds. Null until contacted.

    • uncontacted_nudged_atstring | nullISO 8601 timestamp

      When lead.uncontacted was recorded for the lead; null when it never was.

    • merged_into_idstring | null

      The kept lead's id when this lead was merged. Merged leads remain readable by id.

    • possible_repeat_ofarray of string

      Detail read only. For a call lead whose caller's number matched earlier open enquiries but who did not say whether this call was about one of them: those leads' ids. Empty otherwise. This historical hint does not perform a merge.

    • possible_duplicatesarray of objectup to 5 items

      Other unmerged leads in this org and project matching a non-null phone_e164, a non-blank trimmed case-insensitive email, or possible_repeat_of. Dismissals on either side are excluded. Newest first, unique by id; phone wins over email, then repeat_caller. Empty when this lead is merged.

      7 attributes
      • idstringrequired

      • namestring | nullrequired

      • emailstring | nullrequired

      • phonestring | nullrequired

      • sourcestringrequired

        One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

      • created_atstringrequiredISO 8601 timestamp

      • reasonstringrequired

        One of phone email repeat_caller

    • merged_fromarray of object

      Leads merged into this lead, oldest first. Origin links stay on these rows, including all earlier merges.

      7 attributes
      • idstringrequired

      • namestring | nullrequired

      • sourcestringrequired

        One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

      • conversation_idstring | nullrequired

      • call_idstring | nullrequired

      • form_submission_idstring | nullrequired

      • created_atstringrequiredISO 8601 timestamp

    • status_historyarray of object

      Every status change, oldest first.

      5 attributes
      • fromstringrequired

        One of new contacted qualified won lost

      • tostringrequired

        One of new contacted qualified won lost

      • atstringrequiredISO 8601 timestamp

      • bystringrequired

      • by_namestring | nullrequired

    • contactsarray of LeadContact

      Detail read only. Live logged contacts, newest first; voided ones are left out.

      8 attributes
      • idstringrequired

        lcon_....

      • channelstringrequired

        One of phone whatsapp email sms in_person other

      • viastringrequired

        A console contact button, Log contact, or the API.

        One of button manual api

      • contacted_atstringrequiredISO 8601 timestamp

      • bystringrequired

        A user id, or the agent.id an API key named.

      • by_namestring | nullrequired

      • status_movedbooleanrequired

        Whether this contact moved the lead from new to contacted.

      • logged_atstringrequiredISO 8601 timestamp

        When the contact was logged: the time of the status change it made. Undo is open for a day after.

    • form_originobject | null

      Detail read only. The form a form or ad_form lead came from; null for other leads. ad holds the ad platform's ids for an ad_form lead (attribution.ad_form in lead.captured), null for a website form.

      4 attributes
      • form_idstring

      • form_namestring

      • channelstring

        One of website google_lead_form

      • adobject | null

    • bookingsarray of object

      Scheduling facts for this lead and mode, up to 200 bookings, oldest first. CRM outcome is unchanged.

      9 attributes
      • idstringrequired

      • uidstringrequired

      • event_namestringrequired

      • statusstringrequired

        One of pending processing confirmed completed rejected expired cancelled rescheduled

      • modestringrequired

        One of live test

      • start_atstringrequiredISO 8601 timestamp

      • end_atstringrequiredISO 8601 timestamp

      • timezonestringrequired

      • rescheduled_to_idstring | nullrequired

    • callbackobject | null

      The callback the visitor asked for in the lead's chat, as on the conversation. Detail read only.

      7 attributes
      • phonestring

      • slot_startstringISO 8601 timestamp

      • notestring

      • requested_atstringISO 8601 timestamp

      • done_atstringISO 8601 timestamp

      • done_bystring

      • done_by_namestring

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 409 Conflict
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
POST /api/leads
curl -X POST "https://api.brightshoal.com/api/leads" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d 'null'
Response 201
{
  "data": {
    "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "email": "ana@example.com",
    "phone": "+14155550123",
    "fact_provenance": {
      "key": {
        "source": "conversation",
        "channel": "web_chat",
        "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "captured_at": "2026-10-28T09:30:00.000Z",
        "captured_at_estimated": true,
        "edited_at": "2026-10-28T09:30:00.000Z",
        "edited_by": "string"
      }
    },
    "fields": {
      "key": "string"
    },
    "source": "web_chat",
    "mode": "live",
    "test": true,
    "traffic": "real",
    "test_reason": "reserved_domain",
    "test_override": true,
    "outcome": "open",
    "outcome_value": "string",
    "outcome_currency": "string",
    "outcome_at": "2026-10-28T09:30:00.000Z",
    "outcome_ref": "string",
    "customer_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "status": "new",
    "status_changed_at": "2026-10-28T09:30:00.000Z",
    "status_changed_by": "string",
    "status_changed_by_name": "string",
    "attribution": {
      "chat_page": "string",
      "visit": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "oppref": "string",
        "ctwa_clid": "string",
        "ad_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "ad_source_type": "string",
        "ad_source_url": "https://example.com/hook",
        "ad_headline": "string",
        "whatsapp_link_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "whatsapp_link_name": "string"
      },
      "first": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "oppref": "string",
        "ctwa_clid": "string",
        "ad_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "ad_source_type": "string",
        "ad_source_url": "https://example.com/hook",
        "ad_headline": "string",
        "whatsapp_link_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "whatsapp_link_name": "string",
        "at": "2026-10-28T09:30:00.000Z"
      },
      "latest_paid": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "oppref": "string",
        "ctwa_clid": "string",
        "ad_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "ad_source_type": "string",
        "ad_source_url": "https://example.com/hook",
        "ad_headline": "string",
        "whatsapp_link_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "whatsapp_link_name": "string",
        "at": "2026-10-28T09:30:00.000Z"
      }
    },
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z",
    "capture_method": "tool",
    "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "phone_e164": "+14155550123",
    "phone_source": "given",
    "first_contacted_at": "2026-10-28T09:30:00.000Z",
    "last_contacted_at": "2026-10-28T09:30:00.000Z",
    "next_follow_up_at": "2026-10-28T09:30:00.000Z",
    "time_to_first_contact_seconds": 1,
    "uncontacted_nudged_at": "2026-10-28T09:30:00.000Z",
    "merged_into_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "possible_repeat_of": [
      "string"
    ],
    "possible_duplicates": [
      {
        "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "name": "Front desk",
        "email": "ana@example.com",
        "phone": "+14155550123",
        "source": "web_chat",
        "created_at": "2026-10-28T09:30:00.000Z",
        "reason": "phone"
      }
    ],
    "merged_from": [
      {
        "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "name": "Front desk",
        "source": "web_chat",
        "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "created_at": "2026-10-28T09:30:00.000Z"
      }
    ],
    "status_history": [
      {
        "from": "new",
        "to": "new",
        "at": "2026-10-28T09:30:00.000Z",
        "by": "string",
        "by_name": "string"
      }
    ],
    "contacts": [
      {
        "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "channel": "phone",
        "via": "button",
        "contacted_at": "2026-10-28T09:30:00.000Z",
        "by": "string",
        "by_name": "string",
        "status_moved": true,
        "logged_at": "2026-10-28T09:30:00.000Z"
      }
    ],
    "form_origin": {
      "form_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "form_name": "string",
      "channel": "website",
      "ad": {}
    },
    "bookings": [
      {
        "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "uid": "string",
        "event_name": "string",
        "status": "pending",
        "mode": "live",
        "start_at": "2026-10-28T09:30:00.000Z",
        "end_at": "2026-10-28T09:30:00.000Z",
        "timezone": "string",
        "rescheduled_to_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
      }
    ],
    "callback": {
      "phone": "+14155550123",
      "slot_start": "2026-10-28T09:30:00.000Z",
      "note": "string",
      "requested_at": "2026-10-28T09:30:00.000Z",
      "done_at": "2026-10-28T09:30:00.000Z",
      "done_by": "string",
      "done_by_name": "string"
    }
  }
}

Get a lead

GET/api/leads/{id}

One lead with the details the assistant captured, the conversation it came from, any outcome you reported, its status history and the chat's callback request.

Secret API key. How it works

Path parameters

  • idstringrequired

    Lead id, lead_....

Returns

200 OK

Response attributes
  • dataLeadDetailrequired

    48 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • assistant_idstring | null

      The assistant that captured the lead; null when no assistant did (a form lead, or one added by hand).

    • conversation_idstring | null

    • namestring | null

    • emailstring | nullemail

    • phonestring | null

    • fact_provenanceobject

      Provenance per field key, including name, email and phone. Legacy values use lead creation time with captured_at_estimated true; edits retain captured_at and set edited_at and edited_by.

      9 attributes
      • sourcestringrequired

        One of conversation channel form manual

      • channelstringrequired

        One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

      • conversation_idstring | nullrequired

      • call_idstring | nullrequired

      • form_submission_idstring | nullrequired

      • captured_atstringrequiredISO 8601 timestamp

      • captured_at_estimatedbooleanrequired

      • edited_atstring | nullrequiredISO 8601 timestamp

      • edited_bystring | nullrequired

    • fieldsobject | null

    • sourcestringrequired

      Where the lead came from: web_chat, web_call (a call from a browser), phone_call, sms, whatsapp, form, ad_form (an ad platform's own lead form, such as a Google lead form), scheduling (a booking) or other (such as a lead added by hand).

      One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

    • modestring

      Capture provenance: the chat mode, independent of email classification.

      One of live test preview

    • testboolean

      Effective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See traffic to tell them apart.

    • trafficstring

      Which traffic this belongs to: sandbox (made through a non-live key: a sandbox key, the console's sandbox chat, a sandbox phone or WhatsApp number, or a preview link), test (a live chat or lead one of our rules caught: a test marker, a staging or preview page, a placeholder or own-domain email, or marked as test by hand) or real. Sandbox wins over test. Sandbox and test are both left out of real numbers.

      One of real sandbox test

    • test_reasonstring | null

      Automatic classification, recomputed when saved: reserved_domain (placeholder email), business_domain (your own email domain) or staging_site (a live chat on a staging or preview page). An email reason wins over staging_site.

      One of reserved_domain business_domain staging_site

    • test_overrideboolean | null

      Member override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox.

    • outcomestring | null

      What became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).

      One of open booked lost

    • outcome_valuestring | null

      Booking value as a decimal string.

    • outcome_currencystring | null

    • outcome_atstring | nullISO 8601 timestamp

    • outcome_refstring | null

      The CRM's own id for the booking.

    • customer_idstring | null

      The customer's own id for this person, set with PUT /v1/leads/{id}/outcome.

    • statusstring

      The front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts new. new, contacted and qualified are open; won and lost close it. Separate from outcome, which your CRM reports.

      One of new contacted qualified won lost

    • status_changed_atstring | nullISO 8601 timestamp

    • status_changed_bystring | null

      A user id, or the agent.id an API key named.

    • status_changed_by_namestring | null

    • attributionChatAttribution | null

      Where the lead's chat came from. Returned by the list and detail reads; null when none was recorded.

      One of 2 shapes

      ChatAttribution

      • chat_pagestring

        The path the visitor started chatting on.

      • visitChatAttributionTouch

        This visit's landing.

        20 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

      • firstobject

        The visitor's first-ever landing.

        21 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

        • atstringISO 8601 timestamp

          When the visitor first landed.

      • latest_paidobject

        The visitor's latest ad click within 90 days: a landing with a click id, or with utm_medium cpc, ppc or paid*. Recorded even when the click came inside a visit that began elsewhere, and kept through later direct visits, so it can differ from visit and first.

        21 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

        • atstringISO 8601 timestamp

          When the visitor landed from this ad click.

      Option 2

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • capture_methodstring

      How the lead was first saved: tool (the assistant saved it during the conversation), analysis (read from the conversation afterwards), form (a form submission) manual (added by hand) or scheduling (a direct booking). Later updates never change it.

      One of tool analysis form manual scheduling

    • call_idstring | null

      The call the lead came from, when it came from one.

    • form_submission_idstring | null

      The form submission the lead came from, when it came from one.

    • phone_e164string | null

      phone in E.164 form when it could be read as a number; phone stays as given.

    • phone_sourcestring | null

      caller_id when a call lead's phone is the number the call came from, because the caller never said one. Null means the person gave it.

      One of given caller_id

    • first_contacted_atstring | nullISO 8601 timestamp

      The first contact: the earliest logged contact, or the first status change out of new by a person or key. Null until contacted.

    • last_contacted_atstring | nullISO 8601 timestamp

      The latest contact.

    • next_follow_up_atstring | nullISO 8601 timestamp

      When to contact the lead again. Cleared when the lead is won or lost.

    • time_to_first_contact_secondsinteger | null

      Wall clock from created_at to first_contacted_at, in seconds. Null until contacted.

    • uncontacted_nudged_atstring | nullISO 8601 timestamp

      When lead.uncontacted was recorded for the lead; null when it never was.

    • merged_into_idstring | null

      The kept lead's id when this lead was merged. Merged leads remain readable by id.

    • possible_repeat_ofarray of string

      Detail read only. For a call lead whose caller's number matched earlier open enquiries but who did not say whether this call was about one of them: those leads' ids. Empty otherwise. This historical hint does not perform a merge.

    • possible_duplicatesarray of objectup to 5 items

      Other unmerged leads in this org and project matching a non-null phone_e164, a non-blank trimmed case-insensitive email, or possible_repeat_of. Dismissals on either side are excluded. Newest first, unique by id; phone wins over email, then repeat_caller. Empty when this lead is merged.

      7 attributes
      • idstringrequired

      • namestring | nullrequired

      • emailstring | nullrequired

      • phonestring | nullrequired

      • sourcestringrequired

        One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

      • created_atstringrequiredISO 8601 timestamp

      • reasonstringrequired

        One of phone email repeat_caller

    • merged_fromarray of object

      Leads merged into this lead, oldest first. Origin links stay on these rows, including all earlier merges.

      7 attributes
      • idstringrequired

      • namestring | nullrequired

      • sourcestringrequired

        One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

      • conversation_idstring | nullrequired

      • call_idstring | nullrequired

      • form_submission_idstring | nullrequired

      • created_atstringrequiredISO 8601 timestamp

    • status_historyarray of object

      Every status change, oldest first.

      5 attributes
      • fromstringrequired

        One of new contacted qualified won lost

      • tostringrequired

        One of new contacted qualified won lost

      • atstringrequiredISO 8601 timestamp

      • bystringrequired

      • by_namestring | nullrequired

    • contactsarray of LeadContact

      Detail read only. Live logged contacts, newest first; voided ones are left out.

      8 attributes
      • idstringrequired

        lcon_....

      • channelstringrequired

        One of phone whatsapp email sms in_person other

      • viastringrequired

        A console contact button, Log contact, or the API.

        One of button manual api

      • contacted_atstringrequiredISO 8601 timestamp

      • bystringrequired

        A user id, or the agent.id an API key named.

      • by_namestring | nullrequired

      • status_movedbooleanrequired

        Whether this contact moved the lead from new to contacted.

      • logged_atstringrequiredISO 8601 timestamp

        When the contact was logged: the time of the status change it made. Undo is open for a day after.

    • form_originobject | null

      Detail read only. The form a form or ad_form lead came from; null for other leads. ad holds the ad platform's ids for an ad_form lead (attribution.ad_form in lead.captured), null for a website form.

      4 attributes
      • form_idstring

      • form_namestring

      • channelstring

        One of website google_lead_form

      • adobject | null

    • bookingsarray of object

      Scheduling facts for this lead and mode, up to 200 bookings, oldest first. CRM outcome is unchanged.

      9 attributes
      • idstringrequired

      • uidstringrequired

      • event_namestringrequired

      • statusstringrequired

        One of pending processing confirmed completed rejected expired cancelled rescheduled

      • modestringrequired

        One of live test

      • start_atstringrequiredISO 8601 timestamp

      • end_atstringrequiredISO 8601 timestamp

      • timezonestringrequired

      • rescheduled_to_idstring | nullrequired

    • callbackobject | null

      The callback the visitor asked for in the lead's chat, as on the conversation. Detail read only.

      7 attributes
      • phonestring

      • slot_startstringISO 8601 timestamp

      • notestring

      • requested_atstringISO 8601 timestamp

      • done_atstringISO 8601 timestamp

      • done_bystring

      • done_by_namestring

  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 404 Not found, or outside what the key can see
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
GET /api/leads/{id}
curl "https://api.brightshoal.com/api/leads/LEAD_ID" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "email": "ana@example.com",
    "phone": "+14155550123",
    "fact_provenance": {
      "key": {
        "source": "conversation",
        "channel": "web_chat",
        "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "captured_at": "2026-10-28T09:30:00.000Z",
        "captured_at_estimated": true,
        "edited_at": "2026-10-28T09:30:00.000Z",
        "edited_by": "string"
      }
    },
    "fields": {
      "key": "string"
    },
    "source": "web_chat",
    "mode": "live",
    "test": true,
    "traffic": "real",
    "test_reason": "reserved_domain",
    "test_override": true,
    "outcome": "open",
    "outcome_value": "string",
    "outcome_currency": "string",
    "outcome_at": "2026-10-28T09:30:00.000Z",
    "outcome_ref": "string",
    "customer_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "status": "new",
    "status_changed_at": "2026-10-28T09:30:00.000Z",
    "status_changed_by": "string",
    "status_changed_by_name": "string",
    "attribution": {
      "chat_page": "string",
      "visit": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "oppref": "string",
        "ctwa_clid": "string",
        "ad_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "ad_source_type": "string",
        "ad_source_url": "https://example.com/hook",
        "ad_headline": "string",
        "whatsapp_link_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "whatsapp_link_name": "string"
      },
      "first": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "oppref": "string",
        "ctwa_clid": "string",
        "ad_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "ad_source_type": "string",
        "ad_source_url": "https://example.com/hook",
        "ad_headline": "string",
        "whatsapp_link_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "whatsapp_link_name": "string",
        "at": "2026-10-28T09:30:00.000Z"
      },
      "latest_paid": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "oppref": "string",
        "ctwa_clid": "string",
        "ad_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "ad_source_type": "string",
        "ad_source_url": "https://example.com/hook",
        "ad_headline": "string",
        "whatsapp_link_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "whatsapp_link_name": "string",
        "at": "2026-10-28T09:30:00.000Z"
      }
    },
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z",
    "capture_method": "tool",
    "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "phone_e164": "+14155550123",
    "phone_source": "given",
    "first_contacted_at": "2026-10-28T09:30:00.000Z",
    "last_contacted_at": "2026-10-28T09:30:00.000Z",
    "next_follow_up_at": "2026-10-28T09:30:00.000Z",
    "time_to_first_contact_seconds": 1,
    "uncontacted_nudged_at": "2026-10-28T09:30:00.000Z",
    "merged_into_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "possible_repeat_of": [
      "string"
    ],
    "possible_duplicates": [
      {
        "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "name": "Front desk",
        "email": "ana@example.com",
        "phone": "+14155550123",
        "source": "web_chat",
        "created_at": "2026-10-28T09:30:00.000Z",
        "reason": "phone"
      }
    ],
    "merged_from": [
      {
        "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "name": "Front desk",
        "source": "web_chat",
        "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "created_at": "2026-10-28T09:30:00.000Z"
      }
    ],
    "status_history": [
      {
        "from": "new",
        "to": "new",
        "at": "2026-10-28T09:30:00.000Z",
        "by": "string",
        "by_name": "string"
      }
    ],
    "contacts": [
      {
        "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "channel": "phone",
        "via": "button",
        "contacted_at": "2026-10-28T09:30:00.000Z",
        "by": "string",
        "by_name": "string",
        "status_moved": true,
        "logged_at": "2026-10-28T09:30:00.000Z"
      }
    ],
    "form_origin": {
      "form_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "form_name": "string",
      "channel": "website",
      "ad": {}
    },
    "bookings": [
      {
        "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "uid": "string",
        "event_name": "string",
        "status": "pending",
        "mode": "live",
        "start_at": "2026-10-28T09:30:00.000Z",
        "end_at": "2026-10-28T09:30:00.000Z",
        "timezone": "string",
        "rescheduled_to_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
      }
    ],
    "callback": {
      "phone": "+14155550123",
      "slot_start": "2026-10-28T09:30:00.000Z",
      "note": "string",
      "requested_at": "2026-10-28T09:30:00.000Z",
      "done_at": "2026-10-28T09:30:00.000Z",
      "done_by": "string",
      "done_by_name": "string"
    }
  }
}

Set a lead's test override

PATCH/api/leads/{id}

Requires a member. Set test to true or false, or null to use automatic classification. Capture mode stays unchanged. The change is audited.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

    Lead id, lead_....

Request body

  • testboolean | nullrequired

Returns

200 OK

Response attributes
  • dataLeadrequired

    40 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • assistant_idstring | null

      The assistant that captured the lead; null when no assistant did (a form lead, or one added by hand).

    • conversation_idstring | null

    • namestring | null

    • emailstring | nullemail

    • phonestring | null

    • fact_provenanceobject

      Provenance per field key, including name, email and phone. Legacy values use lead creation time with captured_at_estimated true; edits retain captured_at and set edited_at and edited_by.

      9 attributes
      • sourcestringrequired

        One of conversation channel form manual

      • channelstringrequired

        One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

      • conversation_idstring | nullrequired

      • call_idstring | nullrequired

      • form_submission_idstring | nullrequired

      • captured_atstringrequiredISO 8601 timestamp

      • captured_at_estimatedbooleanrequired

      • edited_atstring | nullrequiredISO 8601 timestamp

      • edited_bystring | nullrequired

    • fieldsobject | null

    • sourcestringrequired

      Where the lead came from: web_chat, web_call (a call from a browser), phone_call, sms, whatsapp, form, ad_form (an ad platform's own lead form, such as a Google lead form), scheduling (a booking) or other (such as a lead added by hand).

      One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

    • modestring

      Capture provenance: the chat mode, independent of email classification.

      One of live test preview

    • testboolean

      Effective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See traffic to tell them apart.

    • trafficstring

      Which traffic this belongs to: sandbox (made through a non-live key: a sandbox key, the console's sandbox chat, a sandbox phone or WhatsApp number, or a preview link), test (a live chat or lead one of our rules caught: a test marker, a staging or preview page, a placeholder or own-domain email, or marked as test by hand) or real. Sandbox wins over test. Sandbox and test are both left out of real numbers.

      One of real sandbox test

    • test_reasonstring | null

      Automatic classification, recomputed when saved: reserved_domain (placeholder email), business_domain (your own email domain) or staging_site (a live chat on a staging or preview page). An email reason wins over staging_site.

      One of reserved_domain business_domain staging_site

    • test_overrideboolean | null

      Member override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox.

    • outcomestring | null

      What became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).

      One of open booked lost

    • outcome_valuestring | null

      Booking value as a decimal string.

    • outcome_currencystring | null

    • outcome_atstring | nullISO 8601 timestamp

    • outcome_refstring | null

      The CRM's own id for the booking.

    • customer_idstring | null

      The customer's own id for this person, set with PUT /v1/leads/{id}/outcome.

    • statusstring

      The front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts new. new, contacted and qualified are open; won and lost close it. Separate from outcome, which your CRM reports.

      One of new contacted qualified won lost

    • status_changed_atstring | nullISO 8601 timestamp

    • status_changed_bystring | null

      A user id, or the agent.id an API key named.

    • status_changed_by_namestring | null

    • attributionChatAttribution | null

      Where the lead's chat came from. Returned by the list and detail reads; null when none was recorded.

      One of 2 shapes

      ChatAttribution

      • chat_pagestring

        The path the visitor started chatting on.

      • visitChatAttributionTouch

        This visit's landing.

        20 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

      • firstobject

        The visitor's first-ever landing.

        21 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

        • atstringISO 8601 timestamp

          When the visitor first landed.

      • latest_paidobject

        The visitor's latest ad click within 90 days: a landing with a click id, or with utm_medium cpc, ppc or paid*. Recorded even when the click came inside a visit that began elsewhere, and kept through later direct visits, so it can differ from visit and first.

        21 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

        • atstringISO 8601 timestamp

          When the visitor landed from this ad click.

      Option 2

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • capture_methodstring

      How the lead was first saved: tool (the assistant saved it during the conversation), analysis (read from the conversation afterwards), form (a form submission) manual (added by hand) or scheduling (a direct booking). Later updates never change it.

      One of tool analysis form manual scheduling

    • call_idstring | null

      The call the lead came from, when it came from one.

    • form_submission_idstring | null

      The form submission the lead came from, when it came from one.

    • phone_e164string | null

      phone in E.164 form when it could be read as a number; phone stays as given.

    • phone_sourcestring | null

      caller_id when a call lead's phone is the number the call came from, because the caller never said one. Null means the person gave it.

      One of given caller_id

    • first_contacted_atstring | nullISO 8601 timestamp

      The first contact: the earliest logged contact, or the first status change out of new by a person or key. Null until contacted.

    • last_contacted_atstring | nullISO 8601 timestamp

      The latest contact.

    • next_follow_up_atstring | nullISO 8601 timestamp

      When to contact the lead again. Cleared when the lead is won or lost.

    • time_to_first_contact_secondsinteger | null

      Wall clock from created_at to first_contacted_at, in seconds. Null until contacted.

    • uncontacted_nudged_atstring | nullISO 8601 timestamp

      When lead.uncontacted was recorded for the lead; null when it never was.

    • merged_into_idstring | null

      The kept lead's id when this lead was merged. Merged leads remain readable by id.

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Member role required.
  • 404 Not found, or outside what the key can see
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
PATCH /api/leads/{id}
curl -X PATCH "https://api.brightshoal.com/api/leads/LEAD_ID" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "test": true
}'
Response 200
{
  "data": {
    "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "email": "ana@example.com",
    "phone": "+14155550123",
    "fact_provenance": {
      "key": {
        "source": "conversation",
        "channel": "web_chat",
        "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "captured_at": "2026-10-28T09:30:00.000Z",
        "captured_at_estimated": true,
        "edited_at": "2026-10-28T09:30:00.000Z",
        "edited_by": "string"
      }
    },
    "fields": {
      "key": "string"
    },
    "source": "web_chat",
    "mode": "live",
    "test": true,
    "traffic": "real",
    "test_reason": "reserved_domain",
    "test_override": true,
    "outcome": "open",
    "outcome_value": "string",
    "outcome_currency": "string",
    "outcome_at": "2026-10-28T09:30:00.000Z",
    "outcome_ref": "string",
    "customer_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "status": "new",
    "status_changed_at": "2026-10-28T09:30:00.000Z",
    "status_changed_by": "string",
    "status_changed_by_name": "string",
    "attribution": {
      "chat_page": "string",
      "visit": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "oppref": "string",
        "ctwa_clid": "string",
        "ad_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "ad_source_type": "string",
        "ad_source_url": "https://example.com/hook",
        "ad_headline": "string",
        "whatsapp_link_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "whatsapp_link_name": "string"
      },
      "first": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "oppref": "string",
        "ctwa_clid": "string",
        "ad_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "ad_source_type": "string",
        "ad_source_url": "https://example.com/hook",
        "ad_headline": "string",
        "whatsapp_link_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "whatsapp_link_name": "string",
        "at": "2026-10-28T09:30:00.000Z"
      },
      "latest_paid": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "oppref": "string",
        "ctwa_clid": "string",
        "ad_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "ad_source_type": "string",
        "ad_source_url": "https://example.com/hook",
        "ad_headline": "string",
        "whatsapp_link_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "whatsapp_link_name": "string",
        "at": "2026-10-28T09:30:00.000Z"
      }
    },
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z",
    "capture_method": "tool",
    "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "phone_e164": "+14155550123",
    "phone_source": "given",
    "first_contacted_at": "2026-10-28T09:30:00.000Z",
    "last_contacted_at": "2026-10-28T09:30:00.000Z",
    "next_follow_up_at": "2026-10-28T09:30:00.000Z",
    "time_to_first_contact_seconds": 1,
    "uncontacted_nudged_at": "2026-10-28T09:30:00.000Z",
    "merged_into_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}

Log a contact

POST/api/leads/{id}/contacts

Requires a member. Records that someone reached the lead. A new lead moves to contacted (a status change, with lead.status_changed); a won or lost lead takes the contact without a status change. Sets first_contacted_at and last_contacted_at, and next_follow_up_at when given. With an API key the contact is via: api; name the person in agent. Audited, without contact details.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

    Lead id, lead_....

Request body

  • channelstringrequired

    One of phone whatsapp email sms in_person other

  • viastring

    The console's: a contact button or Log contact. Always api for an API key.

    One of button manual

  • contacted_atstringISO 8601 timestamp

    When it happened. Default now; not in the future, not before the lead, at most 30 days back.

  • next_follow_up_atstring | nullISO 8601 timestamp

    When to contact again: within a year, not more than 5 minutes past. Null clears it; absent leaves it. A date on a won or lost lead is 409 lead_closed.

  • agentstring | AgentIdentityInput

    With an API key: who made the contact, as PUT /status takes it, or just a name.

    One of 2 shapes

    Option 1

    AgentIdentityInput

    • idstring

    • emailstringemail

    • namestring

Returns

201 Logged

Response attributes
  • dataobjectrequired

    2 attributes
    • contactLeadContactrequired

      8 attributes
      • idstringrequired

        lcon_....

      • channelstringrequired

        One of phone whatsapp email sms in_person other

      • viastringrequired

        A console contact button, Log contact, or the API.

        One of button manual api

      • contacted_atstringrequiredISO 8601 timestamp

      • bystringrequired

        A user id, or the agent.id an API key named.

      • by_namestring | nullrequired

      • status_movedbooleanrequired

        Whether this contact moved the lead from new to contacted.

      • logged_atstringrequiredISO 8601 timestamp

        When the contact was logged: the time of the status change it made. Undo is open for a day after.

    • leadLeadDetailrequired

      48 attributes
      • idstringrequired

      • org_idstringrequired

      • project_idstringrequired

      • assistant_idstring | null

        The assistant that captured the lead; null when no assistant did (a form lead, or one added by hand).

      • conversation_idstring | null

      • namestring | null

      • emailstring | nullemail

      • phonestring | null

      • fact_provenanceobject

        Provenance per field key, including name, email and phone. Legacy values use lead creation time with captured_at_estimated true; edits retain captured_at and set edited_at and edited_by.

        9 attributes
        • sourcestringrequired

          One of conversation channel form manual

        • channelstringrequired

          One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

        • conversation_idstring | nullrequired

        • call_idstring | nullrequired

        • form_submission_idstring | nullrequired

        • captured_atstringrequiredISO 8601 timestamp

        • captured_at_estimatedbooleanrequired

        • edited_atstring | nullrequiredISO 8601 timestamp

        • edited_bystring | nullrequired

      • fieldsobject | null

      • sourcestringrequired

        Where the lead came from: web_chat, web_call (a call from a browser), phone_call, sms, whatsapp, form, ad_form (an ad platform's own lead form, such as a Google lead form), scheduling (a booking) or other (such as a lead added by hand).

        One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

      • modestring

        Capture provenance: the chat mode, independent of email classification.

        One of live test preview

      • testboolean

        Effective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See traffic to tell them apart.

      • trafficstring

        Which traffic this belongs to: sandbox (made through a non-live key: a sandbox key, the console's sandbox chat, a sandbox phone or WhatsApp number, or a preview link), test (a live chat or lead one of our rules caught: a test marker, a staging or preview page, a placeholder or own-domain email, or marked as test by hand) or real. Sandbox wins over test. Sandbox and test are both left out of real numbers.

        One of real sandbox test

      • test_reasonstring | null

        Automatic classification, recomputed when saved: reserved_domain (placeholder email), business_domain (your own email domain) or staging_site (a live chat on a staging or preview page). An email reason wins over staging_site.

        One of reserved_domain business_domain staging_site

      • test_overrideboolean | null

        Member override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox.

      • outcomestring | null

        What became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).

        One of open booked lost

      • outcome_valuestring | null

        Booking value as a decimal string.

      • outcome_currencystring | null

      • outcome_atstring | nullISO 8601 timestamp

      • outcome_refstring | null

        The CRM's own id for the booking.

      • customer_idstring | null

        The customer's own id for this person, set with PUT /v1/leads/{id}/outcome.

      • statusstring

        The front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts new. new, contacted and qualified are open; won and lost close it. Separate from outcome, which your CRM reports.

        One of new contacted qualified won lost

      • status_changed_atstring | nullISO 8601 timestamp

      • status_changed_bystring | null

        A user id, or the agent.id an API key named.

      • status_changed_by_namestring | null

      • attributionChatAttribution | null

        Where the lead's chat came from. Returned by the list and detail reads; null when none was recorded.

        One of 2 shapes

        ChatAttribution

        • chat_pagestring

          The path the visitor started chatting on.

        • visitChatAttributionTouch

          This visit's landing.

          20 attributes
          • landing_pagestring

            A path starting with /, without query or fragment.

          • referrer_hoststring

          • utm_sourcestring

          • utm_mediumstring

          • utm_campaignstring

          • utm_termstring

          • utm_contentstring

          • gclidstring

          • gbraidstring

          • wbraidstring

          • fbclidstring

          • msclkidstring

          • opprefstring

          • ctwa_clidstring

            WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

          • ad_idstring

            WhatsApp only: the ad or post id (source_id) from Meta's referral.

          • ad_source_typestring

            WhatsApp only: ad or post.

          • ad_source_urlstring

            WhatsApp only: the ad's URL, up to 512 characters.

          • ad_headlinestring

            WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

          • whatsapp_link_idstring

            WhatsApp only: the campaign link (wal_...) the chat started from.

          • whatsapp_link_namestring

            WhatsApp only: that campaign link's name.

        • firstobject

          The visitor's first-ever landing.

          21 attributes
          • landing_pagestring

            A path starting with /, without query or fragment.

          • referrer_hoststring

          • utm_sourcestring

          • utm_mediumstring

          • utm_campaignstring

          • utm_termstring

          • utm_contentstring

          • gclidstring

          • gbraidstring

          • wbraidstring

          • fbclidstring

          • msclkidstring

          • opprefstring

          • ctwa_clidstring

            WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

          • ad_idstring

            WhatsApp only: the ad or post id (source_id) from Meta's referral.

          • ad_source_typestring

            WhatsApp only: ad or post.

          • ad_source_urlstring

            WhatsApp only: the ad's URL, up to 512 characters.

          • ad_headlinestring

            WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

          • whatsapp_link_idstring

            WhatsApp only: the campaign link (wal_...) the chat started from.

          • whatsapp_link_namestring

            WhatsApp only: that campaign link's name.

          • atstringISO 8601 timestamp

            When the visitor first landed.

        • latest_paidobject

          The visitor's latest ad click within 90 days: a landing with a click id, or with utm_medium cpc, ppc or paid*. Recorded even when the click came inside a visit that began elsewhere, and kept through later direct visits, so it can differ from visit and first.

          21 attributes
          • landing_pagestring

            A path starting with /, without query or fragment.

          • referrer_hoststring

          • utm_sourcestring

          • utm_mediumstring

          • utm_campaignstring

          • utm_termstring

          • utm_contentstring

          • gclidstring

          • gbraidstring

          • wbraidstring

          • fbclidstring

          • msclkidstring

          • opprefstring

          • ctwa_clidstring

            WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

          • ad_idstring

            WhatsApp only: the ad or post id (source_id) from Meta's referral.

          • ad_source_typestring

            WhatsApp only: ad or post.

          • ad_source_urlstring

            WhatsApp only: the ad's URL, up to 512 characters.

          • ad_headlinestring

            WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

          • whatsapp_link_idstring

            WhatsApp only: the campaign link (wal_...) the chat started from.

          • whatsapp_link_namestring

            WhatsApp only: that campaign link's name.

          • atstringISO 8601 timestamp

            When the visitor landed from this ad click.

        Option 2

      • created_atstringISO 8601 timestamp

      • updated_atstringISO 8601 timestamp

      • capture_methodstring

        How the lead was first saved: tool (the assistant saved it during the conversation), analysis (read from the conversation afterwards), form (a form submission) manual (added by hand) or scheduling (a direct booking). Later updates never change it.

        One of tool analysis form manual scheduling

      • call_idstring | null

        The call the lead came from, when it came from one.

      • form_submission_idstring | null

        The form submission the lead came from, when it came from one.

      • phone_e164string | null

        phone in E.164 form when it could be read as a number; phone stays as given.

      • phone_sourcestring | null

        caller_id when a call lead's phone is the number the call came from, because the caller never said one. Null means the person gave it.

        One of given caller_id

      • first_contacted_atstring | nullISO 8601 timestamp

        The first contact: the earliest logged contact, or the first status change out of new by a person or key. Null until contacted.

      • last_contacted_atstring | nullISO 8601 timestamp

        The latest contact.

      • next_follow_up_atstring | nullISO 8601 timestamp

        When to contact the lead again. Cleared when the lead is won or lost.

      • time_to_first_contact_secondsinteger | null

        Wall clock from created_at to first_contacted_at, in seconds. Null until contacted.

      • uncontacted_nudged_atstring | nullISO 8601 timestamp

        When lead.uncontacted was recorded for the lead; null when it never was.

      • merged_into_idstring | null

        The kept lead's id when this lead was merged. Merged leads remain readable by id.

      • possible_repeat_ofarray of string

        Detail read only. For a call lead whose caller's number matched earlier open enquiries but who did not say whether this call was about one of them: those leads' ids. Empty otherwise. This historical hint does not perform a merge.

      • possible_duplicatesarray of objectup to 5 items

        Other unmerged leads in this org and project matching a non-null phone_e164, a non-blank trimmed case-insensitive email, or possible_repeat_of. Dismissals on either side are excluded. Newest first, unique by id; phone wins over email, then repeat_caller. Empty when this lead is merged.

        7 attributes
        • idstringrequired

        • namestring | nullrequired

        • emailstring | nullrequired

        • phonestring | nullrequired

        • sourcestringrequired

          One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

        • created_atstringrequiredISO 8601 timestamp

        • reasonstringrequired

          One of phone email repeat_caller

      • merged_fromarray of object

        Leads merged into this lead, oldest first. Origin links stay on these rows, including all earlier merges.

        7 attributes
        • idstringrequired

        • namestring | nullrequired

        • sourcestringrequired

          One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

        • conversation_idstring | nullrequired

        • call_idstring | nullrequired

        • form_submission_idstring | nullrequired

        • created_atstringrequiredISO 8601 timestamp

      • status_historyarray of object

        Every status change, oldest first.

        5 attributes
        • fromstringrequired

          One of new contacted qualified won lost

        • tostringrequired

          One of new contacted qualified won lost

        • atstringrequiredISO 8601 timestamp

        • bystringrequired

        • by_namestring | nullrequired

      • contactsarray of LeadContact

        Detail read only. Live logged contacts, newest first; voided ones are left out.

        8 attributes
        • idstringrequired

          lcon_....

        • channelstringrequired

          One of phone whatsapp email sms in_person other

        • viastringrequired

          A console contact button, Log contact, or the API.

          One of button manual api

        • contacted_atstringrequiredISO 8601 timestamp

        • bystringrequired

          A user id, or the agent.id an API key named.

        • by_namestring | nullrequired

        • status_movedbooleanrequired

          Whether this contact moved the lead from new to contacted.

        • logged_atstringrequiredISO 8601 timestamp

          When the contact was logged: the time of the status change it made. Undo is open for a day after.

      • form_originobject | null

        Detail read only. The form a form or ad_form lead came from; null for other leads. ad holds the ad platform's ids for an ad_form lead (attribution.ad_form in lead.captured), null for a website form.

        4 attributes
        • form_idstring

        • form_namestring

        • channelstring

          One of website google_lead_form

        • adobject | null

      • bookingsarray of object

        Scheduling facts for this lead and mode, up to 200 bookings, oldest first. CRM outcome is unchanged.

        9 attributes
        • idstringrequired

        • uidstringrequired

        • event_namestringrequired

        • statusstringrequired

          One of pending processing confirmed completed rejected expired cancelled rescheduled

        • modestringrequired

          One of live test

        • start_atstringrequiredISO 8601 timestamp

        • end_atstringrequiredISO 8601 timestamp

        • timezonestringrequired

        • rescheduled_to_idstring | nullrequired

      • callbackobject | null

        The callback the visitor asked for in the lead's chat, as on the conversation. Detail read only.

        7 attributes
        • phonestring

        • slot_startstringISO 8601 timestamp

        • notestring

        • requested_atstringISO 8601 timestamp

        • done_atstringISO 8601 timestamp

        • done_bystring

        • done_by_namestring

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 409 lead_closed: a reminder date on a won or lost lead.
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
POST /api/leads/{id}/contacts
curl -X POST "https://api.brightshoal.com/api/leads/LEAD_ID/contacts" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "channel": "phone"
}'
Response 201
{
  "data": {
    "contact": {
      "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "channel": "phone",
      "via": "button",
      "contacted_at": "2026-10-28T09:30:00.000Z",
      "by": "string",
      "by_name": "string",
      "status_moved": true,
      "logged_at": "2026-10-28T09:30:00.000Z"
    },
    "lead": {
      "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "name": "Front desk",
      "email": "ana@example.com",
      "phone": "+14155550123",
      "fact_provenance": {
        "key": {
          "source": "conversation",
          "channel": "web_chat",
          "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "captured_at": "2026-10-28T09:30:00.000Z",
          "captured_at_estimated": true,
          "edited_at": "2026-10-28T09:30:00.000Z",
          "edited_by": "string"
        }
      },
      "fields": {
        "key": "string"
      },
      "source": "web_chat",
      "mode": "live",
      "test": true,
      "traffic": "real",
      "test_reason": "reserved_domain",
      "test_override": true,
      "outcome": "open",
      "outcome_value": "string",
      "outcome_currency": "string",
      "outcome_at": "2026-10-28T09:30:00.000Z",
      "outcome_ref": "string",
      "customer_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "status": "new",
      "status_changed_at": "2026-10-28T09:30:00.000Z",
      "status_changed_by": "string",
      "status_changed_by_name": "string",
      "attribution": {
        "chat_page": "string",
        "visit": {
          "landing_page": {},
          "referrer_host": {},
          "utm_source": {},
          "utm_medium": {},
          "utm_campaign": {},
          "utm_term": {},
          "utm_content": {},
          "gclid": {},
          "gbraid": {},
          "wbraid": {},
          "fbclid": {},
          "msclkid": {},
          "oppref": {},
          "ctwa_clid": {},
          "ad_id": {},
          "ad_source_type": {},
          "ad_source_url": {},
          "ad_headline": {},
          "whatsapp_link_id": {},
          "whatsapp_link_name": {}
        },
        "first": {
          "landing_page": {},
          "referrer_host": {},
          "utm_source": {},
          "utm_medium": {},
          "utm_campaign": {},
          "utm_term": {},
          "utm_content": {},
          "gclid": {},
          "gbraid": {},
          "wbraid": {},
          "fbclid": {},
          "msclkid": {},
          "oppref": {},
          "ctwa_clid": {},
          "ad_id": {},
          "ad_source_type": {},
          "ad_source_url": {},
          "ad_headline": {},
          "whatsapp_link_id": {},
          "whatsapp_link_name": {},
          "at": {}
        },
        "latest_paid": {
          "landing_page": {},
          "referrer_host": {},
          "utm_source": {},
          "utm_medium": {},
          "utm_campaign": {},
          "utm_term": {},
          "utm_content": {},
          "gclid": {},
          "gbraid": {},
          "wbraid": {},
          "fbclid": {},
          "msclkid": {},
          "oppref": {},
          "ctwa_clid": {},
          "ad_id": {},
          "ad_source_type": {},
          "ad_source_url": {},
          "ad_headline": {},
          "whatsapp_link_id": {},
          "whatsapp_link_name": {},
          "at": {}
        }
      },
      "created_at": "2026-10-28T09:30:00.000Z",
      "updated_at": "2026-10-28T09:30:00.000Z",
      "capture_method": "tool",
      "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "phone_e164": "+14155550123",
      "phone_source": "given",
      "first_contacted_at": "2026-10-28T09:30:00.000Z",
      "last_contacted_at": "2026-10-28T09:30:00.000Z",
      "next_follow_up_at": "2026-10-28T09:30:00.000Z",
      "time_to_first_contact_seconds": 1,
      "uncontacted_nudged_at": "2026-10-28T09:30:00.000Z",
      "merged_into_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "possible_repeat_of": [
        "string"
      ],
      "possible_duplicates": [
        {
          "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "name": "Front desk",
          "email": "ana@example.com",
          "phone": "+14155550123",
          "source": "web_chat",
          "created_at": "2026-10-28T09:30:00.000Z",
          "reason": "phone"
        }
      ],
      "merged_from": [
        {
          "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "name": "Front desk",
          "source": "web_chat",
          "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "created_at": "2026-10-28T09:30:00.000Z"
        }
      ],
      "status_history": [
        {
          "from": "new",
          "to": "new",
          "at": "2026-10-28T09:30:00.000Z",
          "by": "string",
          "by_name": "string"
        }
      ],
      "contacts": [
        {
          "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "channel": "phone",
          "via": "button",
          "contacted_at": "2026-10-28T09:30:00.000Z",
          "by": "string",
          "by_name": "string",
          "status_moved": true,
          "logged_at": "2026-10-28T09:30:00.000Z"
        }
      ],
      "form_origin": {
        "form_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "form_name": "string",
        "channel": "website",
        "ad": {}
      },
      "bookings": [
        {
          "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "uid": "string",
          "event_name": "string",
          "status": "pending",
          "mode": "live",
          "start_at": "2026-10-28T09:30:00.000Z",
          "end_at": "2026-10-28T09:30:00.000Z",
          "timezone": "string",
          "rescheduled_to_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
        }
      ],
      "callback": {
        "phone": "+14155550123",
        "slot_start": "2026-10-28T09:30:00.000Z",
        "note": "string",
        "requested_at": "2026-10-28T09:30:00.000Z",
        "done_at": "2026-10-28T09:30:00.000Z",
        "done_by": "string",
        "done_by_name": "string"
      }
    }
  }
}

Undo a contact

POST/api/leads/{id}/contacts/{contactId}/void

Requires a member. Voids a contact within 24 hours of logging it; a repeat changes nothing. The contact times are recomputed, and a contact that moved the lead from new moves it back while it is still contacted. Audited.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

    Lead id, lead_....

  • contactIdstringrequired

    Contact id, lcon_....

Returns

200 OK

Response attributes
  • dataobjectrequired

    1 attribute
    • leadLeadDetailrequired

      48 attributes
      • idstringrequired

      • org_idstringrequired

      • project_idstringrequired

      • assistant_idstring | null

        The assistant that captured the lead; null when no assistant did (a form lead, or one added by hand).

      • conversation_idstring | null

      • namestring | null

      • emailstring | nullemail

      • phonestring | null

      • fact_provenanceobject

        Provenance per field key, including name, email and phone. Legacy values use lead creation time with captured_at_estimated true; edits retain captured_at and set edited_at and edited_by.

        9 attributes
        • sourcestringrequired

          One of conversation channel form manual

        • channelstringrequired

          One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

        • conversation_idstring | nullrequired

        • call_idstring | nullrequired

        • form_submission_idstring | nullrequired

        • captured_atstringrequiredISO 8601 timestamp

        • captured_at_estimatedbooleanrequired

        • edited_atstring | nullrequiredISO 8601 timestamp

        • edited_bystring | nullrequired

      • fieldsobject | null

      • sourcestringrequired

        Where the lead came from: web_chat, web_call (a call from a browser), phone_call, sms, whatsapp, form, ad_form (an ad platform's own lead form, such as a Google lead form), scheduling (a booking) or other (such as a lead added by hand).

        One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

      • modestring

        Capture provenance: the chat mode, independent of email classification.

        One of live test preview

      • testboolean

        Effective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See traffic to tell them apart.

      • trafficstring

        Which traffic this belongs to: sandbox (made through a non-live key: a sandbox key, the console's sandbox chat, a sandbox phone or WhatsApp number, or a preview link), test (a live chat or lead one of our rules caught: a test marker, a staging or preview page, a placeholder or own-domain email, or marked as test by hand) or real. Sandbox wins over test. Sandbox and test are both left out of real numbers.

        One of real sandbox test

      • test_reasonstring | null

        Automatic classification, recomputed when saved: reserved_domain (placeholder email), business_domain (your own email domain) or staging_site (a live chat on a staging or preview page). An email reason wins over staging_site.

        One of reserved_domain business_domain staging_site

      • test_overrideboolean | null

        Member override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox.

      • outcomestring | null

        What became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).

        One of open booked lost

      • outcome_valuestring | null

        Booking value as a decimal string.

      • outcome_currencystring | null

      • outcome_atstring | nullISO 8601 timestamp

      • outcome_refstring | null

        The CRM's own id for the booking.

      • customer_idstring | null

        The customer's own id for this person, set with PUT /v1/leads/{id}/outcome.

      • statusstring

        The front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts new. new, contacted and qualified are open; won and lost close it. Separate from outcome, which your CRM reports.

        One of new contacted qualified won lost

      • status_changed_atstring | nullISO 8601 timestamp

      • status_changed_bystring | null

        A user id, or the agent.id an API key named.

      • status_changed_by_namestring | null

      • attributionChatAttribution | null

        Where the lead's chat came from. Returned by the list and detail reads; null when none was recorded.

        One of 2 shapes

        ChatAttribution

        • chat_pagestring

          The path the visitor started chatting on.

        • visitChatAttributionTouch

          This visit's landing.

          20 attributes
          • landing_pagestring

            A path starting with /, without query or fragment.

          • referrer_hoststring

          • utm_sourcestring

          • utm_mediumstring

          • utm_campaignstring

          • utm_termstring

          • utm_contentstring

          • gclidstring

          • gbraidstring

          • wbraidstring

          • fbclidstring

          • msclkidstring

          • opprefstring

          • ctwa_clidstring

            WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

          • ad_idstring

            WhatsApp only: the ad or post id (source_id) from Meta's referral.

          • ad_source_typestring

            WhatsApp only: ad or post.

          • ad_source_urlstring

            WhatsApp only: the ad's URL, up to 512 characters.

          • ad_headlinestring

            WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

          • whatsapp_link_idstring

            WhatsApp only: the campaign link (wal_...) the chat started from.

          • whatsapp_link_namestring

            WhatsApp only: that campaign link's name.

        • firstobject

          The visitor's first-ever landing.

          21 attributes
          • landing_pagestring

            A path starting with /, without query or fragment.

          • referrer_hoststring

          • utm_sourcestring

          • utm_mediumstring

          • utm_campaignstring

          • utm_termstring

          • utm_contentstring

          • gclidstring

          • gbraidstring

          • wbraidstring

          • fbclidstring

          • msclkidstring

          • opprefstring

          • ctwa_clidstring

            WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

          • ad_idstring

            WhatsApp only: the ad or post id (source_id) from Meta's referral.

          • ad_source_typestring

            WhatsApp only: ad or post.

          • ad_source_urlstring

            WhatsApp only: the ad's URL, up to 512 characters.

          • ad_headlinestring

            WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

          • whatsapp_link_idstring

            WhatsApp only: the campaign link (wal_...) the chat started from.

          • whatsapp_link_namestring

            WhatsApp only: that campaign link's name.

          • atstringISO 8601 timestamp

            When the visitor first landed.

        • latest_paidobject

          The visitor's latest ad click within 90 days: a landing with a click id, or with utm_medium cpc, ppc or paid*. Recorded even when the click came inside a visit that began elsewhere, and kept through later direct visits, so it can differ from visit and first.

          21 attributes
          • landing_pagestring

            A path starting with /, without query or fragment.

          • referrer_hoststring

          • utm_sourcestring

          • utm_mediumstring

          • utm_campaignstring

          • utm_termstring

          • utm_contentstring

          • gclidstring

          • gbraidstring

          • wbraidstring

          • fbclidstring

          • msclkidstring

          • opprefstring

          • ctwa_clidstring

            WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

          • ad_idstring

            WhatsApp only: the ad or post id (source_id) from Meta's referral.

          • ad_source_typestring

            WhatsApp only: ad or post.

          • ad_source_urlstring

            WhatsApp only: the ad's URL, up to 512 characters.

          • ad_headlinestring

            WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

          • whatsapp_link_idstring

            WhatsApp only: the campaign link (wal_...) the chat started from.

          • whatsapp_link_namestring

            WhatsApp only: that campaign link's name.

          • atstringISO 8601 timestamp

            When the visitor landed from this ad click.

        Option 2

      • created_atstringISO 8601 timestamp

      • updated_atstringISO 8601 timestamp

      • capture_methodstring

        How the lead was first saved: tool (the assistant saved it during the conversation), analysis (read from the conversation afterwards), form (a form submission) manual (added by hand) or scheduling (a direct booking). Later updates never change it.

        One of tool analysis form manual scheduling

      • call_idstring | null

        The call the lead came from, when it came from one.

      • form_submission_idstring | null

        The form submission the lead came from, when it came from one.

      • phone_e164string | null

        phone in E.164 form when it could be read as a number; phone stays as given.

      • phone_sourcestring | null

        caller_id when a call lead's phone is the number the call came from, because the caller never said one. Null means the person gave it.

        One of given caller_id

      • first_contacted_atstring | nullISO 8601 timestamp

        The first contact: the earliest logged contact, or the first status change out of new by a person or key. Null until contacted.

      • last_contacted_atstring | nullISO 8601 timestamp

        The latest contact.

      • next_follow_up_atstring | nullISO 8601 timestamp

        When to contact the lead again. Cleared when the lead is won or lost.

      • time_to_first_contact_secondsinteger | null

        Wall clock from created_at to first_contacted_at, in seconds. Null until contacted.

      • uncontacted_nudged_atstring | nullISO 8601 timestamp

        When lead.uncontacted was recorded for the lead; null when it never was.

      • merged_into_idstring | null

        The kept lead's id when this lead was merged. Merged leads remain readable by id.

      • possible_repeat_ofarray of string

        Detail read only. For a call lead whose caller's number matched earlier open enquiries but who did not say whether this call was about one of them: those leads' ids. Empty otherwise. This historical hint does not perform a merge.

      • possible_duplicatesarray of objectup to 5 items

        Other unmerged leads in this org and project matching a non-null phone_e164, a non-blank trimmed case-insensitive email, or possible_repeat_of. Dismissals on either side are excluded. Newest first, unique by id; phone wins over email, then repeat_caller. Empty when this lead is merged.

        7 attributes
        • idstringrequired

        • namestring | nullrequired

        • emailstring | nullrequired

        • phonestring | nullrequired

        • sourcestringrequired

          One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

        • created_atstringrequiredISO 8601 timestamp

        • reasonstringrequired

          One of phone email repeat_caller

      • merged_fromarray of object

        Leads merged into this lead, oldest first. Origin links stay on these rows, including all earlier merges.

        7 attributes
        • idstringrequired

        • namestring | nullrequired

        • sourcestringrequired

          One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

        • conversation_idstring | nullrequired

        • call_idstring | nullrequired

        • form_submission_idstring | nullrequired

        • created_atstringrequiredISO 8601 timestamp

      • status_historyarray of object

        Every status change, oldest first.

        5 attributes
        • fromstringrequired

          One of new contacted qualified won lost

        • tostringrequired

          One of new contacted qualified won lost

        • atstringrequiredISO 8601 timestamp

        • bystringrequired

        • by_namestring | nullrequired

      • contactsarray of LeadContact

        Detail read only. Live logged contacts, newest first; voided ones are left out.

        8 attributes
        • idstringrequired

          lcon_....

        • channelstringrequired

          One of phone whatsapp email sms in_person other

        • viastringrequired

          A console contact button, Log contact, or the API.

          One of button manual api

        • contacted_atstringrequiredISO 8601 timestamp

        • bystringrequired

          A user id, or the agent.id an API key named.

        • by_namestring | nullrequired

        • status_movedbooleanrequired

          Whether this contact moved the lead from new to contacted.

        • logged_atstringrequiredISO 8601 timestamp

          When the contact was logged: the time of the status change it made. Undo is open for a day after.

      • form_originobject | null

        Detail read only. The form a form or ad_form lead came from; null for other leads. ad holds the ad platform's ids for an ad_form lead (attribution.ad_form in lead.captured), null for a website form.

        4 attributes
        • form_idstring

        • form_namestring

        • channelstring

          One of website google_lead_form

        • adobject | null

      • bookingsarray of object

        Scheduling facts for this lead and mode, up to 200 bookings, oldest first. CRM outcome is unchanged.

        9 attributes
        • idstringrequired

        • uidstringrequired

        • event_namestringrequired

        • statusstringrequired

          One of pending processing confirmed completed rejected expired cancelled rescheduled

        • modestringrequired

          One of live test

        • start_atstringrequiredISO 8601 timestamp

        • end_atstringrequiredISO 8601 timestamp

        • timezonestringrequired

        • rescheduled_to_idstring | nullrequired

      • callbackobject | null

        The callback the visitor asked for in the lead's chat, as on the conversation. Detail read only.

        7 attributes
        • phonestring

        • slot_startstringISO 8601 timestamp

        • notestring

        • requested_atstringISO 8601 timestamp

        • done_atstringISO 8601 timestamp

        • done_bystring

        • done_by_namestring

  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 409 void_window_passed: more than 24 hours since it was logged.
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
POST /api/leads/{id}/contacts/{contactId}/void
curl -X POST "https://api.brightshoal.com/api/leads/LEAD_ID/contacts/CONTACT_ID/void" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "lead": {
      "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "name": "Front desk",
      "email": "ana@example.com",
      "phone": "+14155550123",
      "fact_provenance": {
        "key": {
          "source": "conversation",
          "channel": "web_chat",
          "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "captured_at": "2026-10-28T09:30:00.000Z",
          "captured_at_estimated": true,
          "edited_at": "2026-10-28T09:30:00.000Z",
          "edited_by": "string"
        }
      },
      "fields": {
        "key": "string"
      },
      "source": "web_chat",
      "mode": "live",
      "test": true,
      "traffic": "real",
      "test_reason": "reserved_domain",
      "test_override": true,
      "outcome": "open",
      "outcome_value": "string",
      "outcome_currency": "string",
      "outcome_at": "2026-10-28T09:30:00.000Z",
      "outcome_ref": "string",
      "customer_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "status": "new",
      "status_changed_at": "2026-10-28T09:30:00.000Z",
      "status_changed_by": "string",
      "status_changed_by_name": "string",
      "attribution": {
        "chat_page": "string",
        "visit": {
          "landing_page": {},
          "referrer_host": {},
          "utm_source": {},
          "utm_medium": {},
          "utm_campaign": {},
          "utm_term": {},
          "utm_content": {},
          "gclid": {},
          "gbraid": {},
          "wbraid": {},
          "fbclid": {},
          "msclkid": {},
          "oppref": {},
          "ctwa_clid": {},
          "ad_id": {},
          "ad_source_type": {},
          "ad_source_url": {},
          "ad_headline": {},
          "whatsapp_link_id": {},
          "whatsapp_link_name": {}
        },
        "first": {
          "landing_page": {},
          "referrer_host": {},
          "utm_source": {},
          "utm_medium": {},
          "utm_campaign": {},
          "utm_term": {},
          "utm_content": {},
          "gclid": {},
          "gbraid": {},
          "wbraid": {},
          "fbclid": {},
          "msclkid": {},
          "oppref": {},
          "ctwa_clid": {},
          "ad_id": {},
          "ad_source_type": {},
          "ad_source_url": {},
          "ad_headline": {},
          "whatsapp_link_id": {},
          "whatsapp_link_name": {},
          "at": {}
        },
        "latest_paid": {
          "landing_page": {},
          "referrer_host": {},
          "utm_source": {},
          "utm_medium": {},
          "utm_campaign": {},
          "utm_term": {},
          "utm_content": {},
          "gclid": {},
          "gbraid": {},
          "wbraid": {},
          "fbclid": {},
          "msclkid": {},
          "oppref": {},
          "ctwa_clid": {},
          "ad_id": {},
          "ad_source_type": {},
          "ad_source_url": {},
          "ad_headline": {},
          "whatsapp_link_id": {},
          "whatsapp_link_name": {},
          "at": {}
        }
      },
      "created_at": "2026-10-28T09:30:00.000Z",
      "updated_at": "2026-10-28T09:30:00.000Z",
      "capture_method": "tool",
      "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "phone_e164": "+14155550123",
      "phone_source": "given",
      "first_contacted_at": "2026-10-28T09:30:00.000Z",
      "last_contacted_at": "2026-10-28T09:30:00.000Z",
      "next_follow_up_at": "2026-10-28T09:30:00.000Z",
      "time_to_first_contact_seconds": 1,
      "uncontacted_nudged_at": "2026-10-28T09:30:00.000Z",
      "merged_into_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "possible_repeat_of": [
        "string"
      ],
      "possible_duplicates": [
        {
          "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "name": "Front desk",
          "email": "ana@example.com",
          "phone": "+14155550123",
          "source": "web_chat",
          "created_at": "2026-10-28T09:30:00.000Z",
          "reason": "phone"
        }
      ],
      "merged_from": [
        {
          "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "name": "Front desk",
          "source": "web_chat",
          "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "created_at": "2026-10-28T09:30:00.000Z"
        }
      ],
      "status_history": [
        {
          "from": "new",
          "to": "new",
          "at": "2026-10-28T09:30:00.000Z",
          "by": "string",
          "by_name": "string"
        }
      ],
      "contacts": [
        {
          "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "channel": "phone",
          "via": "button",
          "contacted_at": "2026-10-28T09:30:00.000Z",
          "by": "string",
          "by_name": "string",
          "status_moved": true,
          "logged_at": "2026-10-28T09:30:00.000Z"
        }
      ],
      "form_origin": {
        "form_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "form_name": "string",
        "channel": "website",
        "ad": {}
      },
      "bookings": [
        {
          "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "uid": "string",
          "event_name": "string",
          "status": "pending",
          "mode": "live",
          "start_at": "2026-10-28T09:30:00.000Z",
          "end_at": "2026-10-28T09:30:00.000Z",
          "timezone": "string",
          "rescheduled_to_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
        }
      ],
      "callback": {
        "phone": "+14155550123",
        "slot_start": "2026-10-28T09:30:00.000Z",
        "note": "string",
        "requested_at": "2026-10-28T09:30:00.000Z",
        "done_at": "2026-10-28T09:30:00.000Z",
        "done_by": "string",
        "done_by_name": "string"
      }
    }
  }
}

Edit one captured lead fact

PATCH/api/leads/{id}/facts/{field}

Member role. Edits name, email, phone or a custom field. Null clears it. Records manual provenance, original capture time, edit time and actor. Does not send a message or lead webhook. Merged leads cannot be edited.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

  • fieldstringrequired

Request body

  • valuestring | nullrequiredup to 500 characters

Returns

200 OK

Response attributes
  • dataLeadrequired

    40 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • assistant_idstring | null

      The assistant that captured the lead; null when no assistant did (a form lead, or one added by hand).

    • conversation_idstring | null

    • namestring | null

    • emailstring | nullemail

    • phonestring | null

    • fact_provenanceobject

      Provenance per field key, including name, email and phone. Legacy values use lead creation time with captured_at_estimated true; edits retain captured_at and set edited_at and edited_by.

      9 attributes
      • sourcestringrequired

        One of conversation channel form manual

      • channelstringrequired

        One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

      • conversation_idstring | nullrequired

      • call_idstring | nullrequired

      • form_submission_idstring | nullrequired

      • captured_atstringrequiredISO 8601 timestamp

      • captured_at_estimatedbooleanrequired

      • edited_atstring | nullrequiredISO 8601 timestamp

      • edited_bystring | nullrequired

    • fieldsobject | null

    • sourcestringrequired

      Where the lead came from: web_chat, web_call (a call from a browser), phone_call, sms, whatsapp, form, ad_form (an ad platform's own lead form, such as a Google lead form), scheduling (a booking) or other (such as a lead added by hand).

      One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

    • modestring

      Capture provenance: the chat mode, independent of email classification.

      One of live test preview

    • testboolean

      Effective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See traffic to tell them apart.

    • trafficstring

      Which traffic this belongs to: sandbox (made through a non-live key: a sandbox key, the console's sandbox chat, a sandbox phone or WhatsApp number, or a preview link), test (a live chat or lead one of our rules caught: a test marker, a staging or preview page, a placeholder or own-domain email, or marked as test by hand) or real. Sandbox wins over test. Sandbox and test are both left out of real numbers.

      One of real sandbox test

    • test_reasonstring | null

      Automatic classification, recomputed when saved: reserved_domain (placeholder email), business_domain (your own email domain) or staging_site (a live chat on a staging or preview page). An email reason wins over staging_site.

      One of reserved_domain business_domain staging_site

    • test_overrideboolean | null

      Member override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox.

    • outcomestring | null

      What became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).

      One of open booked lost

    • outcome_valuestring | null

      Booking value as a decimal string.

    • outcome_currencystring | null

    • outcome_atstring | nullISO 8601 timestamp

    • outcome_refstring | null

      The CRM's own id for the booking.

    • customer_idstring | null

      The customer's own id for this person, set with PUT /v1/leads/{id}/outcome.

    • statusstring

      The front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts new. new, contacted and qualified are open; won and lost close it. Separate from outcome, which your CRM reports.

      One of new contacted qualified won lost

    • status_changed_atstring | nullISO 8601 timestamp

    • status_changed_bystring | null

      A user id, or the agent.id an API key named.

    • status_changed_by_namestring | null

    • attributionChatAttribution | null

      Where the lead's chat came from. Returned by the list and detail reads; null when none was recorded.

      One of 2 shapes

      ChatAttribution

      • chat_pagestring

        The path the visitor started chatting on.

      • visitChatAttributionTouch

        This visit's landing.

        20 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

      • firstobject

        The visitor's first-ever landing.

        21 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

        • atstringISO 8601 timestamp

          When the visitor first landed.

      • latest_paidobject

        The visitor's latest ad click within 90 days: a landing with a click id, or with utm_medium cpc, ppc or paid*. Recorded even when the click came inside a visit that began elsewhere, and kept through later direct visits, so it can differ from visit and first.

        21 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

        • atstringISO 8601 timestamp

          When the visitor landed from this ad click.

      Option 2

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • capture_methodstring

      How the lead was first saved: tool (the assistant saved it during the conversation), analysis (read from the conversation afterwards), form (a form submission) manual (added by hand) or scheduling (a direct booking). Later updates never change it.

      One of tool analysis form manual scheduling

    • call_idstring | null

      The call the lead came from, when it came from one.

    • form_submission_idstring | null

      The form submission the lead came from, when it came from one.

    • phone_e164string | null

      phone in E.164 form when it could be read as a number; phone stays as given.

    • phone_sourcestring | null

      caller_id when a call lead's phone is the number the call came from, because the caller never said one. Null means the person gave it.

      One of given caller_id

    • first_contacted_atstring | nullISO 8601 timestamp

      The first contact: the earliest logged contact, or the first status change out of new by a person or key. Null until contacted.

    • last_contacted_atstring | nullISO 8601 timestamp

      The latest contact.

    • next_follow_up_atstring | nullISO 8601 timestamp

      When to contact the lead again. Cleared when the lead is won or lost.

    • time_to_first_contact_secondsinteger | null

      Wall clock from created_at to first_contacted_at, in seconds. Null until contacted.

    • uncontacted_nudged_atstring | nullISO 8601 timestamp

      When lead.uncontacted was recorded for the lead; null when it never was.

    • merged_into_idstring | null

      The kept lead's id when this lead was merged. Merged leads remain readable by id.

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
PATCH /api/leads/{id}/facts/{field}
curl -X PATCH "https://api.brightshoal.com/api/leads/LEAD_ID/facts/FIELD" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "value": "string"
}'
Response 200
{
  "data": {
    "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "email": "ana@example.com",
    "phone": "+14155550123",
    "fact_provenance": {
      "key": {
        "source": "conversation",
        "channel": "web_chat",
        "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "captured_at": "2026-10-28T09:30:00.000Z",
        "captured_at_estimated": true,
        "edited_at": "2026-10-28T09:30:00.000Z",
        "edited_by": "string"
      }
    },
    "fields": {
      "key": "string"
    },
    "source": "web_chat",
    "mode": "live",
    "test": true,
    "traffic": "real",
    "test_reason": "reserved_domain",
    "test_override": true,
    "outcome": "open",
    "outcome_value": "string",
    "outcome_currency": "string",
    "outcome_at": "2026-10-28T09:30:00.000Z",
    "outcome_ref": "string",
    "customer_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "status": "new",
    "status_changed_at": "2026-10-28T09:30:00.000Z",
    "status_changed_by": "string",
    "status_changed_by_name": "string",
    "attribution": {
      "chat_page": "string",
      "visit": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "oppref": "string",
        "ctwa_clid": "string",
        "ad_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "ad_source_type": "string",
        "ad_source_url": "https://example.com/hook",
        "ad_headline": "string",
        "whatsapp_link_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "whatsapp_link_name": "string"
      },
      "first": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "oppref": "string",
        "ctwa_clid": "string",
        "ad_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "ad_source_type": "string",
        "ad_source_url": "https://example.com/hook",
        "ad_headline": "string",
        "whatsapp_link_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "whatsapp_link_name": "string",
        "at": "2026-10-28T09:30:00.000Z"
      },
      "latest_paid": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "oppref": "string",
        "ctwa_clid": "string",
        "ad_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "ad_source_type": "string",
        "ad_source_url": "https://example.com/hook",
        "ad_headline": "string",
        "whatsapp_link_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "whatsapp_link_name": "string",
        "at": "2026-10-28T09:30:00.000Z"
      }
    },
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z",
    "capture_method": "tool",
    "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "phone_e164": "+14155550123",
    "phone_source": "given",
    "first_contacted_at": "2026-10-28T09:30:00.000Z",
    "last_contacted_at": "2026-10-28T09:30:00.000Z",
    "next_follow_up_at": "2026-10-28T09:30:00.000Z",
    "time_to_first_contact_seconds": 1,
    "uncontacted_nudged_at": "2026-10-28T09:30:00.000Z",
    "merged_into_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}

Set a lead's reminder

PUT/api/leads/{id}/follow-up

Requires a member. Sets or clears the reminder (next_follow_up_at). Audited.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

    Lead id, lead_....

Request body

  • next_follow_up_atstring | nullrequiredISO 8601 timestamp

    When to contact again: within a year, not more than 5 minutes past. Null clears it; absent leaves it. A date on a won or lost lead is 409 lead_closed.

Returns

200 OK

Response attributes
  • dataLeadDetailrequired

    48 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • assistant_idstring | null

      The assistant that captured the lead; null when no assistant did (a form lead, or one added by hand).

    • conversation_idstring | null

    • namestring | null

    • emailstring | nullemail

    • phonestring | null

    • fact_provenanceobject

      Provenance per field key, including name, email and phone. Legacy values use lead creation time with captured_at_estimated true; edits retain captured_at and set edited_at and edited_by.

      9 attributes
      • sourcestringrequired

        One of conversation channel form manual

      • channelstringrequired

        One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

      • conversation_idstring | nullrequired

      • call_idstring | nullrequired

      • form_submission_idstring | nullrequired

      • captured_atstringrequiredISO 8601 timestamp

      • captured_at_estimatedbooleanrequired

      • edited_atstring | nullrequiredISO 8601 timestamp

      • edited_bystring | nullrequired

    • fieldsobject | null

    • sourcestringrequired

      Where the lead came from: web_chat, web_call (a call from a browser), phone_call, sms, whatsapp, form, ad_form (an ad platform's own lead form, such as a Google lead form), scheduling (a booking) or other (such as a lead added by hand).

      One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

    • modestring

      Capture provenance: the chat mode, independent of email classification.

      One of live test preview

    • testboolean

      Effective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See traffic to tell them apart.

    • trafficstring

      Which traffic this belongs to: sandbox (made through a non-live key: a sandbox key, the console's sandbox chat, a sandbox phone or WhatsApp number, or a preview link), test (a live chat or lead one of our rules caught: a test marker, a staging or preview page, a placeholder or own-domain email, or marked as test by hand) or real. Sandbox wins over test. Sandbox and test are both left out of real numbers.

      One of real sandbox test

    • test_reasonstring | null

      Automatic classification, recomputed when saved: reserved_domain (placeholder email), business_domain (your own email domain) or staging_site (a live chat on a staging or preview page). An email reason wins over staging_site.

      One of reserved_domain business_domain staging_site

    • test_overrideboolean | null

      Member override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox.

    • outcomestring | null

      What became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).

      One of open booked lost

    • outcome_valuestring | null

      Booking value as a decimal string.

    • outcome_currencystring | null

    • outcome_atstring | nullISO 8601 timestamp

    • outcome_refstring | null

      The CRM's own id for the booking.

    • customer_idstring | null

      The customer's own id for this person, set with PUT /v1/leads/{id}/outcome.

    • statusstring

      The front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts new. new, contacted and qualified are open; won and lost close it. Separate from outcome, which your CRM reports.

      One of new contacted qualified won lost

    • status_changed_atstring | nullISO 8601 timestamp

    • status_changed_bystring | null

      A user id, or the agent.id an API key named.

    • status_changed_by_namestring | null

    • attributionChatAttribution | null

      Where the lead's chat came from. Returned by the list and detail reads; null when none was recorded.

      One of 2 shapes

      ChatAttribution

      • chat_pagestring

        The path the visitor started chatting on.

      • visitChatAttributionTouch

        This visit's landing.

        20 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

      • firstobject

        The visitor's first-ever landing.

        21 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

        • atstringISO 8601 timestamp

          When the visitor first landed.

      • latest_paidobject

        The visitor's latest ad click within 90 days: a landing with a click id, or with utm_medium cpc, ppc or paid*. Recorded even when the click came inside a visit that began elsewhere, and kept through later direct visits, so it can differ from visit and first.

        21 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

        • atstringISO 8601 timestamp

          When the visitor landed from this ad click.

      Option 2

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • capture_methodstring

      How the lead was first saved: tool (the assistant saved it during the conversation), analysis (read from the conversation afterwards), form (a form submission) manual (added by hand) or scheduling (a direct booking). Later updates never change it.

      One of tool analysis form manual scheduling

    • call_idstring | null

      The call the lead came from, when it came from one.

    • form_submission_idstring | null

      The form submission the lead came from, when it came from one.

    • phone_e164string | null

      phone in E.164 form when it could be read as a number; phone stays as given.

    • phone_sourcestring | null

      caller_id when a call lead's phone is the number the call came from, because the caller never said one. Null means the person gave it.

      One of given caller_id

    • first_contacted_atstring | nullISO 8601 timestamp

      The first contact: the earliest logged contact, or the first status change out of new by a person or key. Null until contacted.

    • last_contacted_atstring | nullISO 8601 timestamp

      The latest contact.

    • next_follow_up_atstring | nullISO 8601 timestamp

      When to contact the lead again. Cleared when the lead is won or lost.

    • time_to_first_contact_secondsinteger | null

      Wall clock from created_at to first_contacted_at, in seconds. Null until contacted.

    • uncontacted_nudged_atstring | nullISO 8601 timestamp

      When lead.uncontacted was recorded for the lead; null when it never was.

    • merged_into_idstring | null

      The kept lead's id when this lead was merged. Merged leads remain readable by id.

    • possible_repeat_ofarray of string

      Detail read only. For a call lead whose caller's number matched earlier open enquiries but who did not say whether this call was about one of them: those leads' ids. Empty otherwise. This historical hint does not perform a merge.

    • possible_duplicatesarray of objectup to 5 items

      Other unmerged leads in this org and project matching a non-null phone_e164, a non-blank trimmed case-insensitive email, or possible_repeat_of. Dismissals on either side are excluded. Newest first, unique by id; phone wins over email, then repeat_caller. Empty when this lead is merged.

      7 attributes
      • idstringrequired

      • namestring | nullrequired

      • emailstring | nullrequired

      • phonestring | nullrequired

      • sourcestringrequired

        One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

      • created_atstringrequiredISO 8601 timestamp

      • reasonstringrequired

        One of phone email repeat_caller

    • merged_fromarray of object

      Leads merged into this lead, oldest first. Origin links stay on these rows, including all earlier merges.

      7 attributes
      • idstringrequired

      • namestring | nullrequired

      • sourcestringrequired

        One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

      • conversation_idstring | nullrequired

      • call_idstring | nullrequired

      • form_submission_idstring | nullrequired

      • created_atstringrequiredISO 8601 timestamp

    • status_historyarray of object

      Every status change, oldest first.

      5 attributes
      • fromstringrequired

        One of new contacted qualified won lost

      • tostringrequired

        One of new contacted qualified won lost

      • atstringrequiredISO 8601 timestamp

      • bystringrequired

      • by_namestring | nullrequired

    • contactsarray of LeadContact

      Detail read only. Live logged contacts, newest first; voided ones are left out.

      8 attributes
      • idstringrequired

        lcon_....

      • channelstringrequired

        One of phone whatsapp email sms in_person other

      • viastringrequired

        A console contact button, Log contact, or the API.

        One of button manual api

      • contacted_atstringrequiredISO 8601 timestamp

      • bystringrequired

        A user id, or the agent.id an API key named.

      • by_namestring | nullrequired

      • status_movedbooleanrequired

        Whether this contact moved the lead from new to contacted.

      • logged_atstringrequiredISO 8601 timestamp

        When the contact was logged: the time of the status change it made. Undo is open for a day after.

    • form_originobject | null

      Detail read only. The form a form or ad_form lead came from; null for other leads. ad holds the ad platform's ids for an ad_form lead (attribution.ad_form in lead.captured), null for a website form.

      4 attributes
      • form_idstring

      • form_namestring

      • channelstring

        One of website google_lead_form

      • adobject | null

    • bookingsarray of object

      Scheduling facts for this lead and mode, up to 200 bookings, oldest first. CRM outcome is unchanged.

      9 attributes
      • idstringrequired

      • uidstringrequired

      • event_namestringrequired

      • statusstringrequired

        One of pending processing confirmed completed rejected expired cancelled rescheduled

      • modestringrequired

        One of live test

      • start_atstringrequiredISO 8601 timestamp

      • end_atstringrequiredISO 8601 timestamp

      • timezonestringrequired

      • rescheduled_to_idstring | nullrequired

    • callbackobject | null

      The callback the visitor asked for in the lead's chat, as on the conversation. Detail read only.

      7 attributes
      • phonestring

      • slot_startstringISO 8601 timestamp

      • notestring

      • requested_atstringISO 8601 timestamp

      • done_atstringISO 8601 timestamp

      • done_bystring

      • done_by_namestring

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 409 lead_closed: the lead is won or lost.
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
PUT /api/leads/{id}/follow-up
curl -X PUT "https://api.brightshoal.com/api/leads/LEAD_ID/follow-up" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "next_follow_up_at": "2026-10-28T09:30:00.000Z"
}'
Response 200
{
  "data": {
    "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "email": "ana@example.com",
    "phone": "+14155550123",
    "fact_provenance": {
      "key": {
        "source": "conversation",
        "channel": "web_chat",
        "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "captured_at": "2026-10-28T09:30:00.000Z",
        "captured_at_estimated": true,
        "edited_at": "2026-10-28T09:30:00.000Z",
        "edited_by": "string"
      }
    },
    "fields": {
      "key": "string"
    },
    "source": "web_chat",
    "mode": "live",
    "test": true,
    "traffic": "real",
    "test_reason": "reserved_domain",
    "test_override": true,
    "outcome": "open",
    "outcome_value": "string",
    "outcome_currency": "string",
    "outcome_at": "2026-10-28T09:30:00.000Z",
    "outcome_ref": "string",
    "customer_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "status": "new",
    "status_changed_at": "2026-10-28T09:30:00.000Z",
    "status_changed_by": "string",
    "status_changed_by_name": "string",
    "attribution": {
      "chat_page": "string",
      "visit": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "oppref": "string",
        "ctwa_clid": "string",
        "ad_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "ad_source_type": "string",
        "ad_source_url": "https://example.com/hook",
        "ad_headline": "string",
        "whatsapp_link_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "whatsapp_link_name": "string"
      },
      "first": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "oppref": "string",
        "ctwa_clid": "string",
        "ad_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "ad_source_type": "string",
        "ad_source_url": "https://example.com/hook",
        "ad_headline": "string",
        "whatsapp_link_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "whatsapp_link_name": "string",
        "at": "2026-10-28T09:30:00.000Z"
      },
      "latest_paid": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "oppref": "string",
        "ctwa_clid": "string",
        "ad_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "ad_source_type": "string",
        "ad_source_url": "https://example.com/hook",
        "ad_headline": "string",
        "whatsapp_link_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "whatsapp_link_name": "string",
        "at": "2026-10-28T09:30:00.000Z"
      }
    },
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z",
    "capture_method": "tool",
    "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "phone_e164": "+14155550123",
    "phone_source": "given",
    "first_contacted_at": "2026-10-28T09:30:00.000Z",
    "last_contacted_at": "2026-10-28T09:30:00.000Z",
    "next_follow_up_at": "2026-10-28T09:30:00.000Z",
    "time_to_first_contact_seconds": 1,
    "uncontacted_nudged_at": "2026-10-28T09:30:00.000Z",
    "merged_into_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "possible_repeat_of": [
      "string"
    ],
    "possible_duplicates": [
      {
        "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "name": "Front desk",
        "email": "ana@example.com",
        "phone": "+14155550123",
        "source": "web_chat",
        "created_at": "2026-10-28T09:30:00.000Z",
        "reason": "phone"
      }
    ],
    "merged_from": [
      {
        "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "name": "Front desk",
        "source": "web_chat",
        "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "created_at": "2026-10-28T09:30:00.000Z"
      }
    ],
    "status_history": [
      {
        "from": "new",
        "to": "new",
        "at": "2026-10-28T09:30:00.000Z",
        "by": "string",
        "by_name": "string"
      }
    ],
    "contacts": [
      {
        "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "channel": "phone",
        "via": "button",
        "contacted_at": "2026-10-28T09:30:00.000Z",
        "by": "string",
        "by_name": "string",
        "status_moved": true,
        "logged_at": "2026-10-28T09:30:00.000Z"
      }
    ],
    "form_origin": {
      "form_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "form_name": "string",
      "channel": "website",
      "ad": {}
    },
    "bookings": [
      {
        "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "uid": "string",
        "event_name": "string",
        "status": "pending",
        "mode": "live",
        "start_at": "2026-10-28T09:30:00.000Z",
        "end_at": "2026-10-28T09:30:00.000Z",
        "timezone": "string",
        "rescheduled_to_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
      }
    ],
    "callback": {
      "phone": "+14155550123",
      "slot_start": "2026-10-28T09:30:00.000Z",
      "note": "string",
      "requested_at": "2026-10-28T09:30:00.000Z",
      "done_at": "2026-10-28T09:30:00.000Z",
      "done_by": "string",
      "done_by_name": "string"
    }
  }
}

Merge a duplicate lead

POST/api/leads/{id}/merge

Requires a member. Both leads must be visible in the same project. Keeps this lead, filling only blank contact values and fields from duplicate_id. Statuses and origin links stay on their rows; earlier merges move to this lead. The duplicate stays readable by id with merged_into_id set, but is excluded from lists, attention, speed and new work. Audited as lead.merged; no webhook.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

    The lead to keep.

Request body

  • duplicate_idstringrequirednot empty

Returns

200 OK

Response attributes
  • dataLeadDetailrequired

    48 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • assistant_idstring | null

      The assistant that captured the lead; null when no assistant did (a form lead, or one added by hand).

    • conversation_idstring | null

    • namestring | null

    • emailstring | nullemail

    • phonestring | null

    • fact_provenanceobject

      Provenance per field key, including name, email and phone. Legacy values use lead creation time with captured_at_estimated true; edits retain captured_at and set edited_at and edited_by.

      9 attributes
      • sourcestringrequired

        One of conversation channel form manual

      • channelstringrequired

        One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

      • conversation_idstring | nullrequired

      • call_idstring | nullrequired

      • form_submission_idstring | nullrequired

      • captured_atstringrequiredISO 8601 timestamp

      • captured_at_estimatedbooleanrequired

      • edited_atstring | nullrequiredISO 8601 timestamp

      • edited_bystring | nullrequired

    • fieldsobject | null

    • sourcestringrequired

      Where the lead came from: web_chat, web_call (a call from a browser), phone_call, sms, whatsapp, form, ad_form (an ad platform's own lead form, such as a Google lead form), scheduling (a booking) or other (such as a lead added by hand).

      One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

    • modestring

      Capture provenance: the chat mode, independent of email classification.

      One of live test preview

    • testboolean

      Effective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See traffic to tell them apart.

    • trafficstring

      Which traffic this belongs to: sandbox (made through a non-live key: a sandbox key, the console's sandbox chat, a sandbox phone or WhatsApp number, or a preview link), test (a live chat or lead one of our rules caught: a test marker, a staging or preview page, a placeholder or own-domain email, or marked as test by hand) or real. Sandbox wins over test. Sandbox and test are both left out of real numbers.

      One of real sandbox test

    • test_reasonstring | null

      Automatic classification, recomputed when saved: reserved_domain (placeholder email), business_domain (your own email domain) or staging_site (a live chat on a staging or preview page). An email reason wins over staging_site.

      One of reserved_domain business_domain staging_site

    • test_overrideboolean | null

      Member override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox.

    • outcomestring | null

      What became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).

      One of open booked lost

    • outcome_valuestring | null

      Booking value as a decimal string.

    • outcome_currencystring | null

    • outcome_atstring | nullISO 8601 timestamp

    • outcome_refstring | null

      The CRM's own id for the booking.

    • customer_idstring | null

      The customer's own id for this person, set with PUT /v1/leads/{id}/outcome.

    • statusstring

      The front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts new. new, contacted and qualified are open; won and lost close it. Separate from outcome, which your CRM reports.

      One of new contacted qualified won lost

    • status_changed_atstring | nullISO 8601 timestamp

    • status_changed_bystring | null

      A user id, or the agent.id an API key named.

    • status_changed_by_namestring | null

    • attributionChatAttribution | null

      Where the lead's chat came from. Returned by the list and detail reads; null when none was recorded.

      One of 2 shapes

      ChatAttribution

      • chat_pagestring

        The path the visitor started chatting on.

      • visitChatAttributionTouch

        This visit's landing.

        20 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

      • firstobject

        The visitor's first-ever landing.

        21 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

        • atstringISO 8601 timestamp

          When the visitor first landed.

      • latest_paidobject

        The visitor's latest ad click within 90 days: a landing with a click id, or with utm_medium cpc, ppc or paid*. Recorded even when the click came inside a visit that began elsewhere, and kept through later direct visits, so it can differ from visit and first.

        21 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

        • atstringISO 8601 timestamp

          When the visitor landed from this ad click.

      Option 2

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • capture_methodstring

      How the lead was first saved: tool (the assistant saved it during the conversation), analysis (read from the conversation afterwards), form (a form submission) manual (added by hand) or scheduling (a direct booking). Later updates never change it.

      One of tool analysis form manual scheduling

    • call_idstring | null

      The call the lead came from, when it came from one.

    • form_submission_idstring | null

      The form submission the lead came from, when it came from one.

    • phone_e164string | null

      phone in E.164 form when it could be read as a number; phone stays as given.

    • phone_sourcestring | null

      caller_id when a call lead's phone is the number the call came from, because the caller never said one. Null means the person gave it.

      One of given caller_id

    • first_contacted_atstring | nullISO 8601 timestamp

      The first contact: the earliest logged contact, or the first status change out of new by a person or key. Null until contacted.

    • last_contacted_atstring | nullISO 8601 timestamp

      The latest contact.

    • next_follow_up_atstring | nullISO 8601 timestamp

      When to contact the lead again. Cleared when the lead is won or lost.

    • time_to_first_contact_secondsinteger | null

      Wall clock from created_at to first_contacted_at, in seconds. Null until contacted.

    • uncontacted_nudged_atstring | nullISO 8601 timestamp

      When lead.uncontacted was recorded for the lead; null when it never was.

    • merged_into_idstring | null

      The kept lead's id when this lead was merged. Merged leads remain readable by id.

    • possible_repeat_ofarray of string

      Detail read only. For a call lead whose caller's number matched earlier open enquiries but who did not say whether this call was about one of them: those leads' ids. Empty otherwise. This historical hint does not perform a merge.

    • possible_duplicatesarray of objectup to 5 items

      Other unmerged leads in this org and project matching a non-null phone_e164, a non-blank trimmed case-insensitive email, or possible_repeat_of. Dismissals on either side are excluded. Newest first, unique by id; phone wins over email, then repeat_caller. Empty when this lead is merged.

      7 attributes
      • idstringrequired

      • namestring | nullrequired

      • emailstring | nullrequired

      • phonestring | nullrequired

      • sourcestringrequired

        One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

      • created_atstringrequiredISO 8601 timestamp

      • reasonstringrequired

        One of phone email repeat_caller

    • merged_fromarray of object

      Leads merged into this lead, oldest first. Origin links stay on these rows, including all earlier merges.

      7 attributes
      • idstringrequired

      • namestring | nullrequired

      • sourcestringrequired

        One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

      • conversation_idstring | nullrequired

      • call_idstring | nullrequired

      • form_submission_idstring | nullrequired

      • created_atstringrequiredISO 8601 timestamp

    • status_historyarray of object

      Every status change, oldest first.

      5 attributes
      • fromstringrequired

        One of new contacted qualified won lost

      • tostringrequired

        One of new contacted qualified won lost

      • atstringrequiredISO 8601 timestamp

      • bystringrequired

      • by_namestring | nullrequired

    • contactsarray of LeadContact

      Detail read only. Live logged contacts, newest first; voided ones are left out.

      8 attributes
      • idstringrequired

        lcon_....

      • channelstringrequired

        One of phone whatsapp email sms in_person other

      • viastringrequired

        A console contact button, Log contact, or the API.

        One of button manual api

      • contacted_atstringrequiredISO 8601 timestamp

      • bystringrequired

        A user id, or the agent.id an API key named.

      • by_namestring | nullrequired

      • status_movedbooleanrequired

        Whether this contact moved the lead from new to contacted.

      • logged_atstringrequiredISO 8601 timestamp

        When the contact was logged: the time of the status change it made. Undo is open for a day after.

    • form_originobject | null

      Detail read only. The form a form or ad_form lead came from; null for other leads. ad holds the ad platform's ids for an ad_form lead (attribution.ad_form in lead.captured), null for a website form.

      4 attributes
      • form_idstring

      • form_namestring

      • channelstring

        One of website google_lead_form

      • adobject | null

    • bookingsarray of object

      Scheduling facts for this lead and mode, up to 200 bookings, oldest first. CRM outcome is unchanged.

      9 attributes
      • idstringrequired

      • uidstringrequired

      • event_namestringrequired

      • statusstringrequired

        One of pending processing confirmed completed rejected expired cancelled rescheduled

      • modestringrequired

        One of live test

      • start_atstringrequiredISO 8601 timestamp

      • end_atstringrequiredISO 8601 timestamp

      • timezonestringrequired

      • rescheduled_to_idstring | nullrequired

    • callbackobject | null

      The callback the visitor asked for in the lead's chat, as on the conversation. Detail read only.

      7 attributes
      • phonestring

      • slot_startstringISO 8601 timestamp

      • notestring

      • requested_atstringISO 8601 timestamp

      • done_atstringISO 8601 timestamp

      • done_bystring

      • done_by_namestring

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Either lead is outside scope, missing or in a different project.
  • 409 already_merged: either lead has already been merged.
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
POST /api/leads/{id}/merge
curl -X POST "https://api.brightshoal.com/api/leads/LEAD_ID/merge" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "duplicate_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
}'
Response 200
{
  "data": {
    "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "email": "ana@example.com",
    "phone": "+14155550123",
    "fact_provenance": {
      "key": {
        "source": "conversation",
        "channel": "web_chat",
        "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "captured_at": "2026-10-28T09:30:00.000Z",
        "captured_at_estimated": true,
        "edited_at": "2026-10-28T09:30:00.000Z",
        "edited_by": "string"
      }
    },
    "fields": {
      "key": "string"
    },
    "source": "web_chat",
    "mode": "live",
    "test": true,
    "traffic": "real",
    "test_reason": "reserved_domain",
    "test_override": true,
    "outcome": "open",
    "outcome_value": "string",
    "outcome_currency": "string",
    "outcome_at": "2026-10-28T09:30:00.000Z",
    "outcome_ref": "string",
    "customer_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "status": "new",
    "status_changed_at": "2026-10-28T09:30:00.000Z",
    "status_changed_by": "string",
    "status_changed_by_name": "string",
    "attribution": {
      "chat_page": "string",
      "visit": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "oppref": "string",
        "ctwa_clid": "string",
        "ad_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "ad_source_type": "string",
        "ad_source_url": "https://example.com/hook",
        "ad_headline": "string",
        "whatsapp_link_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "whatsapp_link_name": "string"
      },
      "first": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "oppref": "string",
        "ctwa_clid": "string",
        "ad_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "ad_source_type": "string",
        "ad_source_url": "https://example.com/hook",
        "ad_headline": "string",
        "whatsapp_link_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "whatsapp_link_name": "string",
        "at": "2026-10-28T09:30:00.000Z"
      },
      "latest_paid": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "oppref": "string",
        "ctwa_clid": "string",
        "ad_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "ad_source_type": "string",
        "ad_source_url": "https://example.com/hook",
        "ad_headline": "string",
        "whatsapp_link_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "whatsapp_link_name": "string",
        "at": "2026-10-28T09:30:00.000Z"
      }
    },
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z",
    "capture_method": "tool",
    "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "phone_e164": "+14155550123",
    "phone_source": "given",
    "first_contacted_at": "2026-10-28T09:30:00.000Z",
    "last_contacted_at": "2026-10-28T09:30:00.000Z",
    "next_follow_up_at": "2026-10-28T09:30:00.000Z",
    "time_to_first_contact_seconds": 1,
    "uncontacted_nudged_at": "2026-10-28T09:30:00.000Z",
    "merged_into_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "possible_repeat_of": [
      "string"
    ],
    "possible_duplicates": [
      {
        "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "name": "Front desk",
        "email": "ana@example.com",
        "phone": "+14155550123",
        "source": "web_chat",
        "created_at": "2026-10-28T09:30:00.000Z",
        "reason": "phone"
      }
    ],
    "merged_from": [
      {
        "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "name": "Front desk",
        "source": "web_chat",
        "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "created_at": "2026-10-28T09:30:00.000Z"
      }
    ],
    "status_history": [
      {
        "from": "new",
        "to": "new",
        "at": "2026-10-28T09:30:00.000Z",
        "by": "string",
        "by_name": "string"
      }
    ],
    "contacts": [
      {
        "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "channel": "phone",
        "via": "button",
        "contacted_at": "2026-10-28T09:30:00.000Z",
        "by": "string",
        "by_name": "string",
        "status_moved": true,
        "logged_at": "2026-10-28T09:30:00.000Z"
      }
    ],
    "form_origin": {
      "form_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "form_name": "string",
      "channel": "website",
      "ad": {}
    },
    "bookings": [
      {
        "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "uid": "string",
        "event_name": "string",
        "status": "pending",
        "mode": "live",
        "start_at": "2026-10-28T09:30:00.000Z",
        "end_at": "2026-10-28T09:30:00.000Z",
        "timezone": "string",
        "rescheduled_to_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
      }
    ],
    "callback": {
      "phone": "+14155550123",
      "slot_start": "2026-10-28T09:30:00.000Z",
      "note": "string",
      "requested_at": "2026-10-28T09:30:00.000Z",
      "done_at": "2026-10-28T09:30:00.000Z",
      "done_by": "string",
      "done_by_name": "string"
    }
  }
}

Dismiss a duplicate suggestion

POST/api/leads/{id}/not-duplicate

Requires a member. Both leads must be visible in the same project and neither may be merged. Records the dismissal on both leads so neither suggests the other. Idempotent. Audited as lead.not_duplicate.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

    Lead id, lead_...

Request body

  • duplicate_idstringrequirednot empty

Returns

200 Dismissed

Response attributes
  • okbooleanrequired

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 409 already_merged: either lead has already been merged.
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
POST /api/leads/{id}/not-duplicate
curl -X POST "https://api.brightshoal.com/api/leads/LEAD_ID/not-duplicate" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "duplicate_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
}'
Response 200
{
  "ok": true
}

Report a lead's outcome

PUT/api/leads/{id}/outcome

Call from your CRM when a lead turns into a booking, is lost, or goes back to open, so chat analytics can count bookings and revenue. Replaces the whole outcome: a field you leave out is cleared, and at defaults to now. customer_id is separate: leaving it out keeps the stored one.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

    Lead id, lead_....

Request body

  • outcomestringrequired

    One of open booked lost

  • valuenumbermin 0

    Booking value, stored to two decimal places.

  • currencystring

    ISO 4217 code in capitals, for example GBP. Required when value is given.

  • atstringISO 8601 timestamp

    When it happened, ISO 8601 with an offset. Default: now.

  • refstringup to 128 characters

    Your CRM's id for the booking.

  • customer_idstringup to 128 characters

    The customer's own id for this person in their CRM (trimmed). Stored on the lead and used to link this person's chats across devices. Left unchanged when omitted.

Returns

200 OK

Response attributes
  • dataLeadrequired

    40 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • assistant_idstring | null

      The assistant that captured the lead; null when no assistant did (a form lead, or one added by hand).

    • conversation_idstring | null

    • namestring | null

    • emailstring | nullemail

    • phonestring | null

    • fact_provenanceobject

      Provenance per field key, including name, email and phone. Legacy values use lead creation time with captured_at_estimated true; edits retain captured_at and set edited_at and edited_by.

      9 attributes
      • sourcestringrequired

        One of conversation channel form manual

      • channelstringrequired

        One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

      • conversation_idstring | nullrequired

      • call_idstring | nullrequired

      • form_submission_idstring | nullrequired

      • captured_atstringrequiredISO 8601 timestamp

      • captured_at_estimatedbooleanrequired

      • edited_atstring | nullrequiredISO 8601 timestamp

      • edited_bystring | nullrequired

    • fieldsobject | null

    • sourcestringrequired

      Where the lead came from: web_chat, web_call (a call from a browser), phone_call, sms, whatsapp, form, ad_form (an ad platform's own lead form, such as a Google lead form), scheduling (a booking) or other (such as a lead added by hand).

      One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

    • modestring

      Capture provenance: the chat mode, independent of email classification.

      One of live test preview

    • testboolean

      Effective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See traffic to tell them apart.

    • trafficstring

      Which traffic this belongs to: sandbox (made through a non-live key: a sandbox key, the console's sandbox chat, a sandbox phone or WhatsApp number, or a preview link), test (a live chat or lead one of our rules caught: a test marker, a staging or preview page, a placeholder or own-domain email, or marked as test by hand) or real. Sandbox wins over test. Sandbox and test are both left out of real numbers.

      One of real sandbox test

    • test_reasonstring | null

      Automatic classification, recomputed when saved: reserved_domain (placeholder email), business_domain (your own email domain) or staging_site (a live chat on a staging or preview page). An email reason wins over staging_site.

      One of reserved_domain business_domain staging_site

    • test_overrideboolean | null

      Member override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox.

    • outcomestring | null

      What became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).

      One of open booked lost

    • outcome_valuestring | null

      Booking value as a decimal string.

    • outcome_currencystring | null

    • outcome_atstring | nullISO 8601 timestamp

    • outcome_refstring | null

      The CRM's own id for the booking.

    • customer_idstring | null

      The customer's own id for this person, set with PUT /v1/leads/{id}/outcome.

    • statusstring

      The front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts new. new, contacted and qualified are open; won and lost close it. Separate from outcome, which your CRM reports.

      One of new contacted qualified won lost

    • status_changed_atstring | nullISO 8601 timestamp

    • status_changed_bystring | null

      A user id, or the agent.id an API key named.

    • status_changed_by_namestring | null

    • attributionChatAttribution | null

      Where the lead's chat came from. Returned by the list and detail reads; null when none was recorded.

      One of 2 shapes

      ChatAttribution

      • chat_pagestring

        The path the visitor started chatting on.

      • visitChatAttributionTouch

        This visit's landing.

        20 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

      • firstobject

        The visitor's first-ever landing.

        21 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

        • atstringISO 8601 timestamp

          When the visitor first landed.

      • latest_paidobject

        The visitor's latest ad click within 90 days: a landing with a click id, or with utm_medium cpc, ppc or paid*. Recorded even when the click came inside a visit that began elsewhere, and kept through later direct visits, so it can differ from visit and first.

        21 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

        • atstringISO 8601 timestamp

          When the visitor landed from this ad click.

      Option 2

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • capture_methodstring

      How the lead was first saved: tool (the assistant saved it during the conversation), analysis (read from the conversation afterwards), form (a form submission) manual (added by hand) or scheduling (a direct booking). Later updates never change it.

      One of tool analysis form manual scheduling

    • call_idstring | null

      The call the lead came from, when it came from one.

    • form_submission_idstring | null

      The form submission the lead came from, when it came from one.

    • phone_e164string | null

      phone in E.164 form when it could be read as a number; phone stays as given.

    • phone_sourcestring | null

      caller_id when a call lead's phone is the number the call came from, because the caller never said one. Null means the person gave it.

      One of given caller_id

    • first_contacted_atstring | nullISO 8601 timestamp

      The first contact: the earliest logged contact, or the first status change out of new by a person or key. Null until contacted.

    • last_contacted_atstring | nullISO 8601 timestamp

      The latest contact.

    • next_follow_up_atstring | nullISO 8601 timestamp

      When to contact the lead again. Cleared when the lead is won or lost.

    • time_to_first_contact_secondsinteger | null

      Wall clock from created_at to first_contacted_at, in seconds. Null until contacted.

    • uncontacted_nudged_atstring | nullISO 8601 timestamp

      When lead.uncontacted was recorded for the lead; null when it never was.

    • merged_into_idstring | null

      The kept lead's id when this lead was merged. Merged leads remain readable by id.

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
PUT /api/leads/{id}/outcome
curl -X PUT "https://api.brightshoal.com/api/leads/LEAD_ID/outcome" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "outcome": "booked",
  "value": 1840,
  "currency": "EUR",
  "ref": "BK-20931"
}'
Response 200
{
  "data": {
    "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "email": "ana@example.com",
    "phone": "+14155550123",
    "fact_provenance": {
      "key": {
        "source": "conversation",
        "channel": "web_chat",
        "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "captured_at": "2026-10-28T09:30:00.000Z",
        "captured_at_estimated": true,
        "edited_at": "2026-10-28T09:30:00.000Z",
        "edited_by": "string"
      }
    },
    "fields": {
      "key": "string"
    },
    "source": "web_chat",
    "mode": "live",
    "test": true,
    "traffic": "real",
    "test_reason": "reserved_domain",
    "test_override": true,
    "outcome": "open",
    "outcome_value": "string",
    "outcome_currency": "string",
    "outcome_at": "2026-10-28T09:30:00.000Z",
    "outcome_ref": "string",
    "customer_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "status": "new",
    "status_changed_at": "2026-10-28T09:30:00.000Z",
    "status_changed_by": "string",
    "status_changed_by_name": "string",
    "attribution": {
      "chat_page": "string",
      "visit": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "oppref": "string",
        "ctwa_clid": "string",
        "ad_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "ad_source_type": "string",
        "ad_source_url": "https://example.com/hook",
        "ad_headline": "string",
        "whatsapp_link_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "whatsapp_link_name": "string"
      },
      "first": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "oppref": "string",
        "ctwa_clid": "string",
        "ad_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "ad_source_type": "string",
        "ad_source_url": "https://example.com/hook",
        "ad_headline": "string",
        "whatsapp_link_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "whatsapp_link_name": "string",
        "at": "2026-10-28T09:30:00.000Z"
      },
      "latest_paid": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "oppref": "string",
        "ctwa_clid": "string",
        "ad_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "ad_source_type": "string",
        "ad_source_url": "https://example.com/hook",
        "ad_headline": "string",
        "whatsapp_link_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "whatsapp_link_name": "string",
        "at": "2026-10-28T09:30:00.000Z"
      }
    },
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z",
    "capture_method": "tool",
    "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "phone_e164": "+14155550123",
    "phone_source": "given",
    "first_contacted_at": "2026-10-28T09:30:00.000Z",
    "last_contacted_at": "2026-10-28T09:30:00.000Z",
    "next_follow_up_at": "2026-10-28T09:30:00.000Z",
    "time_to_first_contact_seconds": 1,
    "uncontacted_nudged_at": "2026-10-28T09:30:00.000Z",
    "merged_into_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}

Set a lead's status

PUT/api/leads/{id}/status

Requires a member. Moves the lead to new, contacted, qualified, won or lost and records who and when, in the lead's status_history and the audit log. Setting the status it already has changes nothing. A change to won or lost clears next_follow_up_at. A change out of new by a person or key counts as the first contact when none was logged. With an API key, name the person in agent.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

    Lead id, lead_....

Request body

  • statusstringrequired

    One of new contacted qualified won lost

  • agentAgentIdentityInput

    3 attributes
    • idstring

    • emailstringemail

    • namestring

Returns

200 OK

Response attributes
  • dataLeadDetailrequired

    48 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • assistant_idstring | null

      The assistant that captured the lead; null when no assistant did (a form lead, or one added by hand).

    • conversation_idstring | null

    • namestring | null

    • emailstring | nullemail

    • phonestring | null

    • fact_provenanceobject

      Provenance per field key, including name, email and phone. Legacy values use lead creation time with captured_at_estimated true; edits retain captured_at and set edited_at and edited_by.

      9 attributes
      • sourcestringrequired

        One of conversation channel form manual

      • channelstringrequired

        One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

      • conversation_idstring | nullrequired

      • call_idstring | nullrequired

      • form_submission_idstring | nullrequired

      • captured_atstringrequiredISO 8601 timestamp

      • captured_at_estimatedbooleanrequired

      • edited_atstring | nullrequiredISO 8601 timestamp

      • edited_bystring | nullrequired

    • fieldsobject | null

    • sourcestringrequired

      Where the lead came from: web_chat, web_call (a call from a browser), phone_call, sms, whatsapp, form, ad_form (an ad platform's own lead form, such as a Google lead form), scheduling (a booking) or other (such as a lead added by hand).

      One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

    • modestring

      Capture provenance: the chat mode, independent of email classification.

      One of live test preview

    • testboolean

      Effective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See traffic to tell them apart.

    • trafficstring

      Which traffic this belongs to: sandbox (made through a non-live key: a sandbox key, the console's sandbox chat, a sandbox phone or WhatsApp number, or a preview link), test (a live chat or lead one of our rules caught: a test marker, a staging or preview page, a placeholder or own-domain email, or marked as test by hand) or real. Sandbox wins over test. Sandbox and test are both left out of real numbers.

      One of real sandbox test

    • test_reasonstring | null

      Automatic classification, recomputed when saved: reserved_domain (placeholder email), business_domain (your own email domain) or staging_site (a live chat on a staging or preview page). An email reason wins over staging_site.

      One of reserved_domain business_domain staging_site

    • test_overrideboolean | null

      Member override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox.

    • outcomestring | null

      What became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).

      One of open booked lost

    • outcome_valuestring | null

      Booking value as a decimal string.

    • outcome_currencystring | null

    • outcome_atstring | nullISO 8601 timestamp

    • outcome_refstring | null

      The CRM's own id for the booking.

    • customer_idstring | null

      The customer's own id for this person, set with PUT /v1/leads/{id}/outcome.

    • statusstring

      The front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts new. new, contacted and qualified are open; won and lost close it. Separate from outcome, which your CRM reports.

      One of new contacted qualified won lost

    • status_changed_atstring | nullISO 8601 timestamp

    • status_changed_bystring | null

      A user id, or the agent.id an API key named.

    • status_changed_by_namestring | null

    • attributionChatAttribution | null

      Where the lead's chat came from. Returned by the list and detail reads; null when none was recorded.

      One of 2 shapes

      ChatAttribution

      • chat_pagestring

        The path the visitor started chatting on.

      • visitChatAttributionTouch

        This visit's landing.

        20 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

      • firstobject

        The visitor's first-ever landing.

        21 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

        • atstringISO 8601 timestamp

          When the visitor first landed.

      • latest_paidobject

        The visitor's latest ad click within 90 days: a landing with a click id, or with utm_medium cpc, ppc or paid*. Recorded even when the click came inside a visit that began elsewhere, and kept through later direct visits, so it can differ from visit and first.

        21 attributes
        • landing_pagestring

          A path starting with /, without query or fragment.

        • referrer_hoststring

        • utm_sourcestring

        • utm_mediumstring

        • utm_campaignstring

        • utm_termstring

        • utm_contentstring

        • gclidstring

        • gbraidstring

        • wbraidstring

        • fbclidstring

        • msclkidstring

        • opprefstring

        • ctwa_clidstring

          WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

        • ad_idstring

          WhatsApp only: the ad or post id (source_id) from Meta's referral.

        • ad_source_typestring

          WhatsApp only: ad or post.

        • ad_source_urlstring

          WhatsApp only: the ad's URL, up to 512 characters.

        • ad_headlinestring

          WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

        • whatsapp_link_idstring

          WhatsApp only: the campaign link (wal_...) the chat started from.

        • whatsapp_link_namestring

          WhatsApp only: that campaign link's name.

        • atstringISO 8601 timestamp

          When the visitor landed from this ad click.

      Option 2

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • capture_methodstring

      How the lead was first saved: tool (the assistant saved it during the conversation), analysis (read from the conversation afterwards), form (a form submission) manual (added by hand) or scheduling (a direct booking). Later updates never change it.

      One of tool analysis form manual scheduling

    • call_idstring | null

      The call the lead came from, when it came from one.

    • form_submission_idstring | null

      The form submission the lead came from, when it came from one.

    • phone_e164string | null

      phone in E.164 form when it could be read as a number; phone stays as given.

    • phone_sourcestring | null

      caller_id when a call lead's phone is the number the call came from, because the caller never said one. Null means the person gave it.

      One of given caller_id

    • first_contacted_atstring | nullISO 8601 timestamp

      The first contact: the earliest logged contact, or the first status change out of new by a person or key. Null until contacted.

    • last_contacted_atstring | nullISO 8601 timestamp

      The latest contact.

    • next_follow_up_atstring | nullISO 8601 timestamp

      When to contact the lead again. Cleared when the lead is won or lost.

    • time_to_first_contact_secondsinteger | null

      Wall clock from created_at to first_contacted_at, in seconds. Null until contacted.

    • uncontacted_nudged_atstring | nullISO 8601 timestamp

      When lead.uncontacted was recorded for the lead; null when it never was.

    • merged_into_idstring | null

      The kept lead's id when this lead was merged. Merged leads remain readable by id.

    • possible_repeat_ofarray of string

      Detail read only. For a call lead whose caller's number matched earlier open enquiries but who did not say whether this call was about one of them: those leads' ids. Empty otherwise. This historical hint does not perform a merge.

    • possible_duplicatesarray of objectup to 5 items

      Other unmerged leads in this org and project matching a non-null phone_e164, a non-blank trimmed case-insensitive email, or possible_repeat_of. Dismissals on either side are excluded. Newest first, unique by id; phone wins over email, then repeat_caller. Empty when this lead is merged.

      7 attributes
      • idstringrequired

      • namestring | nullrequired

      • emailstring | nullrequired

      • phonestring | nullrequired

      • sourcestringrequired

        One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

      • created_atstringrequiredISO 8601 timestamp

      • reasonstringrequired

        One of phone email repeat_caller

    • merged_fromarray of object

      Leads merged into this lead, oldest first. Origin links stay on these rows, including all earlier merges.

      7 attributes
      • idstringrequired

      • namestring | nullrequired

      • sourcestringrequired

        One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

      • conversation_idstring | nullrequired

      • call_idstring | nullrequired

      • form_submission_idstring | nullrequired

      • created_atstringrequiredISO 8601 timestamp

    • status_historyarray of object

      Every status change, oldest first.

      5 attributes
      • fromstringrequired

        One of new contacted qualified won lost

      • tostringrequired

        One of new contacted qualified won lost

      • atstringrequiredISO 8601 timestamp

      • bystringrequired

      • by_namestring | nullrequired

    • contactsarray of LeadContact

      Detail read only. Live logged contacts, newest first; voided ones are left out.

      8 attributes
      • idstringrequired

        lcon_....

      • channelstringrequired

        One of phone whatsapp email sms in_person other

      • viastringrequired

        A console contact button, Log contact, or the API.

        One of button manual api

      • contacted_atstringrequiredISO 8601 timestamp

      • bystringrequired

        A user id, or the agent.id an API key named.

      • by_namestring | nullrequired

      • status_movedbooleanrequired

        Whether this contact moved the lead from new to contacted.

      • logged_atstringrequiredISO 8601 timestamp

        When the contact was logged: the time of the status change it made. Undo is open for a day after.

    • form_originobject | null

      Detail read only. The form a form or ad_form lead came from; null for other leads. ad holds the ad platform's ids for an ad_form lead (attribution.ad_form in lead.captured), null for a website form.

      4 attributes
      • form_idstring

      • form_namestring

      • channelstring

        One of website google_lead_form

      • adobject | null

    • bookingsarray of object

      Scheduling facts for this lead and mode, up to 200 bookings, oldest first. CRM outcome is unchanged.

      9 attributes
      • idstringrequired

      • uidstringrequired

      • event_namestringrequired

      • statusstringrequired

        One of pending processing confirmed completed rejected expired cancelled rescheduled

      • modestringrequired

        One of live test

      • start_atstringrequiredISO 8601 timestamp

      • end_atstringrequiredISO 8601 timestamp

      • timezonestringrequired

      • rescheduled_to_idstring | nullrequired

    • callbackobject | null

      The callback the visitor asked for in the lead's chat, as on the conversation. Detail read only.

      7 attributes
      • phonestring

      • slot_startstringISO 8601 timestamp

      • notestring

      • requested_atstringISO 8601 timestamp

      • done_atstringISO 8601 timestamp

      • done_bystring

      • done_by_namestring

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
PUT /api/leads/{id}/status
curl -X PUT "https://api.brightshoal.com/api/leads/LEAD_ID/status" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "new"
}'
Response 200
{
  "data": {
    "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "email": "ana@example.com",
    "phone": "+14155550123",
    "fact_provenance": {
      "key": {
        "source": "conversation",
        "channel": "web_chat",
        "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "captured_at": "2026-10-28T09:30:00.000Z",
        "captured_at_estimated": true,
        "edited_at": "2026-10-28T09:30:00.000Z",
        "edited_by": "string"
      }
    },
    "fields": {
      "key": "string"
    },
    "source": "web_chat",
    "mode": "live",
    "test": true,
    "traffic": "real",
    "test_reason": "reserved_domain",
    "test_override": true,
    "outcome": "open",
    "outcome_value": "string",
    "outcome_currency": "string",
    "outcome_at": "2026-10-28T09:30:00.000Z",
    "outcome_ref": "string",
    "customer_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "status": "new",
    "status_changed_at": "2026-10-28T09:30:00.000Z",
    "status_changed_by": "string",
    "status_changed_by_name": "string",
    "attribution": {
      "chat_page": "string",
      "visit": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "oppref": "string",
        "ctwa_clid": "string",
        "ad_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "ad_source_type": "string",
        "ad_source_url": "https://example.com/hook",
        "ad_headline": "string",
        "whatsapp_link_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "whatsapp_link_name": "string"
      },
      "first": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "oppref": "string",
        "ctwa_clid": "string",
        "ad_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "ad_source_type": "string",
        "ad_source_url": "https://example.com/hook",
        "ad_headline": "string",
        "whatsapp_link_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "whatsapp_link_name": "string",
        "at": "2026-10-28T09:30:00.000Z"
      },
      "latest_paid": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "oppref": "string",
        "ctwa_clid": "string",
        "ad_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "ad_source_type": "string",
        "ad_source_url": "https://example.com/hook",
        "ad_headline": "string",
        "whatsapp_link_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "whatsapp_link_name": "string",
        "at": "2026-10-28T09:30:00.000Z"
      }
    },
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z",
    "capture_method": "tool",
    "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "phone_e164": "+14155550123",
    "phone_source": "given",
    "first_contacted_at": "2026-10-28T09:30:00.000Z",
    "last_contacted_at": "2026-10-28T09:30:00.000Z",
    "next_follow_up_at": "2026-10-28T09:30:00.000Z",
    "time_to_first_contact_seconds": 1,
    "uncontacted_nudged_at": "2026-10-28T09:30:00.000Z",
    "merged_into_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "possible_repeat_of": [
      "string"
    ],
    "possible_duplicates": [
      {
        "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "name": "Front desk",
        "email": "ana@example.com",
        "phone": "+14155550123",
        "source": "web_chat",
        "created_at": "2026-10-28T09:30:00.000Z",
        "reason": "phone"
      }
    ],
    "merged_from": [
      {
        "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "name": "Front desk",
        "source": "web_chat",
        "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "created_at": "2026-10-28T09:30:00.000Z"
      }
    ],
    "status_history": [
      {
        "from": "new",
        "to": "new",
        "at": "2026-10-28T09:30:00.000Z",
        "by": "string",
        "by_name": "string"
      }
    ],
    "contacts": [
      {
        "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "channel": "phone",
        "via": "button",
        "contacted_at": "2026-10-28T09:30:00.000Z",
        "by": "string",
        "by_name": "string",
        "status_moved": true,
        "logged_at": "2026-10-28T09:30:00.000Z"
      }
    ],
    "form_origin": {
      "form_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "form_name": "string",
      "channel": "website",
      "ad": {}
    },
    "bookings": [
      {
        "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "uid": "string",
        "event_name": "string",
        "status": "pending",
        "mode": "live",
        "start_at": "2026-10-28T09:30:00.000Z",
        "end_at": "2026-10-28T09:30:00.000Z",
        "timezone": "string",
        "rescheduled_to_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
      }
    ],
    "callback": {
      "phone": "+14155550123",
      "slot_start": "2026-10-28T09:30:00.000Z",
      "note": "string",
      "requested_at": "2026-10-28T09:30:00.000Z",
      "done_at": "2026-10-28T09:30:00.000Z",
      "done_by": "string",
      "done_by_name": "string"
    }
  }
}

Count leads that need attention

GET/api/leads/attention

How many live leads are uncontacted, overdue and due today (the attention buckets of the list). total counts a lead in two buckets once.

Secret API key. How it works

Query parameters

  • project_idstring

    Only this project's leads.

  • tzstring

    IANA time zone for the days. Default: the project's timezone when you see one project, else UTC.

Returns

200 OK

Response attributes
  • dataLeadAttentionrequired

    5 attributes
    • uncontactedintegerrequired

    • overdueintegerrequired

    • due_todayintegerrequired

    • lateintegerrequired

      Leads uncontacted or overdue, each counted once: the nav count.

    • totalintegerrequired

      Leads in any bucket, each counted once.

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
GET /api/leads/attention
curl "https://api.brightshoal.com/api/leads/attention" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "uncontacted": 1,
    "overdue": 1,
    "due_today": 1,
    "late": 1,
    "total": 1
  }
}

Get lead reminder settings

GET/api/leads/settings

When a new lead counts as waiting too long (lead.uncontacted). A project with no settings has the defaults.

Secret API key. How it works

Query parameters

  • project_idstring

    The project. Required with an org-wide key; a project key uses its own.

Returns

200 OK

Response attributes
  • dataLeadsSettingsrequired

    3 attributes
    • project_idstringrequired

    • uncontacted_after_minutesinteger | nullrequired15 to 1440

      Minutes a new lead may wait before lead.uncontacted; null turns the nudge off. Default 60.

    • counts_contact_hoursbooleanrequiredread-only

      True when the project has contact hours and a timezone: the wait counts only those hours.

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 404 Not found, or outside what the key can see
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
GET /api/leads/settings
curl "https://api.brightshoal.com/api/leads/settings" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "uncontacted_after_minutes": 15,
    "counts_contact_hours": true
  }
}

Set lead reminder settings

PUT/api/leads/settings

Requires an admin. uncontacted_after_minutes from 15 to 1,440, or null to stop lead.uncontacted for the project. The change is audited.

Secret API key, not a viewer key. How it works

Query parameters

  • project_idstring

    The project. Required with an org-wide key; a project key uses its own.

Request body

  • uncontacted_after_minutesinteger | nullrequired15 to 1440

Returns

200 OK

Response attributes
  • dataLeadsSettingsrequired

    3 attributes
    • project_idstringrequired

    • uncontacted_after_minutesinteger | nullrequired15 to 1440

      Minutes a new lead may wait before lead.uncontacted; null turns the nudge off. Default 60.

    • counts_contact_hoursbooleanrequiredread-only

      True when the project has contact hours and a timezone: the wait counts only those hours.

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
PUT /api/leads/settings
curl -X PUT "https://api.brightshoal.com/api/leads/settings" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "uncontacted_after_minutes": 15
}'
Response 200
{
  "data": {
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "uncontacted_after_minutes": 15,
    "counts_contact_hours": true
  }
}

Speed to lead

GET/api/leads/speed

How long leads waited for a first contact, wall clock. Counts live leads that are not test and were not added by hand, created between from and to (default the last 30 days). The median and 90th percentile cover contacted leads only; uncontacted says how many never were.

Secret API key. How it works

Query parameters

  • project_idstring

    Only this project's leads.

  • fromstringISO 8601 timestamp

  • tostringISO 8601 timestamp

  • channelstring

    Only these channels (the lead's source), comma separated.

Returns

200 OK

Response attributes
  • dataLeadSpeedrequired

    10 attributes
    • leadsintegerrequired

      Counted leads: live, not test, not added by hand, created in the window.

    • contactedintegerrequired

    • uncontactedintegerrequired

      Counted leads never contacted. Read it beside the median.

    • median_secondsinteger | nullrequired

      Median time to first contact, contacted leads only.

    • p90_secondsinteger | nullrequired

    • within_5mintegerrequired

    • within_1hintegerrequired

    • within_24hintegerrequired

    • excluded_manualintegerrequired

      Leads added by hand in the window (live, not test): left out of every count above.

    • by_channelarray of objectrequired

      4 attributes
      • channelstringrequired

        One of web_chat web_call phone_call sms whatsapp form ad_form scheduling other

      • leadsintegerrequired

      • contactedintegerrequired

      • median_secondsinteger | nullrequired

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
GET /api/leads/speed
curl "https://api.brightshoal.com/api/leads/speed" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "leads": 1,
    "contacted": 1,
    "uncontacted": 1,
    "median_seconds": 1,
    "p90_seconds": 1,
    "within_5m": 1,
    "within_1h": 1,
    "within_24h": 1,
    "excluded_manual": 1,
    "by_channel": [
      {
        "channel": "web_chat",
        "leads": 1,
        "contacted": 1,
        "median_seconds": 1
      }
    ]
  }
}