API reference
Leads
The details an assistant captured from a visitor, and the outcome you report back once your team follows up.
- GET
/api/leadsList leads - POST
/api/leadsAdd a lead by hand - GET
/api/leads/{id}Get a lead - PATCH
/api/leads/{id}Set a lead's test override - POST
/api/leads/{id}/contactsLog a contact - POST
/api/leads/{id}/contacts/{contactId}/voidUndo a contact - PATCH
/api/leads/{id}/facts/{field}Edit one captured lead fact - PUT
/api/leads/{id}/follow-upSet a lead's reminder - POST
/api/leads/{id}/mergeMerge a duplicate lead - POST
/api/leads/{id}/not-duplicateDismiss a duplicate suggestion - PUT
/api/leads/{id}/outcomeReport a lead's outcome - PUT
/api/leads/{id}/statusSet a lead's status - GET
/api/leads/attentionCount leads that need attention - GET
/api/leads/settingsGet lead reminder settings - PUT
/api/leads/settingsSet lead reminder settings - GET
/api/leads/speedSpeed to lead
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_idstringOnly this project's leads.
assistant_idstringOnly leads captured by this assistant, intersected with the caller's org and project scope. Unknown or inaccessible assistants return an empty page.
form_idstringOnly leads captured by this form, intersected with the caller's project scope. Unknown or inaccessible forms return an empty page.
fromstringISO 8601 timestampCreated at or after this time.
tostringISO 8601 timestampCreated at or before this time.
modestringLive 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
livetestpreviewallDefault
"live"trafficstringComma-separated subset of real, sandbox and test: only leads of those kinds. When given it replaces the default view (and
include_test); an explicitmodestill narrows. Absent: the default view, unchanged.channelstringOnly 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.sourcestringAnother name for
channel, with the same values and comma separated lists; read whenchannelis absent.statusstringOnly leads with this status:
new,contacted,qualified,wonorlost. Several, comma separated, list any of them.attentionstringNeeds attention, oldest first:
uncontacted(statusnewand never contacted, bycreated_at),overdue(open, withnext_follow_up_atbefore the start of today, by that date),due_today(open, withnext_follow_up_attoday, by that date) orany(all three, each lead by the earlier of its keys). Days are read intz. The other filters still apply.One of
uncontactedoverduedue_todayanytzstringIANA time zone for
attention's days. Default: the project'stimezonewhen you see one project, else UTC. An unknown zone is 400.qstringSearch: 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 43210finds+91 98765-43210.cursorstringOpaque next_cursor from the previous page. Legacy ISO timestamp cursors are also accepted.
limitinteger1 to 200Page size.
Default
50
Returns
200 OK
Response attributes
dataarray of Leadrequired40 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequiredassistant_idstring | nullThe assistant that captured the lead; null when no assistant did (a form lead, or one added by hand).
conversation_idstring | nullnamestring | nullemailstring | nullemailphonestring | nullfact_provenanceobjectProvenance 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
sourcestringrequiredOne of
conversationchannelformmanualchannelstringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingotherconversation_idstring | nullrequiredcall_idstring | nullrequiredform_submission_idstring | nullrequiredcaptured_atstringrequiredISO 8601 timestampcaptured_at_estimatedbooleanrequirededited_atstring | nullrequiredISO 8601 timestampedited_bystring | nullrequired
fieldsobject | nullsourcestringrequiredWhere 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) orother(such as a lead added by hand).One of
web_chatweb_callphone_callsmswhatsappformad_formschedulingothermodestringCapture provenance: the chat mode, independent of email classification.
One of
livetestpreviewtestbooleanEffective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See
trafficto tell them apart.trafficstringWhich 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) orreal. Sandbox wins over test. Sandbox and test are both left out of real numbers.One of
realsandboxtesttest_reasonstring | nullAutomatic classification, recomputed when saved:
reserved_domain(placeholder email),business_domain(your own email domain) orstaging_site(a live chat on a staging or preview page). An email reason wins over staging_site.One of
reserved_domainbusiness_domainstaging_sitetest_overrideboolean | nullMember override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox.
outcomestring | nullWhat became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).
One of
openbookedlostoutcome_valuestring | nullBooking value as a decimal string.
outcome_currencystring | nulloutcome_atstring | nullISO 8601 timestampoutcome_refstring | nullThe CRM's own id for the booking.
customer_idstring | nullThe customer's own id for this person, set with PUT /v1/leads/{id}/outcome.
statusstringThe front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts
new.new,contactedandqualifiedare open;wonandlostclose it. Separate fromoutcome, which your CRM reports.One of
newcontactedqualifiedwonloststatus_changed_atstring | nullISO 8601 timestampstatus_changed_bystring | nullA user id, or the
agent.idan API key named.status_changed_by_namestring | nullattributionChatAttribution | nullWhere the lead's chat came from. Returned by the list and detail reads; null when none was recorded.
One of 2 shapes
ChatAttribution
chat_pagestringThe path the visitor started chatting on.
visitChatAttributionTouchThis visit's landing.
20 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
firstobjectThe visitor's first-ever landing.
21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor first landed.
latest_paidobjectThe visitor's latest ad click within 90 days: a landing with a click id, or with
utm_mediumcpc, 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 fromvisitandfirst.21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor landed from this ad click.
Option 2
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestampcapture_methodstringHow 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) orscheduling(a direct booking). Later updates never change it.One of
toolanalysisformmanualschedulingcall_idstring | nullThe call the lead came from, when it came from one.
form_submission_idstring | nullThe form submission the lead came from, when it came from one.
phone_e164string | nullphonein E.164 form when it could be read as a number;phonestays as given.phone_sourcestring | nullcaller_idwhen a call lead'sphoneis the number the call came from, because the caller never said one. Null means the person gave it.One of
givencaller_idfirst_contacted_atstring | nullISO 8601 timestampThe first contact: the earliest logged contact, or the first status change out of
newby a person or key. Null until contacted.last_contacted_atstring | nullISO 8601 timestampThe latest contact.
next_follow_up_atstring | nullISO 8601 timestampWhen to contact the lead again. Cleared when the lead is won or lost.
time_to_first_contact_secondsinteger | nullWall clock from
created_attofirst_contacted_at, in seconds. Null until contacted.uncontacted_nudged_atstring | nullISO 8601 timestampWhen
lead.uncontactedwas recorded for the lead; null when it never was.merged_into_idstring | nullThe kept lead's id when this lead was merged. Merged leads remain readable by id.
next_cursorstring | nullrequiredOpaque cursor for the next page.
has_morebooleanrequired
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. 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).
curl "https://api.brightshoal.com/api/leads" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"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_idstringThe project the lead belongs to. Required with an org-wide key; a project key uses its own.
call_idstringnot emptySave 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 emptySave a conversation as a lead, with the same scope and duplicate checks as call_id. Mutually exclusive with call_id.
namestringup to 200 charactersemailstringemailup to 320 charactersphonestringup to 64 charactersAs given; include the country code for
phone_e164.fieldsobjectAny other details, keyed by field key.
sourcestringDefaults to the linked origin channel, or other when unlinked. These are capture channels; search acquisition is not a recorded source value.
One of
web_chatweb_callphone_callsmswhatsappformad_formschedulingothertestbooleanMark it as test (or not) by hand; absent follows the automatic rules.
Returns
201 Created
Response attributes
dataLeadDetailrequired48 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequiredassistant_idstring | nullThe assistant that captured the lead; null when no assistant did (a form lead, or one added by hand).
conversation_idstring | nullnamestring | nullemailstring | nullemailphonestring | nullfact_provenanceobjectProvenance 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
sourcestringrequiredOne of
conversationchannelformmanualchannelstringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingotherconversation_idstring | nullrequiredcall_idstring | nullrequiredform_submission_idstring | nullrequiredcaptured_atstringrequiredISO 8601 timestampcaptured_at_estimatedbooleanrequirededited_atstring | nullrequiredISO 8601 timestampedited_bystring | nullrequired
fieldsobject | nullsourcestringrequiredWhere 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) orother(such as a lead added by hand).One of
web_chatweb_callphone_callsmswhatsappformad_formschedulingothermodestringCapture provenance: the chat mode, independent of email classification.
One of
livetestpreviewtestbooleanEffective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See
trafficto tell them apart.trafficstringWhich 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) orreal. Sandbox wins over test. Sandbox and test are both left out of real numbers.One of
realsandboxtesttest_reasonstring | nullAutomatic classification, recomputed when saved:
reserved_domain(placeholder email),business_domain(your own email domain) orstaging_site(a live chat on a staging or preview page). An email reason wins over staging_site.One of
reserved_domainbusiness_domainstaging_sitetest_overrideboolean | nullMember override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox.
outcomestring | nullWhat became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).
One of
openbookedlostoutcome_valuestring | nullBooking value as a decimal string.
outcome_currencystring | nulloutcome_atstring | nullISO 8601 timestampoutcome_refstring | nullThe CRM's own id for the booking.
customer_idstring | nullThe customer's own id for this person, set with PUT /v1/leads/{id}/outcome.
statusstringThe front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts
new.new,contactedandqualifiedare open;wonandlostclose it. Separate fromoutcome, which your CRM reports.One of
newcontactedqualifiedwonloststatus_changed_atstring | nullISO 8601 timestampstatus_changed_bystring | nullA user id, or the
agent.idan API key named.status_changed_by_namestring | nullattributionChatAttribution | nullWhere the lead's chat came from. Returned by the list and detail reads; null when none was recorded.
One of 2 shapes
ChatAttribution
chat_pagestringThe path the visitor started chatting on.
visitChatAttributionTouchThis visit's landing.
20 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
firstobjectThe visitor's first-ever landing.
21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor first landed.
latest_paidobjectThe visitor's latest ad click within 90 days: a landing with a click id, or with
utm_mediumcpc, 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 fromvisitandfirst.21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor landed from this ad click.
Option 2
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestampcapture_methodstringHow 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) orscheduling(a direct booking). Later updates never change it.One of
toolanalysisformmanualschedulingcall_idstring | nullThe call the lead came from, when it came from one.
form_submission_idstring | nullThe form submission the lead came from, when it came from one.
phone_e164string | nullphonein E.164 form when it could be read as a number;phonestays as given.phone_sourcestring | nullcaller_idwhen a call lead'sphoneis the number the call came from, because the caller never said one. Null means the person gave it.One of
givencaller_idfirst_contacted_atstring | nullISO 8601 timestampThe first contact: the earliest logged contact, or the first status change out of
newby a person or key. Null until contacted.last_contacted_atstring | nullISO 8601 timestampThe latest contact.
next_follow_up_atstring | nullISO 8601 timestampWhen to contact the lead again. Cleared when the lead is won or lost.
time_to_first_contact_secondsinteger | nullWall clock from
created_attofirst_contacted_at, in seconds. Null until contacted.uncontacted_nudged_atstring | nullISO 8601 timestampWhen
lead.uncontactedwas recorded for the lead; null when it never was.merged_into_idstring | nullThe kept lead's id when this lead was merged. Merged leads remain readable by id.
possible_repeat_ofarray of stringDetail 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 itemsOther 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
idstringrequirednamestring | nullrequiredemailstring | nullrequiredphonestring | nullrequiredsourcestringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingothercreated_atstringrequiredISO 8601 timestampreasonstringrequiredOne of
phoneemailrepeat_caller
merged_fromarray of objectLeads merged into this lead, oldest first. Origin links stay on these rows, including all earlier merges.
7 attributes
idstringrequirednamestring | nullrequiredsourcestringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingotherconversation_idstring | nullrequiredcall_idstring | nullrequiredform_submission_idstring | nullrequiredcreated_atstringrequiredISO 8601 timestamp
status_historyarray of objectEvery status change, oldest first.
5 attributes
fromstringrequiredOne of
newcontactedqualifiedwonlosttostringrequiredOne of
newcontactedqualifiedwonlostatstringrequiredISO 8601 timestampbystringrequiredby_namestring | nullrequired
contactsarray of LeadContactDetail read only. Live logged contacts, newest first; voided ones are left out.
8 attributes
idstringrequiredlcon_....channelstringrequiredOne of
phonewhatsappemailsmsin_personotherviastringrequiredA console contact button, Log contact, or the API.
One of
buttonmanualapicontacted_atstringrequiredISO 8601 timestampbystringrequiredA user id, or the
agent.idan API key named.by_namestring | nullrequiredstatus_movedbooleanrequiredWhether this contact moved the lead from
newtocontacted.logged_atstringrequiredISO 8601 timestampWhen the contact was logged: the time of the status change it made. Undo is open for a day after.
form_originobject | nullDetail read only. The form a form or
ad_formlead came from; null for other leads.adholds the ad platform's ids for anad_formlead (attribution.ad_forminlead.captured), null for a website form.4 attributes
form_idstringform_namestringchannelstringOne of
websitegoogle_lead_formadobject | null
bookingsarray of objectScheduling facts for this lead and mode, up to 200 bookings, oldest first. CRM outcome is unchanged.
9 attributes
idstringrequireduidstringrequiredevent_namestringrequiredstatusstringrequiredOne of
pendingprocessingconfirmedcompletedrejectedexpiredcancelledrescheduledmodestringrequiredOne of
liveteststart_atstringrequiredISO 8601 timestampend_atstringrequiredISO 8601 timestamptimezonestringrequiredrescheduled_to_idstring | nullrequired
callbackobject | nullThe callback the visitor asked for in the lead's chat, as on the conversation. Detail read only.
7 attributes
phonestringslot_startstringISO 8601 timestampnotestringrequested_atstringISO 8601 timestampdone_atstringISO 8601 timestampdone_bystringdone_by_namestring
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen 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). WaitRetry-Afterseconds. 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).
curl -X POST "https://api.brightshoal.com/api/leads" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d 'null'{
"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
idstringrequiredLead id,
lead_....
Returns
200 OK
Response attributes
dataLeadDetailrequired48 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequiredassistant_idstring | nullThe assistant that captured the lead; null when no assistant did (a form lead, or one added by hand).
conversation_idstring | nullnamestring | nullemailstring | nullemailphonestring | nullfact_provenanceobjectProvenance 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
sourcestringrequiredOne of
conversationchannelformmanualchannelstringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingotherconversation_idstring | nullrequiredcall_idstring | nullrequiredform_submission_idstring | nullrequiredcaptured_atstringrequiredISO 8601 timestampcaptured_at_estimatedbooleanrequirededited_atstring | nullrequiredISO 8601 timestampedited_bystring | nullrequired
fieldsobject | nullsourcestringrequiredWhere 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) orother(such as a lead added by hand).One of
web_chatweb_callphone_callsmswhatsappformad_formschedulingothermodestringCapture provenance: the chat mode, independent of email classification.
One of
livetestpreviewtestbooleanEffective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See
trafficto tell them apart.trafficstringWhich 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) orreal. Sandbox wins over test. Sandbox and test are both left out of real numbers.One of
realsandboxtesttest_reasonstring | nullAutomatic classification, recomputed when saved:
reserved_domain(placeholder email),business_domain(your own email domain) orstaging_site(a live chat on a staging or preview page). An email reason wins over staging_site.One of
reserved_domainbusiness_domainstaging_sitetest_overrideboolean | nullMember override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox.
outcomestring | nullWhat became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).
One of
openbookedlostoutcome_valuestring | nullBooking value as a decimal string.
outcome_currencystring | nulloutcome_atstring | nullISO 8601 timestampoutcome_refstring | nullThe CRM's own id for the booking.
customer_idstring | nullThe customer's own id for this person, set with PUT /v1/leads/{id}/outcome.
statusstringThe front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts
new.new,contactedandqualifiedare open;wonandlostclose it. Separate fromoutcome, which your CRM reports.One of
newcontactedqualifiedwonloststatus_changed_atstring | nullISO 8601 timestampstatus_changed_bystring | nullA user id, or the
agent.idan API key named.status_changed_by_namestring | nullattributionChatAttribution | nullWhere the lead's chat came from. Returned by the list and detail reads; null when none was recorded.
One of 2 shapes
ChatAttribution
chat_pagestringThe path the visitor started chatting on.
visitChatAttributionTouchThis visit's landing.
20 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
firstobjectThe visitor's first-ever landing.
21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor first landed.
latest_paidobjectThe visitor's latest ad click within 90 days: a landing with a click id, or with
utm_mediumcpc, 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 fromvisitandfirst.21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor landed from this ad click.
Option 2
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestampcapture_methodstringHow 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) orscheduling(a direct booking). Later updates never change it.One of
toolanalysisformmanualschedulingcall_idstring | nullThe call the lead came from, when it came from one.
form_submission_idstring | nullThe form submission the lead came from, when it came from one.
phone_e164string | nullphonein E.164 form when it could be read as a number;phonestays as given.phone_sourcestring | nullcaller_idwhen a call lead'sphoneis the number the call came from, because the caller never said one. Null means the person gave it.One of
givencaller_idfirst_contacted_atstring | nullISO 8601 timestampThe first contact: the earliest logged contact, or the first status change out of
newby a person or key. Null until contacted.last_contacted_atstring | nullISO 8601 timestampThe latest contact.
next_follow_up_atstring | nullISO 8601 timestampWhen to contact the lead again. Cleared when the lead is won or lost.
time_to_first_contact_secondsinteger | nullWall clock from
created_attofirst_contacted_at, in seconds. Null until contacted.uncontacted_nudged_atstring | nullISO 8601 timestampWhen
lead.uncontactedwas recorded for the lead; null when it never was.merged_into_idstring | nullThe kept lead's id when this lead was merged. Merged leads remain readable by id.
possible_repeat_ofarray of stringDetail 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 itemsOther 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
idstringrequirednamestring | nullrequiredemailstring | nullrequiredphonestring | nullrequiredsourcestringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingothercreated_atstringrequiredISO 8601 timestampreasonstringrequiredOne of
phoneemailrepeat_caller
merged_fromarray of objectLeads merged into this lead, oldest first. Origin links stay on these rows, including all earlier merges.
7 attributes
idstringrequirednamestring | nullrequiredsourcestringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingotherconversation_idstring | nullrequiredcall_idstring | nullrequiredform_submission_idstring | nullrequiredcreated_atstringrequiredISO 8601 timestamp
status_historyarray of objectEvery status change, oldest first.
5 attributes
fromstringrequiredOne of
newcontactedqualifiedwonlosttostringrequiredOne of
newcontactedqualifiedwonlostatstringrequiredISO 8601 timestampbystringrequiredby_namestring | nullrequired
contactsarray of LeadContactDetail read only. Live logged contacts, newest first; voided ones are left out.
8 attributes
idstringrequiredlcon_....channelstringrequiredOne of
phonewhatsappemailsmsin_personotherviastringrequiredA console contact button, Log contact, or the API.
One of
buttonmanualapicontacted_atstringrequiredISO 8601 timestampbystringrequiredA user id, or the
agent.idan API key named.by_namestring | nullrequiredstatus_movedbooleanrequiredWhether this contact moved the lead from
newtocontacted.logged_atstringrequiredISO 8601 timestampWhen the contact was logged: the time of the status change it made. Undo is open for a day after.
form_originobject | nullDetail read only. The form a form or
ad_formlead came from; null for other leads.adholds the ad platform's ids for anad_formlead (attribution.ad_forminlead.captured), null for a website form.4 attributes
form_idstringform_namestringchannelstringOne of
websitegoogle_lead_formadobject | null
bookingsarray of objectScheduling facts for this lead and mode, up to 200 bookings, oldest first. CRM outcome is unchanged.
9 attributes
idstringrequireduidstringrequiredevent_namestringrequiredstatusstringrequiredOne of
pendingprocessingconfirmedcompletedrejectedexpiredcancelledrescheduledmodestringrequiredOne of
liveteststart_atstringrequiredISO 8601 timestampend_atstringrequiredISO 8601 timestamptimezonestringrequiredrescheduled_to_idstring | nullrequired
callbackobject | nullThe callback the visitor asked for in the lead's chat, as on the conversation. Detail read only.
7 attributes
phonestringslot_startstringISO 8601 timestampnotestringrequested_atstringISO 8601 timestampdone_atstringISO 8601 timestampdone_bystringdone_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). WaitRetry-Afterseconds. 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).
curl "https://api.brightshoal.com/api/leads/LEAD_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"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
idstringrequiredLead id,
lead_....
Request body
testboolean | nullrequired
Returns
200 OK
Response attributes
dataLeadrequired40 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequiredassistant_idstring | nullThe assistant that captured the lead; null when no assistant did (a form lead, or one added by hand).
conversation_idstring | nullnamestring | nullemailstring | nullemailphonestring | nullfact_provenanceobjectProvenance 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
sourcestringrequiredOne of
conversationchannelformmanualchannelstringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingotherconversation_idstring | nullrequiredcall_idstring | nullrequiredform_submission_idstring | nullrequiredcaptured_atstringrequiredISO 8601 timestampcaptured_at_estimatedbooleanrequirededited_atstring | nullrequiredISO 8601 timestampedited_bystring | nullrequired
fieldsobject | nullsourcestringrequiredWhere 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) orother(such as a lead added by hand).One of
web_chatweb_callphone_callsmswhatsappformad_formschedulingothermodestringCapture provenance: the chat mode, independent of email classification.
One of
livetestpreviewtestbooleanEffective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See
trafficto tell them apart.trafficstringWhich 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) orreal. Sandbox wins over test. Sandbox and test are both left out of real numbers.One of
realsandboxtesttest_reasonstring | nullAutomatic classification, recomputed when saved:
reserved_domain(placeholder email),business_domain(your own email domain) orstaging_site(a live chat on a staging or preview page). An email reason wins over staging_site.One of
reserved_domainbusiness_domainstaging_sitetest_overrideboolean | nullMember override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox.
outcomestring | nullWhat became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).
One of
openbookedlostoutcome_valuestring | nullBooking value as a decimal string.
outcome_currencystring | nulloutcome_atstring | nullISO 8601 timestampoutcome_refstring | nullThe CRM's own id for the booking.
customer_idstring | nullThe customer's own id for this person, set with PUT /v1/leads/{id}/outcome.
statusstringThe front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts
new.new,contactedandqualifiedare open;wonandlostclose it. Separate fromoutcome, which your CRM reports.One of
newcontactedqualifiedwonloststatus_changed_atstring | nullISO 8601 timestampstatus_changed_bystring | nullA user id, or the
agent.idan API key named.status_changed_by_namestring | nullattributionChatAttribution | nullWhere the lead's chat came from. Returned by the list and detail reads; null when none was recorded.
One of 2 shapes
ChatAttribution
chat_pagestringThe path the visitor started chatting on.
visitChatAttributionTouchThis visit's landing.
20 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
firstobjectThe visitor's first-ever landing.
21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor first landed.
latest_paidobjectThe visitor's latest ad click within 90 days: a landing with a click id, or with
utm_mediumcpc, 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 fromvisitandfirst.21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor landed from this ad click.
Option 2
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestampcapture_methodstringHow 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) orscheduling(a direct booking). Later updates never change it.One of
toolanalysisformmanualschedulingcall_idstring | nullThe call the lead came from, when it came from one.
form_submission_idstring | nullThe form submission the lead came from, when it came from one.
phone_e164string | nullphonein E.164 form when it could be read as a number;phonestays as given.phone_sourcestring | nullcaller_idwhen a call lead'sphoneis the number the call came from, because the caller never said one. Null means the person gave it.One of
givencaller_idfirst_contacted_atstring | nullISO 8601 timestampThe first contact: the earliest logged contact, or the first status change out of
newby a person or key. Null until contacted.last_contacted_atstring | nullISO 8601 timestampThe latest contact.
next_follow_up_atstring | nullISO 8601 timestampWhen to contact the lead again. Cleared when the lead is won or lost.
time_to_first_contact_secondsinteger | nullWall clock from
created_attofirst_contacted_at, in seconds. Null until contacted.uncontacted_nudged_atstring | nullISO 8601 timestampWhen
lead.uncontactedwas recorded for the lead; null when it never was.merged_into_idstring | nullThe 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 inissueswhen 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). WaitRetry-Afterseconds. 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).
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
}'{
"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
idstringrequiredLead id,
lead_....
Request body
channelstringrequiredOne of
phonewhatsappemailsmsin_personotherviastringThe console's: a contact button or Log contact. Always
apifor an API key.One of
buttonmanualcontacted_atstringISO 8601 timestampWhen it happened. Default now; not in the future, not before the lead, at most 30 days back.
next_follow_up_atstring | nullISO 8601 timestampWhen 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 | AgentIdentityInputWith an API key: who made the contact, as
PUT /statustakes it, or just a name.One of 2 shapes
Option 1
AgentIdentityInput
idstringemailstringemailnamestring
Returns
201 Logged
Response attributes
dataobjectrequired2 attributes
contactLeadContactrequired8 attributes
idstringrequiredlcon_....channelstringrequiredOne of
phonewhatsappemailsmsin_personotherviastringrequiredA console contact button, Log contact, or the API.
One of
buttonmanualapicontacted_atstringrequiredISO 8601 timestampbystringrequiredA user id, or the
agent.idan API key named.by_namestring | nullrequiredstatus_movedbooleanrequiredWhether this contact moved the lead from
newtocontacted.logged_atstringrequiredISO 8601 timestampWhen the contact was logged: the time of the status change it made. Undo is open for a day after.
leadLeadDetailrequired48 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequiredassistant_idstring | nullThe assistant that captured the lead; null when no assistant did (a form lead, or one added by hand).
conversation_idstring | nullnamestring | nullemailstring | nullemailphonestring | nullfact_provenanceobjectProvenance 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
sourcestringrequiredOne of
conversationchannelformmanualchannelstringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingotherconversation_idstring | nullrequiredcall_idstring | nullrequiredform_submission_idstring | nullrequiredcaptured_atstringrequiredISO 8601 timestampcaptured_at_estimatedbooleanrequirededited_atstring | nullrequiredISO 8601 timestampedited_bystring | nullrequired
fieldsobject | nullsourcestringrequiredWhere 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) orother(such as a lead added by hand).One of
web_chatweb_callphone_callsmswhatsappformad_formschedulingothermodestringCapture provenance: the chat mode, independent of email classification.
One of
livetestpreviewtestbooleanEffective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See
trafficto tell them apart.trafficstringWhich 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) orreal. Sandbox wins over test. Sandbox and test are both left out of real numbers.One of
realsandboxtesttest_reasonstring | nullAutomatic classification, recomputed when saved:
reserved_domain(placeholder email),business_domain(your own email domain) orstaging_site(a live chat on a staging or preview page). An email reason wins over staging_site.One of
reserved_domainbusiness_domainstaging_sitetest_overrideboolean | nullMember override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox.
outcomestring | nullWhat became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).
One of
openbookedlostoutcome_valuestring | nullBooking value as a decimal string.
outcome_currencystring | nulloutcome_atstring | nullISO 8601 timestampoutcome_refstring | nullThe CRM's own id for the booking.
customer_idstring | nullThe customer's own id for this person, set with PUT /v1/leads/{id}/outcome.
statusstringThe front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts
new.new,contactedandqualifiedare open;wonandlostclose it. Separate fromoutcome, which your CRM reports.One of
newcontactedqualifiedwonloststatus_changed_atstring | nullISO 8601 timestampstatus_changed_bystring | nullA user id, or the
agent.idan API key named.status_changed_by_namestring | nullattributionChatAttribution | nullWhere the lead's chat came from. Returned by the list and detail reads; null when none was recorded.
One of 2 shapes
ChatAttribution
chat_pagestringThe path the visitor started chatting on.
visitChatAttributionTouchThis visit's landing.
20 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
firstobjectThe visitor's first-ever landing.
21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor first landed.
latest_paidobjectThe visitor's latest ad click within 90 days: a landing with a click id, or with
utm_mediumcpc, 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 fromvisitandfirst.21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor landed from this ad click.
Option 2
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestampcapture_methodstringHow 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) orscheduling(a direct booking). Later updates never change it.One of
toolanalysisformmanualschedulingcall_idstring | nullThe call the lead came from, when it came from one.
form_submission_idstring | nullThe form submission the lead came from, when it came from one.
phone_e164string | nullphonein E.164 form when it could be read as a number;phonestays as given.phone_sourcestring | nullcaller_idwhen a call lead'sphoneis the number the call came from, because the caller never said one. Null means the person gave it.One of
givencaller_idfirst_contacted_atstring | nullISO 8601 timestampThe first contact: the earliest logged contact, or the first status change out of
newby a person or key. Null until contacted.last_contacted_atstring | nullISO 8601 timestampThe latest contact.
next_follow_up_atstring | nullISO 8601 timestampWhen to contact the lead again. Cleared when the lead is won or lost.
time_to_first_contact_secondsinteger | nullWall clock from
created_attofirst_contacted_at, in seconds. Null until contacted.uncontacted_nudged_atstring | nullISO 8601 timestampWhen
lead.uncontactedwas recorded for the lead; null when it never was.merged_into_idstring | nullThe kept lead's id when this lead was merged. Merged leads remain readable by id.
possible_repeat_ofarray of stringDetail 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 itemsOther 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
idstringrequirednamestring | nullrequiredemailstring | nullrequiredphonestring | nullrequiredsourcestringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingothercreated_atstringrequiredISO 8601 timestampreasonstringrequiredOne of
phoneemailrepeat_caller
merged_fromarray of objectLeads merged into this lead, oldest first. Origin links stay on these rows, including all earlier merges.
7 attributes
idstringrequirednamestring | nullrequiredsourcestringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingotherconversation_idstring | nullrequiredcall_idstring | nullrequiredform_submission_idstring | nullrequiredcreated_atstringrequiredISO 8601 timestamp
status_historyarray of objectEvery status change, oldest first.
5 attributes
fromstringrequiredOne of
newcontactedqualifiedwonlosttostringrequiredOne of
newcontactedqualifiedwonlostatstringrequiredISO 8601 timestampbystringrequiredby_namestring | nullrequired
contactsarray of LeadContactDetail read only. Live logged contacts, newest first; voided ones are left out.
8 attributes
idstringrequiredlcon_....channelstringrequiredOne of
phonewhatsappemailsmsin_personotherviastringrequiredA console contact button, Log contact, or the API.
One of
buttonmanualapicontacted_atstringrequiredISO 8601 timestampbystringrequiredA user id, or the
agent.idan API key named.by_namestring | nullrequiredstatus_movedbooleanrequiredWhether this contact moved the lead from
newtocontacted.logged_atstringrequiredISO 8601 timestampWhen the contact was logged: the time of the status change it made. Undo is open for a day after.
form_originobject | nullDetail read only. The form a form or
ad_formlead came from; null for other leads.adholds the ad platform's ids for anad_formlead (attribution.ad_forminlead.captured), null for a website form.4 attributes
form_idstringform_namestringchannelstringOne of
websitegoogle_lead_formadobject | null
bookingsarray of objectScheduling facts for this lead and mode, up to 200 bookings, oldest first. CRM outcome is unchanged.
9 attributes
idstringrequireduidstringrequiredevent_namestringrequiredstatusstringrequiredOne of
pendingprocessingconfirmedcompletedrejectedexpiredcancelledrescheduledmodestringrequiredOne of
liveteststart_atstringrequiredISO 8601 timestampend_atstringrequiredISO 8601 timestamptimezonestringrequiredrescheduled_to_idstring | nullrequired
callbackobject | nullThe callback the visitor asked for in the lead's chat, as on the conversation. Detail read only.
7 attributes
phonestringslot_startstringISO 8601 timestampnotestringrequested_atstringISO 8601 timestampdone_atstringISO 8601 timestampdone_bystringdone_by_namestring
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen 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). WaitRetry-Afterseconds. 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).
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"
}'{
"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
idstringrequiredLead id,
lead_....contactIdstringrequiredContact id,
lcon_....
Returns
200 OK
Response attributes
dataobjectrequired1 attribute
leadLeadDetailrequired48 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequiredassistant_idstring | nullThe assistant that captured the lead; null when no assistant did (a form lead, or one added by hand).
conversation_idstring | nullnamestring | nullemailstring | nullemailphonestring | nullfact_provenanceobjectProvenance 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
sourcestringrequiredOne of
conversationchannelformmanualchannelstringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingotherconversation_idstring | nullrequiredcall_idstring | nullrequiredform_submission_idstring | nullrequiredcaptured_atstringrequiredISO 8601 timestampcaptured_at_estimatedbooleanrequirededited_atstring | nullrequiredISO 8601 timestampedited_bystring | nullrequired
fieldsobject | nullsourcestringrequiredWhere 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) orother(such as a lead added by hand).One of
web_chatweb_callphone_callsmswhatsappformad_formschedulingothermodestringCapture provenance: the chat mode, independent of email classification.
One of
livetestpreviewtestbooleanEffective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See
trafficto tell them apart.trafficstringWhich 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) orreal. Sandbox wins over test. Sandbox and test are both left out of real numbers.One of
realsandboxtesttest_reasonstring | nullAutomatic classification, recomputed when saved:
reserved_domain(placeholder email),business_domain(your own email domain) orstaging_site(a live chat on a staging or preview page). An email reason wins over staging_site.One of
reserved_domainbusiness_domainstaging_sitetest_overrideboolean | nullMember override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox.
outcomestring | nullWhat became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).
One of
openbookedlostoutcome_valuestring | nullBooking value as a decimal string.
outcome_currencystring | nulloutcome_atstring | nullISO 8601 timestampoutcome_refstring | nullThe CRM's own id for the booking.
customer_idstring | nullThe customer's own id for this person, set with PUT /v1/leads/{id}/outcome.
statusstringThe front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts
new.new,contactedandqualifiedare open;wonandlostclose it. Separate fromoutcome, which your CRM reports.One of
newcontactedqualifiedwonloststatus_changed_atstring | nullISO 8601 timestampstatus_changed_bystring | nullA user id, or the
agent.idan API key named.status_changed_by_namestring | nullattributionChatAttribution | nullWhere the lead's chat came from. Returned by the list and detail reads; null when none was recorded.
One of 2 shapes
ChatAttribution
chat_pagestringThe path the visitor started chatting on.
visitChatAttributionTouchThis visit's landing.
20 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
firstobjectThe visitor's first-ever landing.
21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor first landed.
latest_paidobjectThe visitor's latest ad click within 90 days: a landing with a click id, or with
utm_mediumcpc, 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 fromvisitandfirst.21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor landed from this ad click.
Option 2
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestampcapture_methodstringHow 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) orscheduling(a direct booking). Later updates never change it.One of
toolanalysisformmanualschedulingcall_idstring | nullThe call the lead came from, when it came from one.
form_submission_idstring | nullThe form submission the lead came from, when it came from one.
phone_e164string | nullphonein E.164 form when it could be read as a number;phonestays as given.phone_sourcestring | nullcaller_idwhen a call lead'sphoneis the number the call came from, because the caller never said one. Null means the person gave it.One of
givencaller_idfirst_contacted_atstring | nullISO 8601 timestampThe first contact: the earliest logged contact, or the first status change out of
newby a person or key. Null until contacted.last_contacted_atstring | nullISO 8601 timestampThe latest contact.
next_follow_up_atstring | nullISO 8601 timestampWhen to contact the lead again. Cleared when the lead is won or lost.
time_to_first_contact_secondsinteger | nullWall clock from
created_attofirst_contacted_at, in seconds. Null until contacted.uncontacted_nudged_atstring | nullISO 8601 timestampWhen
lead.uncontactedwas recorded for the lead; null when it never was.merged_into_idstring | nullThe kept lead's id when this lead was merged. Merged leads remain readable by id.
possible_repeat_ofarray of stringDetail 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 itemsOther 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
idstringrequirednamestring | nullrequiredemailstring | nullrequiredphonestring | nullrequiredsourcestringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingothercreated_atstringrequiredISO 8601 timestampreasonstringrequiredOne of
phoneemailrepeat_caller
merged_fromarray of objectLeads merged into this lead, oldest first. Origin links stay on these rows, including all earlier merges.
7 attributes
idstringrequirednamestring | nullrequiredsourcestringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingotherconversation_idstring | nullrequiredcall_idstring | nullrequiredform_submission_idstring | nullrequiredcreated_atstringrequiredISO 8601 timestamp
status_historyarray of objectEvery status change, oldest first.
5 attributes
fromstringrequiredOne of
newcontactedqualifiedwonlosttostringrequiredOne of
newcontactedqualifiedwonlostatstringrequiredISO 8601 timestampbystringrequiredby_namestring | nullrequired
contactsarray of LeadContactDetail read only. Live logged contacts, newest first; voided ones are left out.
8 attributes
idstringrequiredlcon_....channelstringrequiredOne of
phonewhatsappemailsmsin_personotherviastringrequiredA console contact button, Log contact, or the API.
One of
buttonmanualapicontacted_atstringrequiredISO 8601 timestampbystringrequiredA user id, or the
agent.idan API key named.by_namestring | nullrequiredstatus_movedbooleanrequiredWhether this contact moved the lead from
newtocontacted.logged_atstringrequiredISO 8601 timestampWhen the contact was logged: the time of the status change it made. Undo is open for a day after.
form_originobject | nullDetail read only. The form a form or
ad_formlead came from; null for other leads.adholds the ad platform's ids for anad_formlead (attribution.ad_forminlead.captured), null for a website form.4 attributes
form_idstringform_namestringchannelstringOne of
websitegoogle_lead_formadobject | null
bookingsarray of objectScheduling facts for this lead and mode, up to 200 bookings, oldest first. CRM outcome is unchanged.
9 attributes
idstringrequireduidstringrequiredevent_namestringrequiredstatusstringrequiredOne of
pendingprocessingconfirmedcompletedrejectedexpiredcancelledrescheduledmodestringrequiredOne of
liveteststart_atstringrequiredISO 8601 timestampend_atstringrequiredISO 8601 timestamptimezonestringrequiredrescheduled_to_idstring | nullrequired
callbackobject | nullThe callback the visitor asked for in the lead's chat, as on the conversation. Detail read only.
7 attributes
phonestringslot_startstringISO 8601 timestampnotestringrequested_atstringISO 8601 timestampdone_atstringISO 8601 timestampdone_bystringdone_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). WaitRetry-Afterseconds. 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).
curl -X POST "https://api.brightshoal.com/api/leads/LEAD_ID/contacts/CONTACT_ID/void" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"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
idstringrequiredfieldstringrequired
Request body
valuestring | nullrequiredup to 500 characters
Returns
200 OK
Response attributes
dataLeadrequired40 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequiredassistant_idstring | nullThe assistant that captured the lead; null when no assistant did (a form lead, or one added by hand).
conversation_idstring | nullnamestring | nullemailstring | nullemailphonestring | nullfact_provenanceobjectProvenance 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
sourcestringrequiredOne of
conversationchannelformmanualchannelstringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingotherconversation_idstring | nullrequiredcall_idstring | nullrequiredform_submission_idstring | nullrequiredcaptured_atstringrequiredISO 8601 timestampcaptured_at_estimatedbooleanrequirededited_atstring | nullrequiredISO 8601 timestampedited_bystring | nullrequired
fieldsobject | nullsourcestringrequiredWhere 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) orother(such as a lead added by hand).One of
web_chatweb_callphone_callsmswhatsappformad_formschedulingothermodestringCapture provenance: the chat mode, independent of email classification.
One of
livetestpreviewtestbooleanEffective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See
trafficto tell them apart.trafficstringWhich 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) orreal. Sandbox wins over test. Sandbox and test are both left out of real numbers.One of
realsandboxtesttest_reasonstring | nullAutomatic classification, recomputed when saved:
reserved_domain(placeholder email),business_domain(your own email domain) orstaging_site(a live chat on a staging or preview page). An email reason wins over staging_site.One of
reserved_domainbusiness_domainstaging_sitetest_overrideboolean | nullMember override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox.
outcomestring | nullWhat became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).
One of
openbookedlostoutcome_valuestring | nullBooking value as a decimal string.
outcome_currencystring | nulloutcome_atstring | nullISO 8601 timestampoutcome_refstring | nullThe CRM's own id for the booking.
customer_idstring | nullThe customer's own id for this person, set with PUT /v1/leads/{id}/outcome.
statusstringThe front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts
new.new,contactedandqualifiedare open;wonandlostclose it. Separate fromoutcome, which your CRM reports.One of
newcontactedqualifiedwonloststatus_changed_atstring | nullISO 8601 timestampstatus_changed_bystring | nullA user id, or the
agent.idan API key named.status_changed_by_namestring | nullattributionChatAttribution | nullWhere the lead's chat came from. Returned by the list and detail reads; null when none was recorded.
One of 2 shapes
ChatAttribution
chat_pagestringThe path the visitor started chatting on.
visitChatAttributionTouchThis visit's landing.
20 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
firstobjectThe visitor's first-ever landing.
21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor first landed.
latest_paidobjectThe visitor's latest ad click within 90 days: a landing with a click id, or with
utm_mediumcpc, 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 fromvisitandfirst.21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor landed from this ad click.
Option 2
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestampcapture_methodstringHow 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) orscheduling(a direct booking). Later updates never change it.One of
toolanalysisformmanualschedulingcall_idstring | nullThe call the lead came from, when it came from one.
form_submission_idstring | nullThe form submission the lead came from, when it came from one.
phone_e164string | nullphonein E.164 form when it could be read as a number;phonestays as given.phone_sourcestring | nullcaller_idwhen a call lead'sphoneis the number the call came from, because the caller never said one. Null means the person gave it.One of
givencaller_idfirst_contacted_atstring | nullISO 8601 timestampThe first contact: the earliest logged contact, or the first status change out of
newby a person or key. Null until contacted.last_contacted_atstring | nullISO 8601 timestampThe latest contact.
next_follow_up_atstring | nullISO 8601 timestampWhen to contact the lead again. Cleared when the lead is won or lost.
time_to_first_contact_secondsinteger | nullWall clock from
created_attofirst_contacted_at, in seconds. Null until contacted.uncontacted_nudged_atstring | nullISO 8601 timestampWhen
lead.uncontactedwas recorded for the lead; null when it never was.merged_into_idstring | nullThe 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 inissueswhen 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). WaitRetry-Afterseconds. 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).
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"
}'{
"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
idstringrequiredLead id,
lead_....
Request body
next_follow_up_atstring | nullrequiredISO 8601 timestampWhen 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
dataLeadDetailrequired48 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequiredassistant_idstring | nullThe assistant that captured the lead; null when no assistant did (a form lead, or one added by hand).
conversation_idstring | nullnamestring | nullemailstring | nullemailphonestring | nullfact_provenanceobjectProvenance 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
sourcestringrequiredOne of
conversationchannelformmanualchannelstringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingotherconversation_idstring | nullrequiredcall_idstring | nullrequiredform_submission_idstring | nullrequiredcaptured_atstringrequiredISO 8601 timestampcaptured_at_estimatedbooleanrequirededited_atstring | nullrequiredISO 8601 timestampedited_bystring | nullrequired
fieldsobject | nullsourcestringrequiredWhere 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) orother(such as a lead added by hand).One of
web_chatweb_callphone_callsmswhatsappformad_formschedulingothermodestringCapture provenance: the chat mode, independent of email classification.
One of
livetestpreviewtestbooleanEffective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See
trafficto tell them apart.trafficstringWhich 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) orreal. Sandbox wins over test. Sandbox and test are both left out of real numbers.One of
realsandboxtesttest_reasonstring | nullAutomatic classification, recomputed when saved:
reserved_domain(placeholder email),business_domain(your own email domain) orstaging_site(a live chat on a staging or preview page). An email reason wins over staging_site.One of
reserved_domainbusiness_domainstaging_sitetest_overrideboolean | nullMember override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox.
outcomestring | nullWhat became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).
One of
openbookedlostoutcome_valuestring | nullBooking value as a decimal string.
outcome_currencystring | nulloutcome_atstring | nullISO 8601 timestampoutcome_refstring | nullThe CRM's own id for the booking.
customer_idstring | nullThe customer's own id for this person, set with PUT /v1/leads/{id}/outcome.
statusstringThe front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts
new.new,contactedandqualifiedare open;wonandlostclose it. Separate fromoutcome, which your CRM reports.One of
newcontactedqualifiedwonloststatus_changed_atstring | nullISO 8601 timestampstatus_changed_bystring | nullA user id, or the
agent.idan API key named.status_changed_by_namestring | nullattributionChatAttribution | nullWhere the lead's chat came from. Returned by the list and detail reads; null when none was recorded.
One of 2 shapes
ChatAttribution
chat_pagestringThe path the visitor started chatting on.
visitChatAttributionTouchThis visit's landing.
20 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
firstobjectThe visitor's first-ever landing.
21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor first landed.
latest_paidobjectThe visitor's latest ad click within 90 days: a landing with a click id, or with
utm_mediumcpc, 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 fromvisitandfirst.21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor landed from this ad click.
Option 2
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestampcapture_methodstringHow 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) orscheduling(a direct booking). Later updates never change it.One of
toolanalysisformmanualschedulingcall_idstring | nullThe call the lead came from, when it came from one.
form_submission_idstring | nullThe form submission the lead came from, when it came from one.
phone_e164string | nullphonein E.164 form when it could be read as a number;phonestays as given.phone_sourcestring | nullcaller_idwhen a call lead'sphoneis the number the call came from, because the caller never said one. Null means the person gave it.One of
givencaller_idfirst_contacted_atstring | nullISO 8601 timestampThe first contact: the earliest logged contact, or the first status change out of
newby a person or key. Null until contacted.last_contacted_atstring | nullISO 8601 timestampThe latest contact.
next_follow_up_atstring | nullISO 8601 timestampWhen to contact the lead again. Cleared when the lead is won or lost.
time_to_first_contact_secondsinteger | nullWall clock from
created_attofirst_contacted_at, in seconds. Null until contacted.uncontacted_nudged_atstring | nullISO 8601 timestampWhen
lead.uncontactedwas recorded for the lead; null when it never was.merged_into_idstring | nullThe kept lead's id when this lead was merged. Merged leads remain readable by id.
possible_repeat_ofarray of stringDetail 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 itemsOther 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
idstringrequirednamestring | nullrequiredemailstring | nullrequiredphonestring | nullrequiredsourcestringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingothercreated_atstringrequiredISO 8601 timestampreasonstringrequiredOne of
phoneemailrepeat_caller
merged_fromarray of objectLeads merged into this lead, oldest first. Origin links stay on these rows, including all earlier merges.
7 attributes
idstringrequirednamestring | nullrequiredsourcestringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingotherconversation_idstring | nullrequiredcall_idstring | nullrequiredform_submission_idstring | nullrequiredcreated_atstringrequiredISO 8601 timestamp
status_historyarray of objectEvery status change, oldest first.
5 attributes
fromstringrequiredOne of
newcontactedqualifiedwonlosttostringrequiredOne of
newcontactedqualifiedwonlostatstringrequiredISO 8601 timestampbystringrequiredby_namestring | nullrequired
contactsarray of LeadContactDetail read only. Live logged contacts, newest first; voided ones are left out.
8 attributes
idstringrequiredlcon_....channelstringrequiredOne of
phonewhatsappemailsmsin_personotherviastringrequiredA console contact button, Log contact, or the API.
One of
buttonmanualapicontacted_atstringrequiredISO 8601 timestampbystringrequiredA user id, or the
agent.idan API key named.by_namestring | nullrequiredstatus_movedbooleanrequiredWhether this contact moved the lead from
newtocontacted.logged_atstringrequiredISO 8601 timestampWhen the contact was logged: the time of the status change it made. Undo is open for a day after.
form_originobject | nullDetail read only. The form a form or
ad_formlead came from; null for other leads.adholds the ad platform's ids for anad_formlead (attribution.ad_forminlead.captured), null for a website form.4 attributes
form_idstringform_namestringchannelstringOne of
websitegoogle_lead_formadobject | null
bookingsarray of objectScheduling facts for this lead and mode, up to 200 bookings, oldest first. CRM outcome is unchanged.
9 attributes
idstringrequireduidstringrequiredevent_namestringrequiredstatusstringrequiredOne of
pendingprocessingconfirmedcompletedrejectedexpiredcancelledrescheduledmodestringrequiredOne of
liveteststart_atstringrequiredISO 8601 timestampend_atstringrequiredISO 8601 timestamptimezonestringrequiredrescheduled_to_idstring | nullrequired
callbackobject | nullThe callback the visitor asked for in the lead's chat, as on the conversation. Detail read only.
7 attributes
phonestringslot_startstringISO 8601 timestampnotestringrequested_atstringISO 8601 timestampdone_atstringISO 8601 timestampdone_bystringdone_by_namestring
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen 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). WaitRetry-Afterseconds. 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).
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"
}'{
"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
idstringrequiredThe lead to keep.
Request body
duplicate_idstringrequirednot empty
Returns
200 OK
Response attributes
dataLeadDetailrequired48 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequiredassistant_idstring | nullThe assistant that captured the lead; null when no assistant did (a form lead, or one added by hand).
conversation_idstring | nullnamestring | nullemailstring | nullemailphonestring | nullfact_provenanceobjectProvenance 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
sourcestringrequiredOne of
conversationchannelformmanualchannelstringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingotherconversation_idstring | nullrequiredcall_idstring | nullrequiredform_submission_idstring | nullrequiredcaptured_atstringrequiredISO 8601 timestampcaptured_at_estimatedbooleanrequirededited_atstring | nullrequiredISO 8601 timestampedited_bystring | nullrequired
fieldsobject | nullsourcestringrequiredWhere 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) orother(such as a lead added by hand).One of
web_chatweb_callphone_callsmswhatsappformad_formschedulingothermodestringCapture provenance: the chat mode, independent of email classification.
One of
livetestpreviewtestbooleanEffective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See
trafficto tell them apart.trafficstringWhich 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) orreal. Sandbox wins over test. Sandbox and test are both left out of real numbers.One of
realsandboxtesttest_reasonstring | nullAutomatic classification, recomputed when saved:
reserved_domain(placeholder email),business_domain(your own email domain) orstaging_site(a live chat on a staging or preview page). An email reason wins over staging_site.One of
reserved_domainbusiness_domainstaging_sitetest_overrideboolean | nullMember override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox.
outcomestring | nullWhat became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).
One of
openbookedlostoutcome_valuestring | nullBooking value as a decimal string.
outcome_currencystring | nulloutcome_atstring | nullISO 8601 timestampoutcome_refstring | nullThe CRM's own id for the booking.
customer_idstring | nullThe customer's own id for this person, set with PUT /v1/leads/{id}/outcome.
statusstringThe front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts
new.new,contactedandqualifiedare open;wonandlostclose it. Separate fromoutcome, which your CRM reports.One of
newcontactedqualifiedwonloststatus_changed_atstring | nullISO 8601 timestampstatus_changed_bystring | nullA user id, or the
agent.idan API key named.status_changed_by_namestring | nullattributionChatAttribution | nullWhere the lead's chat came from. Returned by the list and detail reads; null when none was recorded.
One of 2 shapes
ChatAttribution
chat_pagestringThe path the visitor started chatting on.
visitChatAttributionTouchThis visit's landing.
20 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
firstobjectThe visitor's first-ever landing.
21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor first landed.
latest_paidobjectThe visitor's latest ad click within 90 days: a landing with a click id, or with
utm_mediumcpc, 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 fromvisitandfirst.21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor landed from this ad click.
Option 2
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestampcapture_methodstringHow 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) orscheduling(a direct booking). Later updates never change it.One of
toolanalysisformmanualschedulingcall_idstring | nullThe call the lead came from, when it came from one.
form_submission_idstring | nullThe form submission the lead came from, when it came from one.
phone_e164string | nullphonein E.164 form when it could be read as a number;phonestays as given.phone_sourcestring | nullcaller_idwhen a call lead'sphoneis the number the call came from, because the caller never said one. Null means the person gave it.One of
givencaller_idfirst_contacted_atstring | nullISO 8601 timestampThe first contact: the earliest logged contact, or the first status change out of
newby a person or key. Null until contacted.last_contacted_atstring | nullISO 8601 timestampThe latest contact.
next_follow_up_atstring | nullISO 8601 timestampWhen to contact the lead again. Cleared when the lead is won or lost.
time_to_first_contact_secondsinteger | nullWall clock from
created_attofirst_contacted_at, in seconds. Null until contacted.uncontacted_nudged_atstring | nullISO 8601 timestampWhen
lead.uncontactedwas recorded for the lead; null when it never was.merged_into_idstring | nullThe kept lead's id when this lead was merged. Merged leads remain readable by id.
possible_repeat_ofarray of stringDetail 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 itemsOther 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
idstringrequirednamestring | nullrequiredemailstring | nullrequiredphonestring | nullrequiredsourcestringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingothercreated_atstringrequiredISO 8601 timestampreasonstringrequiredOne of
phoneemailrepeat_caller
merged_fromarray of objectLeads merged into this lead, oldest first. Origin links stay on these rows, including all earlier merges.
7 attributes
idstringrequirednamestring | nullrequiredsourcestringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingotherconversation_idstring | nullrequiredcall_idstring | nullrequiredform_submission_idstring | nullrequiredcreated_atstringrequiredISO 8601 timestamp
status_historyarray of objectEvery status change, oldest first.
5 attributes
fromstringrequiredOne of
newcontactedqualifiedwonlosttostringrequiredOne of
newcontactedqualifiedwonlostatstringrequiredISO 8601 timestampbystringrequiredby_namestring | nullrequired
contactsarray of LeadContactDetail read only. Live logged contacts, newest first; voided ones are left out.
8 attributes
idstringrequiredlcon_....channelstringrequiredOne of
phonewhatsappemailsmsin_personotherviastringrequiredA console contact button, Log contact, or the API.
One of
buttonmanualapicontacted_atstringrequiredISO 8601 timestampbystringrequiredA user id, or the
agent.idan API key named.by_namestring | nullrequiredstatus_movedbooleanrequiredWhether this contact moved the lead from
newtocontacted.logged_atstringrequiredISO 8601 timestampWhen the contact was logged: the time of the status change it made. Undo is open for a day after.
form_originobject | nullDetail read only. The form a form or
ad_formlead came from; null for other leads.adholds the ad platform's ids for anad_formlead (attribution.ad_forminlead.captured), null for a website form.4 attributes
form_idstringform_namestringchannelstringOne of
websitegoogle_lead_formadobject | null
bookingsarray of objectScheduling facts for this lead and mode, up to 200 bookings, oldest first. CRM outcome is unchanged.
9 attributes
idstringrequireduidstringrequiredevent_namestringrequiredstatusstringrequiredOne of
pendingprocessingconfirmedcompletedrejectedexpiredcancelledrescheduledmodestringrequiredOne of
liveteststart_atstringrequiredISO 8601 timestampend_atstringrequiredISO 8601 timestamptimezonestringrequiredrescheduled_to_idstring | nullrequired
callbackobject | nullThe callback the visitor asked for in the lead's chat, as on the conversation. Detail read only.
7 attributes
phonestringslot_startstringISO 8601 timestampnotestringrequested_atstringISO 8601 timestampdone_atstringISO 8601 timestampdone_bystringdone_by_namestring
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen 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). WaitRetry-Afterseconds. 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).
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"
}'{
"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
idstringrequiredLead id, lead_...
Request body
duplicate_idstringrequirednot empty
Returns
200 Dismissed
Response attributes
okbooleanrequired
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen 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). WaitRetry-Afterseconds. 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).
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"
}'{
"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
idstringrequiredLead id,
lead_....
Request body
outcomestringrequiredOne of
openbookedlostvaluenumbermin 0Booking value, stored to two decimal places.
currencystringISO 4217 code in capitals, for example
GBP. Required when value is given.atstringISO 8601 timestampWhen it happened, ISO 8601 with an offset. Default: now.
refstringup to 128 charactersYour CRM's id for the booking.
customer_idstringup to 128 charactersThe 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
dataLeadrequired40 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequiredassistant_idstring | nullThe assistant that captured the lead; null when no assistant did (a form lead, or one added by hand).
conversation_idstring | nullnamestring | nullemailstring | nullemailphonestring | nullfact_provenanceobjectProvenance 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
sourcestringrequiredOne of
conversationchannelformmanualchannelstringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingotherconversation_idstring | nullrequiredcall_idstring | nullrequiredform_submission_idstring | nullrequiredcaptured_atstringrequiredISO 8601 timestampcaptured_at_estimatedbooleanrequirededited_atstring | nullrequiredISO 8601 timestampedited_bystring | nullrequired
fieldsobject | nullsourcestringrequiredWhere 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) orother(such as a lead added by hand).One of
web_chatweb_callphone_callsmswhatsappformad_formschedulingothermodestringCapture provenance: the chat mode, independent of email classification.
One of
livetestpreviewtestbooleanEffective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See
trafficto tell them apart.trafficstringWhich 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) orreal. Sandbox wins over test. Sandbox and test are both left out of real numbers.One of
realsandboxtesttest_reasonstring | nullAutomatic classification, recomputed when saved:
reserved_domain(placeholder email),business_domain(your own email domain) orstaging_site(a live chat on a staging or preview page). An email reason wins over staging_site.One of
reserved_domainbusiness_domainstaging_sitetest_overrideboolean | nullMember override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox.
outcomestring | nullWhat became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).
One of
openbookedlostoutcome_valuestring | nullBooking value as a decimal string.
outcome_currencystring | nulloutcome_atstring | nullISO 8601 timestampoutcome_refstring | nullThe CRM's own id for the booking.
customer_idstring | nullThe customer's own id for this person, set with PUT /v1/leads/{id}/outcome.
statusstringThe front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts
new.new,contactedandqualifiedare open;wonandlostclose it. Separate fromoutcome, which your CRM reports.One of
newcontactedqualifiedwonloststatus_changed_atstring | nullISO 8601 timestampstatus_changed_bystring | nullA user id, or the
agent.idan API key named.status_changed_by_namestring | nullattributionChatAttribution | nullWhere the lead's chat came from. Returned by the list and detail reads; null when none was recorded.
One of 2 shapes
ChatAttribution
chat_pagestringThe path the visitor started chatting on.
visitChatAttributionTouchThis visit's landing.
20 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
firstobjectThe visitor's first-ever landing.
21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor first landed.
latest_paidobjectThe visitor's latest ad click within 90 days: a landing with a click id, or with
utm_mediumcpc, 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 fromvisitandfirst.21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor landed from this ad click.
Option 2
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestampcapture_methodstringHow 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) orscheduling(a direct booking). Later updates never change it.One of
toolanalysisformmanualschedulingcall_idstring | nullThe call the lead came from, when it came from one.
form_submission_idstring | nullThe form submission the lead came from, when it came from one.
phone_e164string | nullphonein E.164 form when it could be read as a number;phonestays as given.phone_sourcestring | nullcaller_idwhen a call lead'sphoneis the number the call came from, because the caller never said one. Null means the person gave it.One of
givencaller_idfirst_contacted_atstring | nullISO 8601 timestampThe first contact: the earliest logged contact, or the first status change out of
newby a person or key. Null until contacted.last_contacted_atstring | nullISO 8601 timestampThe latest contact.
next_follow_up_atstring | nullISO 8601 timestampWhen to contact the lead again. Cleared when the lead is won or lost.
time_to_first_contact_secondsinteger | nullWall clock from
created_attofirst_contacted_at, in seconds. Null until contacted.uncontacted_nudged_atstring | nullISO 8601 timestampWhen
lead.uncontactedwas recorded for the lead; null when it never was.merged_into_idstring | nullThe 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 inissueswhen 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). WaitRetry-Afterseconds. 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).
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"
}'{
"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
idstringrequiredLead id,
lead_....
Request body
statusstringrequiredOne of
newcontactedqualifiedwonlostagentAgentIdentityInput3 attributes
idstringemailstringemailnamestring
Returns
200 OK
Response attributes
dataLeadDetailrequired48 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequiredassistant_idstring | nullThe assistant that captured the lead; null when no assistant did (a form lead, or one added by hand).
conversation_idstring | nullnamestring | nullemailstring | nullemailphonestring | nullfact_provenanceobjectProvenance 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
sourcestringrequiredOne of
conversationchannelformmanualchannelstringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingotherconversation_idstring | nullrequiredcall_idstring | nullrequiredform_submission_idstring | nullrequiredcaptured_atstringrequiredISO 8601 timestampcaptured_at_estimatedbooleanrequirededited_atstring | nullrequiredISO 8601 timestampedited_bystring | nullrequired
fieldsobject | nullsourcestringrequiredWhere 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) orother(such as a lead added by hand).One of
web_chatweb_callphone_callsmswhatsappformad_formschedulingothermodestringCapture provenance: the chat mode, independent of email classification.
One of
livetestpreviewtestbooleanEffective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See
trafficto tell them apart.trafficstringWhich 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) orreal. Sandbox wins over test. Sandbox and test are both left out of real numbers.One of
realsandboxtesttest_reasonstring | nullAutomatic classification, recomputed when saved:
reserved_domain(placeholder email),business_domain(your own email domain) orstaging_site(a live chat on a staging or preview page). An email reason wins over staging_site.One of
reserved_domainbusiness_domainstaging_sitetest_overrideboolean | nullMember override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox.
outcomestring | nullWhat became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).
One of
openbookedlostoutcome_valuestring | nullBooking value as a decimal string.
outcome_currencystring | nulloutcome_atstring | nullISO 8601 timestampoutcome_refstring | nullThe CRM's own id for the booking.
customer_idstring | nullThe customer's own id for this person, set with PUT /v1/leads/{id}/outcome.
statusstringThe front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts
new.new,contactedandqualifiedare open;wonandlostclose it. Separate fromoutcome, which your CRM reports.One of
newcontactedqualifiedwonloststatus_changed_atstring | nullISO 8601 timestampstatus_changed_bystring | nullA user id, or the
agent.idan API key named.status_changed_by_namestring | nullattributionChatAttribution | nullWhere the lead's chat came from. Returned by the list and detail reads; null when none was recorded.
One of 2 shapes
ChatAttribution
chat_pagestringThe path the visitor started chatting on.
visitChatAttributionTouchThis visit's landing.
20 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
firstobjectThe visitor's first-ever landing.
21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor first landed.
latest_paidobjectThe visitor's latest ad click within 90 days: a landing with a click id, or with
utm_mediumcpc, 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 fromvisitandfirst.21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor landed from this ad click.
Option 2
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestampcapture_methodstringHow 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) orscheduling(a direct booking). Later updates never change it.One of
toolanalysisformmanualschedulingcall_idstring | nullThe call the lead came from, when it came from one.
form_submission_idstring | nullThe form submission the lead came from, when it came from one.
phone_e164string | nullphonein E.164 form when it could be read as a number;phonestays as given.phone_sourcestring | nullcaller_idwhen a call lead'sphoneis the number the call came from, because the caller never said one. Null means the person gave it.One of
givencaller_idfirst_contacted_atstring | nullISO 8601 timestampThe first contact: the earliest logged contact, or the first status change out of
newby a person or key. Null until contacted.last_contacted_atstring | nullISO 8601 timestampThe latest contact.
next_follow_up_atstring | nullISO 8601 timestampWhen to contact the lead again. Cleared when the lead is won or lost.
time_to_first_contact_secondsinteger | nullWall clock from
created_attofirst_contacted_at, in seconds. Null until contacted.uncontacted_nudged_atstring | nullISO 8601 timestampWhen
lead.uncontactedwas recorded for the lead; null when it never was.merged_into_idstring | nullThe kept lead's id when this lead was merged. Merged leads remain readable by id.
possible_repeat_ofarray of stringDetail 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 itemsOther 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
idstringrequirednamestring | nullrequiredemailstring | nullrequiredphonestring | nullrequiredsourcestringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingothercreated_atstringrequiredISO 8601 timestampreasonstringrequiredOne of
phoneemailrepeat_caller
merged_fromarray of objectLeads merged into this lead, oldest first. Origin links stay on these rows, including all earlier merges.
7 attributes
idstringrequirednamestring | nullrequiredsourcestringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingotherconversation_idstring | nullrequiredcall_idstring | nullrequiredform_submission_idstring | nullrequiredcreated_atstringrequiredISO 8601 timestamp
status_historyarray of objectEvery status change, oldest first.
5 attributes
fromstringrequiredOne of
newcontactedqualifiedwonlosttostringrequiredOne of
newcontactedqualifiedwonlostatstringrequiredISO 8601 timestampbystringrequiredby_namestring | nullrequired
contactsarray of LeadContactDetail read only. Live logged contacts, newest first; voided ones are left out.
8 attributes
idstringrequiredlcon_....channelstringrequiredOne of
phonewhatsappemailsmsin_personotherviastringrequiredA console contact button, Log contact, or the API.
One of
buttonmanualapicontacted_atstringrequiredISO 8601 timestampbystringrequiredA user id, or the
agent.idan API key named.by_namestring | nullrequiredstatus_movedbooleanrequiredWhether this contact moved the lead from
newtocontacted.logged_atstringrequiredISO 8601 timestampWhen the contact was logged: the time of the status change it made. Undo is open for a day after.
form_originobject | nullDetail read only. The form a form or
ad_formlead came from; null for other leads.adholds the ad platform's ids for anad_formlead (attribution.ad_forminlead.captured), null for a website form.4 attributes
form_idstringform_namestringchannelstringOne of
websitegoogle_lead_formadobject | null
bookingsarray of objectScheduling facts for this lead and mode, up to 200 bookings, oldest first. CRM outcome is unchanged.
9 attributes
idstringrequireduidstringrequiredevent_namestringrequiredstatusstringrequiredOne of
pendingprocessingconfirmedcompletedrejectedexpiredcancelledrescheduledmodestringrequiredOne of
liveteststart_atstringrequiredISO 8601 timestampend_atstringrequiredISO 8601 timestamptimezonestringrequiredrescheduled_to_idstring | nullrequired
callbackobject | nullThe callback the visitor asked for in the lead's chat, as on the conversation. Detail read only.
7 attributes
phonestringslot_startstringISO 8601 timestampnotestringrequested_atstringISO 8601 timestampdone_atstringISO 8601 timestampdone_bystringdone_by_namestring
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen 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). WaitRetry-Afterseconds. 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).
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"
}'{
"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_idstringOnly this project's leads.
tzstringIANA time zone for the days. Default: the project's
timezonewhen you see one project, else UTC.
Returns
200 OK
Response attributes
dataLeadAttentionrequired5 attributes
uncontactedintegerrequiredoverdueintegerrequireddue_todayintegerrequiredlateintegerrequiredLeads uncontacted or overdue, each counted once: the nav count.
totalintegerrequiredLeads in any bucket, each counted once.
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. 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).
curl "https://api.brightshoal.com/api/leads/attention" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"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_idstringThe project. Required with an org-wide key; a project key uses its own.
Returns
200 OK
Response attributes
dataLeadsSettingsrequired3 attributes
project_idstringrequireduncontacted_after_minutesinteger | nullrequired15 to 1440Minutes a new lead may wait before
lead.uncontacted; null turns the nudge off. Default 60.counts_contact_hoursbooleanrequiredread-onlyTrue 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 inissueswhen 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). WaitRetry-Afterseconds. 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).
curl "https://api.brightshoal.com/api/leads/settings" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"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_idstringThe 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
dataLeadsSettingsrequired3 attributes
project_idstringrequireduncontacted_after_minutesinteger | nullrequired15 to 1440Minutes a new lead may wait before
lead.uncontacted; null turns the nudge off. Default 60.counts_contact_hoursbooleanrequiredread-onlyTrue 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 inissueswhen 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). WaitRetry-Afterseconds. 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).
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
}'{
"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_idstringOnly this project's leads.
fromstringISO 8601 timestamptostringISO 8601 timestampchannelstringOnly these channels (the lead's
source), comma separated.
Returns
200 OK
Response attributes
dataLeadSpeedrequired10 attributes
leadsintegerrequiredCounted leads: live, not test, not added by hand, created in the window.
contactedintegerrequireduncontactedintegerrequiredCounted leads never contacted. Read it beside the median.
median_secondsinteger | nullrequiredMedian time to first contact, contacted leads only.
p90_secondsinteger | nullrequiredwithin_5mintegerrequiredwithin_1hintegerrequiredwithin_24hintegerrequiredexcluded_manualintegerrequiredLeads added by hand in the window (live, not test): left out of every count above.
by_channelarray of objectrequired4 attributes
channelstringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingotherleadsintegerrequiredcontactedintegerrequiredmedian_secondsinteger | nullrequired
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. 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).
curl "https://api.brightshoal.com/api/leads/speed" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"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
}
]
}
}