API reference
Forms
Forms on your own site that post to Brightshoal: their fields, keys and approved sites, the submissions they receive, and submissions your server sends itself.
- POST
/api/formsCreate a form - GET
/api/formsList forms - GET
/api/forms/{id}Get a form - PATCH
/api/forms/{id}Update a form - POST
/api/forms/{id}/submissionsSend a submission from a server - GET
/api/forms/{id}/submissionsList a form's submissions - DELETE
/api/forms/{id}Delete an archived form - POST
/api/forms/{id}/archiveArchive a form - GET
/api/forms/{id}/googleGet a Google lead form's setup - PATCH
/api/forms/{id}/googleUpdate a Google lead form's setup - POST
/api/forms/{id}/google/rotate-keyRotate a Google lead form's key - POST
/api/forms/{id}/keys/{keyId}/revokeRevoke a form key - POST
/api/forms/{id}/keys/rotateRotate a form key - POST
/api/forms/{id}/restoreRestore an archived form - GET
/api/forms/{id}/submissions/{sid}Get a submission - DELETE
/api/forms/{id}/submissions/{sid}Delete an archived submission - POST
/api/forms/{id}/submissions/{sid}/archiveArchive a submission - GET
/api/forms/{id}/submissions/{sid}/files/{fileId}Download a submission's file - POST
/api/forms/{id}/submissions/{sid}/releaseRelease a held submission - POST
/api/forms/{id}/submissions/{sid}/replayReplay a submission's webhooks - POST
/api/forms/{id}/submissions/{sid}/restoreRestore an archived submission - GET
/api/forms/{id}/submissions/exportExport a form's submissions as CSV - POST
/api/forms/erasuresErase a person's form data - GET
/api/forms/healthList form health incidents - POST
/api/forms/health/{incidentId}/resolveResolve a form health incident
Create a form
POST/api/forms
Creates a form with one live and one test key. Needs the admin role.
Secret API key, not a viewer key. How it works
Request body
project_idstringchannelstringDefault
website.google_lead_formalso makes its Google key. On a Google lead form,approved_sites,redirect_url,thank_you,turnstile,honeypot_field,hold_unsure,fields,unknown_fieldsandfield_mapdo not apply: setting one is 400not_for_google_forms.One of
websitegoogle_lead_formnamestringrequiredup to 200 charactersstatusstringA paused form refuses posts.
One of
activepausedkindstringWhat the form is for. Default
enquiry.newsletterandcareerssubmissions never make leads.One of
enquirycallbacksupportnewslettercareersotherunknown_fieldsstringkeep(default) keeps submitted fields the definition does not name;rejectrefuses the post (unknown). Controls are never fields, and an empty definition never refuses.One of
keeprejectapproved_sitesarray of stringup to 20 itemsHosts a live key accepts posts from (the request's Origin, else its Referer), such as
www.example.com; a URL is reduced to its host. A host also covers its subdomains. Empty: a live key refuses every browser post (403site_not_approved) until a site is added. Test keys skip the check.redirect_urlstring | nulluriWhere a browser goes after a post, unless the post names an approved
_redirect. Null: the hosted thank-you page.thank_youobject | nullThe hosted thank-you page's text.
2 attributes
titlestringup to 200 charactersbodystringup to 2000 characters
honeypot_fieldstringA hidden field only bots fill (default
botcheck): a post that fills it is answered as a success and kept nowhere. It may not be a control's name (_redirect,_page,_referrer,access_key,cf-turnstile-response, anyutm_*, a click id), a defined field's key or a name the field map reads.hold_unsurebooleanHold submissions the spam check is unsure about for review.
fieldsarray of FormFieldup to 50 itemsThe fields the form defines, checked in order: a blank required field is
missing, then the type (invalid), length, range andpattern. A key that names a password, card number or national id is refused. Fields the form does not define are kept (seeunknown_fields). Empty: any fields are accepted.10 attributes
keystringrequiredup to 64 charactersThe field's name in the post.
labelstringup to 200 characterstypestringrequiredOne of
textemailphonetextareaurlnumberdatetimedatetimeselectmultiselectcheckboxconsentfilerequiredbooleanDefault
falseoptionsarray of stringThe values a post may send: required for
selectandmultiselect, optional forcheckbox(a group).helpstringup to 500 charactersplaceholderstringup to 200 charactersvalidationobject7 attributes
min_lengthinteger0 to 5000text, textarea, email, phone, url.
max_lengthinteger1 to 5000text, textarea, email, phone, url.
minnumber | stringnumber: a number; date, time, datetime: a value of that type; multiselect, checkbox group: a count of choices.
maxnumber | stringAs
min.integerbooleannumber only.
patternstringup to 500 charactersRE2 syntax, matched against the whole value (text, textarea, email, phone, url).
(?i)for any case. A pattern that does not compile is refused.messagestringup to 200 charactersReplaces the default error message.
fileobjectA
filefield's limits.3 attributes
acceptarray of stringup to 30 itemsmax_size_mbinteger1 to 10max_filesinteger1 to 5
consentobjectA
consentfield only, optional: the channel and purpose its box grants (a ledger consent, never required). Show the project's current consent wording (GET /consent/wordings) beside an unticked checkbox namedkeywhose value is the wording version. A ticked box on a post with a phone records aformgrant in the consent ledger with that version's text; a version the project never had is an invalid field. Without it the field is a plain consent: a ticked box (on,true,yesor1) is stored asyes, and it may be required.2 attributes
channelstringrequiredOne of
whatsappsmsvoice_humanpurposestringrequiredOne of
servicemarketing
field_mapobjectWhich submitted fields hold the person's name, email and phone. Defaults:
name,email,phone.3 attributes
namestringemailstringphonestring
retention_daysinteger1 to 3650Days a submission is kept. Default 365.
Returns
201 OK
Response attributes
dataFormrequired26 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequirednamestringrequiredup to 200 charactersstatusstringrequiredA paused form refuses posts.
One of
activepausedkindstringWhat the form is for. Default
enquiry.newsletterandcareerssubmissions never make leads.One of
enquirycallbacksupportnewslettercareersotherunknown_fieldsstringkeep(default) keeps submitted fields the definition does not name;rejectrefuses the post (unknown). Controls are never fields, and an empty definition never refuses.One of
keeprejectapproved_sitesarray of stringup to 20 itemsHosts a live key accepts posts from (the request's Origin, else its Referer), such as
www.example.com; a URL is reduced to its host. A host also covers its subdomains. Empty: a live key refuses every browser post (403site_not_approved) until a site is added. Test keys skip the check.redirect_urlstring | nulluriWhere a browser goes after a post, unless the post names an approved
_redirect. Null: the hosted thank-you page.thank_youobject | nullThe hosted thank-you page's text.
2 attributes
titlestringup to 200 charactersbodystringup to 2000 characters
honeypot_fieldstringA hidden field only bots fill (default
botcheck): a post that fills it is answered as a success and kept nowhere. It may not be a control's name (_redirect,_page,_referrer,access_key,cf-turnstile-response, anyutm_*, a click id), a defined field's key or a name the field map reads.hold_unsurebooleanHold submissions the spam check is unsure about for review.
fieldsarray of FormFieldrequiredup to 50 itemsThe fields the form defines, checked in order: a blank required field is
missing, then the type (invalid), length, range andpattern. A key that names a password, card number or national id is refused. Fields the form does not define are kept (seeunknown_fields). Empty: any fields are accepted.10 attributes
keystringrequiredup to 64 charactersThe field's name in the post.
labelstringup to 200 characterstypestringrequiredOne of
textemailphonetextareaurlnumberdatetimedatetimeselectmultiselectcheckboxconsentfilerequiredbooleanDefault
falseoptionsarray of stringThe values a post may send: required for
selectandmultiselect, optional forcheckbox(a group).helpstringup to 500 charactersplaceholderstringup to 200 charactersvalidationobject7 attributes
min_lengthinteger0 to 5000text, textarea, email, phone, url.
max_lengthinteger1 to 5000text, textarea, email, phone, url.
minnumber | stringnumber: a number; date, time, datetime: a value of that type; multiselect, checkbox group: a count of choices.
maxnumber | stringAs
min.integerbooleannumber only.
patternstringup to 500 charactersRE2 syntax, matched against the whole value (text, textarea, email, phone, url).
(?i)for any case. A pattern that does not compile is refused.messagestringup to 200 charactersReplaces the default error message.
fileobjectA
filefield's limits.3 attributes
acceptarray of stringup to 30 itemsmax_size_mbinteger1 to 10max_filesinteger1 to 5
consentobjectA
consentfield only, optional: the channel and purpose its box grants (a ledger consent, never required). Show the project's current consent wording (GET /consent/wordings) beside an unticked checkbox namedkeywhose value is the wording version. A ticked box on a post with a phone records aformgrant in the consent ledger with that version's text; a version the project never had is an invalid field. Without it the field is a plain consent: a ticked box (on,true,yesor1) is stored asyes, and it may be required.2 attributes
channelstringrequiredOne of
whatsappsmsvoice_humanpurposestringrequiredOne of
servicemarketing
field_mapobjectWhich submitted fields hold the person's name, email and phone. Defaults:
name,email,phone.3 attributes
namestringemailstringphonestring
retention_daysinteger1 to 3650Days a submission is kept. Default 365.
turnstilestringOne of
offonturnstile_site_keystring | nullturnstile_availablebooleanWhether this deployment can turn Turnstile on (it has Cloudflare credentials).
channelstringrequiredwebsite, orgoogle_lead_formfor a Google lead form connection. Set on create, never changed.One of
websitegoogle_lead_formkeysarray of FormKeyrequired5 attributes
idstringrequiredkeystringrequiredfkey_live_...orfkey_test_...: what the site posts to. Public, like the form's URL.modestringrequiredOne of
livetestexpires_atstring | nullISO 8601 timestampSet on a rotated key: when it stops working.
created_atstringISO 8601 timestamp
archived_atstring | nullISO 8601 timestampWhen the form was archived; null when it is live.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamphealthstringrequiredThe worst open health incident (
GET /v1/forms/health), orok.One of
okwarningcriticalgoogleobject | nullA Google lead form's ownership and arrivals, never its key; null for a website form.
4 attributes
lead_exportstringOne of
brightshoalother_tooloutcome_uploadsstringOne of
nonebrightshoalclient_crmlast_test_atstring | nullISO 8601 timestamplast_lead_atstring | nullISO 8601 timestamp
statsobjectGET /v1/forms/{id}only: live posts by outcome, from hourly counts.2 attributes
last_24hobject4 attributes
acceptedintegerrequiredheldintegerrequiredrefusedintegerrequiredEvery refusal reason, the hourly limit included.
failedintegerrequired
last_7dobject4 attributes
acceptedintegerrequiredheldintegerrequiredrefusedintegerrequiredEvery refusal reason, the hourly limit included.
failedintegerrequired
- 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 POST "https://api.brightshoal.com/api/forms" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Front desk"
}'{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"status": "active",
"kind": "enquiry",
"unknown_fields": "keep",
"approved_sites": [
"string"
],
"redirect_url": "https://example.com/hook",
"thank_you": {
"title": "Front desk",
"body": "string"
},
"honeypot_field": "string",
"hold_unsure": true,
"fields": [
{
"key": "string",
"label": "string",
"type": "text",
"required": true,
"options": [
"string"
],
"help": "string",
"placeholder": "string",
"validation": {
"min_length": 1,
"max_length": 1,
"min": 1,
"max": 1,
"integer": true,
"pattern": "string",
"message": "Hi, can I book a trip to Lisbon in May?"
},
"file": {
"accept": [
{}
],
"max_size_mb": 1,
"max_files": 1
},
"consent": {
"channel": "whatsapp",
"purpose": "service"
}
}
],
"field_map": {
"name": "Front desk",
"email": "ana@example.com",
"phone": "+14155550123"
},
"retention_days": 1,
"turnstile": "off",
"turnstile_site_key": "string",
"turnstile_available": true,
"channel": "website",
"keys": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"key": "string",
"mode": "live",
"expires_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z"
}
],
"archived_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z",
"health": "ok",
"google": {
"lead_export": "brightshoal",
"outcome_uploads": "none",
"last_test_at": "2026-10-28T09:30:00.000Z",
"last_lead_at": "2026-10-28T09:30:00.000Z"
},
"stats": {
"last_24h": {
"accepted": 1,
"held": 1,
"refused": 1,
"failed": 1
},
"last_7d": {
"accepted": 1,
"held": 1,
"refused": 1,
"failed": 1
}
}
}
}List forms
GET/api/forms
Forms in scope, newest first, each with the keys that accept posts (the test key only for the admin role). Archived forms are left out unless archived=true.
Secret API key. How it works
Query parameters
project_idstringOnly this project's forms.
archivedbooleantrue: only archived forms. Absent: only live ones.
Returns
200 OK
Response attributes
dataarray of Formrequired26 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequirednamestringrequiredup to 200 charactersstatusstringrequiredA paused form refuses posts.
One of
activepausedkindstringWhat the form is for. Default
enquiry.newsletterandcareerssubmissions never make leads.One of
enquirycallbacksupportnewslettercareersotherunknown_fieldsstringkeep(default) keeps submitted fields the definition does not name;rejectrefuses the post (unknown). Controls are never fields, and an empty definition never refuses.One of
keeprejectapproved_sitesarray of stringup to 20 itemsHosts a live key accepts posts from (the request's Origin, else its Referer), such as
www.example.com; a URL is reduced to its host. A host also covers its subdomains. Empty: a live key refuses every browser post (403site_not_approved) until a site is added. Test keys skip the check.redirect_urlstring | nulluriWhere a browser goes after a post, unless the post names an approved
_redirect. Null: the hosted thank-you page.thank_youobject | nullThe hosted thank-you page's text.
2 attributes
titlestringup to 200 charactersbodystringup to 2000 characters
honeypot_fieldstringA hidden field only bots fill (default
botcheck): a post that fills it is answered as a success and kept nowhere. It may not be a control's name (_redirect,_page,_referrer,access_key,cf-turnstile-response, anyutm_*, a click id), a defined field's key or a name the field map reads.hold_unsurebooleanHold submissions the spam check is unsure about for review.
fieldsarray of FormFieldrequiredup to 50 itemsThe fields the form defines, checked in order: a blank required field is
missing, then the type (invalid), length, range andpattern. A key that names a password, card number or national id is refused. Fields the form does not define are kept (seeunknown_fields). Empty: any fields are accepted.10 attributes
keystringrequiredup to 64 charactersThe field's name in the post.
labelstringup to 200 characterstypestringrequiredOne of
textemailphonetextareaurlnumberdatetimedatetimeselectmultiselectcheckboxconsentfilerequiredbooleanDefault
falseoptionsarray of stringThe values a post may send: required for
selectandmultiselect, optional forcheckbox(a group).helpstringup to 500 charactersplaceholderstringup to 200 charactersvalidationobject7 attributes
min_lengthinteger0 to 5000text, textarea, email, phone, url.
max_lengthinteger1 to 5000text, textarea, email, phone, url.
minnumber | stringnumber: a number; date, time, datetime: a value of that type; multiselect, checkbox group: a count of choices.
maxnumber | stringAs
min.integerbooleannumber only.
patternstringup to 500 charactersRE2 syntax, matched against the whole value (text, textarea, email, phone, url).
(?i)for any case. A pattern that does not compile is refused.messagestringup to 200 charactersReplaces the default error message.
fileobjectA
filefield's limits.3 attributes
acceptarray of stringup to 30 itemsmax_size_mbinteger1 to 10max_filesinteger1 to 5
consentobjectA
consentfield only, optional: the channel and purpose its box grants (a ledger consent, never required). Show the project's current consent wording (GET /consent/wordings) beside an unticked checkbox namedkeywhose value is the wording version. A ticked box on a post with a phone records aformgrant in the consent ledger with that version's text; a version the project never had is an invalid field. Without it the field is a plain consent: a ticked box (on,true,yesor1) is stored asyes, and it may be required.2 attributes
channelstringrequiredOne of
whatsappsmsvoice_humanpurposestringrequiredOne of
servicemarketing
field_mapobjectWhich submitted fields hold the person's name, email and phone. Defaults:
name,email,phone.3 attributes
namestringemailstringphonestring
retention_daysinteger1 to 3650Days a submission is kept. Default 365.
turnstilestringOne of
offonturnstile_site_keystring | nullturnstile_availablebooleanWhether this deployment can turn Turnstile on (it has Cloudflare credentials).
channelstringrequiredwebsite, orgoogle_lead_formfor a Google lead form connection. Set on create, never changed.One of
websitegoogle_lead_formkeysarray of FormKeyrequired5 attributes
idstringrequiredkeystringrequiredfkey_live_...orfkey_test_...: what the site posts to. Public, like the form's URL.modestringrequiredOne of
livetestexpires_atstring | nullISO 8601 timestampSet on a rotated key: when it stops working.
created_atstringISO 8601 timestamp
archived_atstring | nullISO 8601 timestampWhen the form was archived; null when it is live.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamphealthstringrequiredThe worst open health incident (
GET /v1/forms/health), orok.One of
okwarningcriticalgoogleobject | nullA Google lead form's ownership and arrivals, never its key; null for a website form.
4 attributes
lead_exportstringOne of
brightshoalother_tooloutcome_uploadsstringOne of
nonebrightshoalclient_crmlast_test_atstring | nullISO 8601 timestamplast_lead_atstring | nullISO 8601 timestamp
statsobjectGET /v1/forms/{id}only: live posts by outcome, from hourly counts.2 attributes
last_24hobject4 attributes
acceptedintegerrequiredheldintegerrequiredrefusedintegerrequiredEvery refusal reason, the hourly limit included.
failedintegerrequired
last_7dobject4 attributes
acceptedintegerrequiredheldintegerrequiredrefusedintegerrequiredEvery refusal reason, the hourly limit included.
failedintegerrequired
- 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/forms" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"status": "active",
"kind": "enquiry",
"unknown_fields": "keep",
"approved_sites": [
"string"
],
"redirect_url": "https://example.com/hook",
"thank_you": {
"title": "Front desk",
"body": "string"
},
"honeypot_field": "string",
"hold_unsure": true,
"fields": [
{
"key": "string",
"label": "string",
"type": "text",
"required": true,
"options": [
{}
],
"help": "string",
"placeholder": "string",
"validation": {
"min_length": {},
"max_length": {},
"min": {},
"max": {},
"integer": {},
"pattern": {},
"message": {}
},
"file": {
"accept": {},
"max_size_mb": {},
"max_files": {}
},
"consent": {
"channel": "whatsapp",
"purpose": "service"
}
}
],
"field_map": {
"name": "Front desk",
"email": "ana@example.com",
"phone": "+14155550123"
},
"retention_days": 1,
"turnstile": "off",
"turnstile_site_key": "string",
"turnstile_available": true,
"channel": "website",
"keys": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"key": "string",
"mode": "live",
"expires_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z"
}
],
"archived_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z",
"health": "ok",
"google": {
"lead_export": "brightshoal",
"outcome_uploads": "none",
"last_test_at": "2026-10-28T09:30:00.000Z",
"last_lead_at": "2026-10-28T09:30:00.000Z"
},
"stats": {
"last_24h": {
"accepted": 1,
"held": 1,
"refused": 1,
"failed": 1
},
"last_7d": {
"accepted": 1,
"held": 1,
"refused": 1,
"failed": 1
}
}
}
]
}Get a form
GET/api/forms/{id}
The form with the keys that accept posts (the test key only for the admin role), its health, and its live posts over the last 24 hours and 7 days (stats).
Secret API key. How it works
Path parameters
idstringrequiredForm id,
form_....
Returns
200 OK
Response attributes
dataFormrequired26 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequirednamestringrequiredup to 200 charactersstatusstringrequiredA paused form refuses posts.
One of
activepausedkindstringWhat the form is for. Default
enquiry.newsletterandcareerssubmissions never make leads.One of
enquirycallbacksupportnewslettercareersotherunknown_fieldsstringkeep(default) keeps submitted fields the definition does not name;rejectrefuses the post (unknown). Controls are never fields, and an empty definition never refuses.One of
keeprejectapproved_sitesarray of stringup to 20 itemsHosts a live key accepts posts from (the request's Origin, else its Referer), such as
www.example.com; a URL is reduced to its host. A host also covers its subdomains. Empty: a live key refuses every browser post (403site_not_approved) until a site is added. Test keys skip the check.redirect_urlstring | nulluriWhere a browser goes after a post, unless the post names an approved
_redirect. Null: the hosted thank-you page.thank_youobject | nullThe hosted thank-you page's text.
2 attributes
titlestringup to 200 charactersbodystringup to 2000 characters
honeypot_fieldstringA hidden field only bots fill (default
botcheck): a post that fills it is answered as a success and kept nowhere. It may not be a control's name (_redirect,_page,_referrer,access_key,cf-turnstile-response, anyutm_*, a click id), a defined field's key or a name the field map reads.hold_unsurebooleanHold submissions the spam check is unsure about for review.
fieldsarray of FormFieldrequiredup to 50 itemsThe fields the form defines, checked in order: a blank required field is
missing, then the type (invalid), length, range andpattern. A key that names a password, card number or national id is refused. Fields the form does not define are kept (seeunknown_fields). Empty: any fields are accepted.10 attributes
keystringrequiredup to 64 charactersThe field's name in the post.
labelstringup to 200 characterstypestringrequiredOne of
textemailphonetextareaurlnumberdatetimedatetimeselectmultiselectcheckboxconsentfilerequiredbooleanDefault
falseoptionsarray of stringThe values a post may send: required for
selectandmultiselect, optional forcheckbox(a group).helpstringup to 500 charactersplaceholderstringup to 200 charactersvalidationobject7 attributes
min_lengthinteger0 to 5000text, textarea, email, phone, url.
max_lengthinteger1 to 5000text, textarea, email, phone, url.
minnumber | stringnumber: a number; date, time, datetime: a value of that type; multiselect, checkbox group: a count of choices.
maxnumber | stringAs
min.integerbooleannumber only.
patternstringup to 500 charactersRE2 syntax, matched against the whole value (text, textarea, email, phone, url).
(?i)for any case. A pattern that does not compile is refused.messagestringup to 200 charactersReplaces the default error message.
fileobjectA
filefield's limits.3 attributes
acceptarray of stringup to 30 itemsmax_size_mbinteger1 to 10max_filesinteger1 to 5
consentobjectA
consentfield only, optional: the channel and purpose its box grants (a ledger consent, never required). Show the project's current consent wording (GET /consent/wordings) beside an unticked checkbox namedkeywhose value is the wording version. A ticked box on a post with a phone records aformgrant in the consent ledger with that version's text; a version the project never had is an invalid field. Without it the field is a plain consent: a ticked box (on,true,yesor1) is stored asyes, and it may be required.2 attributes
channelstringrequiredOne of
whatsappsmsvoice_humanpurposestringrequiredOne of
servicemarketing
field_mapobjectWhich submitted fields hold the person's name, email and phone. Defaults:
name,email,phone.3 attributes
namestringemailstringphonestring
retention_daysinteger1 to 3650Days a submission is kept. Default 365.
turnstilestringOne of
offonturnstile_site_keystring | nullturnstile_availablebooleanWhether this deployment can turn Turnstile on (it has Cloudflare credentials).
channelstringrequiredwebsite, orgoogle_lead_formfor a Google lead form connection. Set on create, never changed.One of
websitegoogle_lead_formkeysarray of FormKeyrequired5 attributes
idstringrequiredkeystringrequiredfkey_live_...orfkey_test_...: what the site posts to. Public, like the form's URL.modestringrequiredOne of
livetestexpires_atstring | nullISO 8601 timestampSet on a rotated key: when it stops working.
created_atstringISO 8601 timestamp
archived_atstring | nullISO 8601 timestampWhen the form was archived; null when it is live.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamphealthstringrequiredThe worst open health incident (
GET /v1/forms/health), orok.One of
okwarningcriticalgoogleobject | nullA Google lead form's ownership and arrivals, never its key; null for a website form.
4 attributes
lead_exportstringOne of
brightshoalother_tooloutcome_uploadsstringOne of
nonebrightshoalclient_crmlast_test_atstring | nullISO 8601 timestamplast_lead_atstring | nullISO 8601 timestamp
statsobjectGET /v1/forms/{id}only: live posts by outcome, from hourly counts.2 attributes
last_24hobject4 attributes
acceptedintegerrequiredheldintegerrequiredrefusedintegerrequiredEvery refusal reason, the hourly limit included.
failedintegerrequired
last_7dobject4 attributes
acceptedintegerrequiredheldintegerrequiredrefusedintegerrequiredEvery refusal reason, the hourly limit included.
failedintegerrequired
- 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 "https://api.brightshoal.com/api/forms/FORM_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"status": "active",
"kind": "enquiry",
"unknown_fields": "keep",
"approved_sites": [
"string"
],
"redirect_url": "https://example.com/hook",
"thank_you": {
"title": "Front desk",
"body": "string"
},
"honeypot_field": "string",
"hold_unsure": true,
"fields": [
{
"key": "string",
"label": "string",
"type": "text",
"required": true,
"options": [
"string"
],
"help": "string",
"placeholder": "string",
"validation": {
"min_length": 1,
"max_length": 1,
"min": 1,
"max": 1,
"integer": true,
"pattern": "string",
"message": "Hi, can I book a trip to Lisbon in May?"
},
"file": {
"accept": [
{}
],
"max_size_mb": 1,
"max_files": 1
},
"consent": {
"channel": "whatsapp",
"purpose": "service"
}
}
],
"field_map": {
"name": "Front desk",
"email": "ana@example.com",
"phone": "+14155550123"
},
"retention_days": 1,
"turnstile": "off",
"turnstile_site_key": "string",
"turnstile_available": true,
"channel": "website",
"keys": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"key": "string",
"mode": "live",
"expires_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z"
}
],
"archived_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z",
"health": "ok",
"google": {
"lead_export": "brightshoal",
"outcome_uploads": "none",
"last_test_at": "2026-10-28T09:30:00.000Z",
"last_lead_at": "2026-10-28T09:30:00.000Z"
},
"stats": {
"last_24h": {
"accepted": 1,
"held": 1,
"refused": 1,
"failed": 1
},
"last_7d": {
"accepted": 1,
"held": 1,
"refused": 1,
"failed": 1
}
}
}
}Update a form
PATCH/api/forms/{id}
Change any setting; send at least one. field_map keeps the keys it does not name. turnstile: "on" creates the form's Cloudflare Turnstile widget with its approved sites as hostnames (1 to 10 sites); the widget follows later changes to the sites. An archived form cannot be changed: restore it first. Needs the admin role.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredForm id,
form_....
Request body
namestringup to 200 charactersstatusstringA paused form refuses posts.
One of
activepausedkindstringWhat the form is for. Default
enquiry.newsletterandcareerssubmissions never make leads.One of
enquirycallbacksupportnewslettercareersotherunknown_fieldsstringkeep(default) keeps submitted fields the definition does not name;rejectrefuses the post (unknown). Controls are never fields, and an empty definition never refuses.One of
keeprejectapproved_sitesarray of stringup to 20 itemsHosts a live key accepts posts from (the request's Origin, else its Referer), such as
www.example.com; a URL is reduced to its host. A host also covers its subdomains. Empty: a live key refuses every browser post (403site_not_approved) until a site is added. Test keys skip the check.redirect_urlstring | nulluriWhere a browser goes after a post, unless the post names an approved
_redirect. Null: the hosted thank-you page.thank_youobject | nullThe hosted thank-you page's text.
2 attributes
titlestringup to 200 charactersbodystringup to 2000 characters
honeypot_fieldstringA hidden field only bots fill (default
botcheck): a post that fills it is answered as a success and kept nowhere. It may not be a control's name (_redirect,_page,_referrer,access_key,cf-turnstile-response, anyutm_*, a click id), a defined field's key or a name the field map reads.hold_unsurebooleanHold submissions the spam check is unsure about for review.
fieldsarray of FormFieldup to 50 itemsThe fields the form defines, checked in order: a blank required field is
missing, then the type (invalid), length, range andpattern. A key that names a password, card number or national id is refused. Fields the form does not define are kept (seeunknown_fields). Empty: any fields are accepted.10 attributes
keystringrequiredup to 64 charactersThe field's name in the post.
labelstringup to 200 characterstypestringrequiredOne of
textemailphonetextareaurlnumberdatetimedatetimeselectmultiselectcheckboxconsentfilerequiredbooleanDefault
falseoptionsarray of stringThe values a post may send: required for
selectandmultiselect, optional forcheckbox(a group).helpstringup to 500 charactersplaceholderstringup to 200 charactersvalidationobject7 attributes
min_lengthinteger0 to 5000text, textarea, email, phone, url.
max_lengthinteger1 to 5000text, textarea, email, phone, url.
minnumber | stringnumber: a number; date, time, datetime: a value of that type; multiselect, checkbox group: a count of choices.
maxnumber | stringAs
min.integerbooleannumber only.
patternstringup to 500 charactersRE2 syntax, matched against the whole value (text, textarea, email, phone, url).
(?i)for any case. A pattern that does not compile is refused.messagestringup to 200 charactersReplaces the default error message.
fileobjectA
filefield's limits.3 attributes
acceptarray of stringup to 30 itemsmax_size_mbinteger1 to 10max_filesinteger1 to 5
consentobjectA
consentfield only, optional: the channel and purpose its box grants (a ledger consent, never required). Show the project's current consent wording (GET /consent/wordings) beside an unticked checkbox namedkeywhose value is the wording version. A ticked box on a post with a phone records aformgrant in the consent ledger with that version's text; a version the project never had is an invalid field. Without it the field is a plain consent: a ticked box (on,true,yesor1) is stored asyes, and it may be required.2 attributes
channelstringrequiredOne of
whatsappsmsvoice_humanpurposestringrequiredOne of
servicemarketing
field_mapobjectWhich submitted fields hold the person's name, email and phone. Defaults:
name,email,phone.3 attributes
namestringemailstringphonestring
retention_daysinteger1 to 3650Days a submission is kept. Default 365.
turnstilestringOne of
offon
Returns
200 OK
Response attributes
dataFormrequired26 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequirednamestringrequiredup to 200 charactersstatusstringrequiredA paused form refuses posts.
One of
activepausedkindstringWhat the form is for. Default
enquiry.newsletterandcareerssubmissions never make leads.One of
enquirycallbacksupportnewslettercareersotherunknown_fieldsstringkeep(default) keeps submitted fields the definition does not name;rejectrefuses the post (unknown). Controls are never fields, and an empty definition never refuses.One of
keeprejectapproved_sitesarray of stringup to 20 itemsHosts a live key accepts posts from (the request's Origin, else its Referer), such as
www.example.com; a URL is reduced to its host. A host also covers its subdomains. Empty: a live key refuses every browser post (403site_not_approved) until a site is added. Test keys skip the check.redirect_urlstring | nulluriWhere a browser goes after a post, unless the post names an approved
_redirect. Null: the hosted thank-you page.thank_youobject | nullThe hosted thank-you page's text.
2 attributes
titlestringup to 200 charactersbodystringup to 2000 characters
honeypot_fieldstringA hidden field only bots fill (default
botcheck): a post that fills it is answered as a success and kept nowhere. It may not be a control's name (_redirect,_page,_referrer,access_key,cf-turnstile-response, anyutm_*, a click id), a defined field's key or a name the field map reads.hold_unsurebooleanHold submissions the spam check is unsure about for review.
fieldsarray of FormFieldrequiredup to 50 itemsThe fields the form defines, checked in order: a blank required field is
missing, then the type (invalid), length, range andpattern. A key that names a password, card number or national id is refused. Fields the form does not define are kept (seeunknown_fields). Empty: any fields are accepted.10 attributes
keystringrequiredup to 64 charactersThe field's name in the post.
labelstringup to 200 characterstypestringrequiredOne of
textemailphonetextareaurlnumberdatetimedatetimeselectmultiselectcheckboxconsentfilerequiredbooleanDefault
falseoptionsarray of stringThe values a post may send: required for
selectandmultiselect, optional forcheckbox(a group).helpstringup to 500 charactersplaceholderstringup to 200 charactersvalidationobject7 attributes
min_lengthinteger0 to 5000text, textarea, email, phone, url.
max_lengthinteger1 to 5000text, textarea, email, phone, url.
minnumber | stringnumber: a number; date, time, datetime: a value of that type; multiselect, checkbox group: a count of choices.
maxnumber | stringAs
min.integerbooleannumber only.
patternstringup to 500 charactersRE2 syntax, matched against the whole value (text, textarea, email, phone, url).
(?i)for any case. A pattern that does not compile is refused.messagestringup to 200 charactersReplaces the default error message.
fileobjectA
filefield's limits.3 attributes
acceptarray of stringup to 30 itemsmax_size_mbinteger1 to 10max_filesinteger1 to 5
consentobjectA
consentfield only, optional: the channel and purpose its box grants (a ledger consent, never required). Show the project's current consent wording (GET /consent/wordings) beside an unticked checkbox namedkeywhose value is the wording version. A ticked box on a post with a phone records aformgrant in the consent ledger with that version's text; a version the project never had is an invalid field. Without it the field is a plain consent: a ticked box (on,true,yesor1) is stored asyes, and it may be required.2 attributes
channelstringrequiredOne of
whatsappsmsvoice_humanpurposestringrequiredOne of
servicemarketing
field_mapobjectWhich submitted fields hold the person's name, email and phone. Defaults:
name,email,phone.3 attributes
namestringemailstringphonestring
retention_daysinteger1 to 3650Days a submission is kept. Default 365.
turnstilestringOne of
offonturnstile_site_keystring | nullturnstile_availablebooleanWhether this deployment can turn Turnstile on (it has Cloudflare credentials).
channelstringrequiredwebsite, orgoogle_lead_formfor a Google lead form connection. Set on create, never changed.One of
websitegoogle_lead_formkeysarray of FormKeyrequired5 attributes
idstringrequiredkeystringrequiredfkey_live_...orfkey_test_...: what the site posts to. Public, like the form's URL.modestringrequiredOne of
livetestexpires_atstring | nullISO 8601 timestampSet on a rotated key: when it stops working.
created_atstringISO 8601 timestamp
archived_atstring | nullISO 8601 timestampWhen the form was archived; null when it is live.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamphealthstringrequiredThe worst open health incident (
GET /v1/forms/health), orok.One of
okwarningcriticalgoogleobject | nullA Google lead form's ownership and arrivals, never its key; null for a website form.
4 attributes
lead_exportstringOne of
brightshoalother_tooloutcome_uploadsstringOne of
nonebrightshoalclient_crmlast_test_atstring | nullISO 8601 timestamplast_lead_atstring | nullISO 8601 timestamp
statsobjectGET /v1/forms/{id}only: live posts by outcome, from hourly counts.2 attributes
last_24hobject4 attributes
acceptedintegerrequiredheldintegerrequiredrefusedintegerrequiredEvery refusal reason, the hourly limit included.
failedintegerrequired
last_7dobject4 attributes
acceptedintegerrequiredheldintegerrequiredrefusedintegerrequiredEvery refusal reason, the hourly limit included.
failedintegerrequired
- 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
form_archived: restore the form first.turnstile_not_configured: this deployment has no Cloudflare credentials for Turnstile. - 422
turnstile_needs_sitesorturnstile_too_many_sites. - 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). - 502
turnstile_unavailable: Cloudflare refused or did not answer.
curl -X PATCH "https://api.brightshoal.com/api/forms/FORM_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Front desk",
"status": "active"
}'{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"status": "active",
"kind": "enquiry",
"unknown_fields": "keep",
"approved_sites": [
"string"
],
"redirect_url": "https://example.com/hook",
"thank_you": {
"title": "Front desk",
"body": "string"
},
"honeypot_field": "string",
"hold_unsure": true,
"fields": [
{
"key": "string",
"label": "string",
"type": "text",
"required": true,
"options": [
"string"
],
"help": "string",
"placeholder": "string",
"validation": {
"min_length": 1,
"max_length": 1,
"min": 1,
"max": 1,
"integer": true,
"pattern": "string",
"message": "Hi, can I book a trip to Lisbon in May?"
},
"file": {
"accept": [
{}
],
"max_size_mb": 1,
"max_files": 1
},
"consent": {
"channel": "whatsapp",
"purpose": "service"
}
}
],
"field_map": {
"name": "Front desk",
"email": "ana@example.com",
"phone": "+14155550123"
},
"retention_days": 1,
"turnstile": "off",
"turnstile_site_key": "string",
"turnstile_available": true,
"channel": "website",
"keys": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"key": "string",
"mode": "live",
"expires_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z"
}
],
"archived_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z",
"health": "ok",
"google": {
"lead_export": "brightshoal",
"outcome_uploads": "none",
"last_test_at": "2026-10-28T09:30:00.000Z",
"last_lead_at": "2026-10-28T09:30:00.000Z"
},
"stats": {
"last_24h": {
"accepted": 1,
"held": 1,
"refused": 1,
"failed": 1
},
"last_7d": {
"accepted": 1,
"held": 1,
"refused": 1,
"failed": 1
}
}
}
}Send a submission from a server
POST/api/forms/{id}/submissions
For a server that collected the form itself: the same field checks, sensitive drop, normalisation, kind and spam check as POST /public/forms/{key}, without the approved sites, Turnstile, the per-address limits or the missing Origin signal. 600 an hour per form; a repeat within 10 minutes answers with the first receipt. JSON only, at most 64 KiB; no files. Needs the admin role, or any API key that may write (not a viewer key).
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredForm id,
form_....
Request body
fieldsobjectrequiredName to value; a number or boolean is kept as text, a list joined with ", ", a null left out.
modestringOne of
livetestDefault
"live"page_urlstringup to 2000 charactersreferrerstringup to 2000 charactersutmobjectclick_idsobjectcontextobjectThe
_mlfobject fromforms.js, if the server has it.
Returns
201 Stored.
Response attributes
successtruerequiredsubmission_idstringrequiredlead_idstring | nullrequiredThe lead it made. Null when held, when the form's kind makes no leads, or when there was nothing to make one from. Final: the lead is written with the submission.
statusstringrequiredOne of
acceptedheldreleased
- 400
invalid_fields(withfields) orinvalid_request. - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403
form_archivedorform_paused, or the key may not write. - 404 Not found, or outside what the key can see
- 413
body_too_large. - 429
rate_limited: waitRetry-Afterseconds.
curl -X POST "https://api.brightshoal.com/api/forms/FORM_ID/submissions" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"fields": {
"key": "string"
}
}'{
"success": true,
"submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"lead_id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"status": "accepted"
}List a form's submissions
GET/api/forms/{id}/submissions
Newest first. Page with cursor: pass the previous page's next_cursor, null on the last page. Archived submissions are left out unless archived=true.
Secret API key. How it works
Path parameters
idstringrequiredForm id,
form_....
Query parameters
archivedbooleantrue: only archived submissions. Absent: only live ones.statusstringOnly submissions in this state (
held: waiting for review). Absent: any.One of
acceptedheldreleasedcursorstringOpaque
next_cursorfrom the previous page. Keep the same filters while paging.beforestringISO 8601 timestampOnly submissions received before this time. Kept for older callers: rows received in the same instant as a page's last can be skipped; use
cursor.limitinteger1 to 200Default
50
Returns
200 OK
Response attributes
dataarray of FormSubmissionrequired24 attributes
idstringrequiredorg_idstringproject_idstringform_idstringrequiredkey_idstring | nullmodestringrequiredOne of
liveteststatusstringrequiredOne of
acceptedheldreleaseddiscardedspam_reasonstring | nullWhy the spam check was unsure, comma-separated:
links,disposable_email,markup,not_text,no_origin. Null when it found nothing.fieldsobjectrequiredpage_urlstring | nullreferrerstring | nullutmobject | nullclick_idsobject | nulloriginstring | nullcountrystring | nullISO 3166-1 alpha-2, from the edge.
dropped_fieldsarray of stringKeys not stored: they named or held a password, card number or national id, or carried a file the form does not define.
consentsarray of object | nullConsent fields ticked, with the wording (the field's label) agreed to.
3 attributes
keystringwordingstringatstringISO 8601 timestamp
contextobject | nullThe page context
forms.jssent (_mlf), or a server'scontext.lead_idstring | nullThe lead it made, if any.
filesarray of objectIts files; download one with
GET /v1/forms/{id}/submissions/{sid}/files/{fileId}.6 attributes
idstringrequiredfield_keystringrequiredfilenamestringrequiredcontent_typestringrequiredThe type its bytes were sniffed as.
size_bytesintegerrequiredscan_statusstringrequiredIts malware scan:
pending(downloads answer 409 until it is done, usually seconds),clean,infected(deleted; downloads answer 410),unscannable(the scanner could not read it: served, unscanned) ornot_scanned(stored while scanning was off).One of
pendingcleaninfectedunscannablenot_scanned
archived_atstring | nullISO 8601 timestampWhen the submission was archived; null when it is live.
external_idstring | nullGoogle's
lead_idfor a Google lead form's lead; null for a website post.adobject | nullThe ids Google sent with a Google lead form's lead (
platform,lead_id,form_id,campaign_id,adgroup_id,creative_id,asset_group_id,gcl_id,lead_source,lead_stage,submitted_at), withcapture_conversion: false: Google already counted it. Null for a website post.received_atstringrequiredISO 8601 timestamp
next_cursorstring | nullrequired
- 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 "https://api.brightshoal.com/api/forms/FORM_ID/submissions" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"form_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"key_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"mode": "live",
"status": "accepted",
"spam_reason": "string",
"fields": {
"key": "string"
},
"page_url": "https://example.com/hook",
"referrer": "string",
"utm": {
"key": "string"
},
"click_ids": {
"key": "string"
},
"origin": "https://www.example.com",
"country": "string",
"dropped_fields": [
"string"
],
"consents": [
{
"key": "string",
"wording": "string",
"at": "2026-10-28T09:30:00.000Z"
}
],
"context": {},
"lead_id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"files": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"field_key": "string",
"filename": "string",
"content_type": "string",
"size_bytes": 1,
"scan_status": "pending"
}
],
"archived_at": "2026-10-28T09:30:00.000Z",
"external_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"ad": {},
"received_at": "2026-10-28T09:30:00.000Z"
}
],
"next_cursor": "eyJ0IjoiMjAyNi0xMC0yOCJ9"
}Delete an archived form
DELETE/api/forms/{id}
Permanent: deletes the form, its keys, its Turnstile widget and its submissions with their files (the files first; 503 files_not_deleted when one could not be: the rows are kept, and a retry finishes). Leads made from them stay. Only an archived form can be deleted: 409 not_archived otherwise. Needs the admin role; audited.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredForm id,
form_....
Returns
200 OK
Response attributes
dataDeleteResultrequired2 attributes
idstringrequireddeletedbooleanrequired
- 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
not_archived: archive the form first. - 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). - 503
files_not_deleted: try again shortly.
curl -X DELETE "https://api.brightshoal.com/api/forms/FORM_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"deleted": true
}
}Archive a form
POST/api/forms/{id}/archive
Its keys stop accepting posts (403 form_archived) and it leaves the forms list. Nothing is deleted: its keys, Turnstile widget, submissions, files and leads all stay, and it can be restored (or then deleted for good). Archiving an archived form is a no-op. Needs the admin role; audited.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredForm id,
form_....
Returns
200 OK
Response attributes
dataFormrequired26 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequirednamestringrequiredup to 200 charactersstatusstringrequiredA paused form refuses posts.
One of
activepausedkindstringWhat the form is for. Default
enquiry.newsletterandcareerssubmissions never make leads.One of
enquirycallbacksupportnewslettercareersotherunknown_fieldsstringkeep(default) keeps submitted fields the definition does not name;rejectrefuses the post (unknown). Controls are never fields, and an empty definition never refuses.One of
keeprejectapproved_sitesarray of stringup to 20 itemsHosts a live key accepts posts from (the request's Origin, else its Referer), such as
www.example.com; a URL is reduced to its host. A host also covers its subdomains. Empty: a live key refuses every browser post (403site_not_approved) until a site is added. Test keys skip the check.redirect_urlstring | nulluriWhere a browser goes after a post, unless the post names an approved
_redirect. Null: the hosted thank-you page.thank_youobject | nullThe hosted thank-you page's text.
2 attributes
titlestringup to 200 charactersbodystringup to 2000 characters
honeypot_fieldstringA hidden field only bots fill (default
botcheck): a post that fills it is answered as a success and kept nowhere. It may not be a control's name (_redirect,_page,_referrer,access_key,cf-turnstile-response, anyutm_*, a click id), a defined field's key or a name the field map reads.hold_unsurebooleanHold submissions the spam check is unsure about for review.
fieldsarray of FormFieldrequiredup to 50 itemsThe fields the form defines, checked in order: a blank required field is
missing, then the type (invalid), length, range andpattern. A key that names a password, card number or national id is refused. Fields the form does not define are kept (seeunknown_fields). Empty: any fields are accepted.10 attributes
keystringrequiredup to 64 charactersThe field's name in the post.
labelstringup to 200 characterstypestringrequiredOne of
textemailphonetextareaurlnumberdatetimedatetimeselectmultiselectcheckboxconsentfilerequiredbooleanDefault
falseoptionsarray of stringThe values a post may send: required for
selectandmultiselect, optional forcheckbox(a group).helpstringup to 500 charactersplaceholderstringup to 200 charactersvalidationobject7 attributes
min_lengthinteger0 to 5000text, textarea, email, phone, url.
max_lengthinteger1 to 5000text, textarea, email, phone, url.
minnumber | stringnumber: a number; date, time, datetime: a value of that type; multiselect, checkbox group: a count of choices.
maxnumber | stringAs
min.integerbooleannumber only.
patternstringup to 500 charactersRE2 syntax, matched against the whole value (text, textarea, email, phone, url).
(?i)for any case. A pattern that does not compile is refused.messagestringup to 200 charactersReplaces the default error message.
fileobjectA
filefield's limits.3 attributes
acceptarray of stringup to 30 itemsmax_size_mbinteger1 to 10max_filesinteger1 to 5
consentobjectA
consentfield only, optional: the channel and purpose its box grants (a ledger consent, never required). Show the project's current consent wording (GET /consent/wordings) beside an unticked checkbox namedkeywhose value is the wording version. A ticked box on a post with a phone records aformgrant in the consent ledger with that version's text; a version the project never had is an invalid field. Without it the field is a plain consent: a ticked box (on,true,yesor1) is stored asyes, and it may be required.2 attributes
channelstringrequiredOne of
whatsappsmsvoice_humanpurposestringrequiredOne of
servicemarketing
field_mapobjectWhich submitted fields hold the person's name, email and phone. Defaults:
name,email,phone.3 attributes
namestringemailstringphonestring
retention_daysinteger1 to 3650Days a submission is kept. Default 365.
turnstilestringOne of
offonturnstile_site_keystring | nullturnstile_availablebooleanWhether this deployment can turn Turnstile on (it has Cloudflare credentials).
channelstringrequiredwebsite, orgoogle_lead_formfor a Google lead form connection. Set on create, never changed.One of
websitegoogle_lead_formkeysarray of FormKeyrequired5 attributes
idstringrequiredkeystringrequiredfkey_live_...orfkey_test_...: what the site posts to. Public, like the form's URL.modestringrequiredOne of
livetestexpires_atstring | nullISO 8601 timestampSet on a rotated key: when it stops working.
created_atstringISO 8601 timestamp
archived_atstring | nullISO 8601 timestampWhen the form was archived; null when it is live.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamphealthstringrequiredThe worst open health incident (
GET /v1/forms/health), orok.One of
okwarningcriticalgoogleobject | nullA Google lead form's ownership and arrivals, never its key; null for a website form.
4 attributes
lead_exportstringOne of
brightshoalother_tooloutcome_uploadsstringOne of
nonebrightshoalclient_crmlast_test_atstring | nullISO 8601 timestamplast_lead_atstring | nullISO 8601 timestamp
statsobjectGET /v1/forms/{id}only: live posts by outcome, from hourly counts.2 attributes
last_24hobject4 attributes
acceptedintegerrequiredheldintegerrequiredrefusedintegerrequiredEvery refusal reason, the hourly limit included.
failedintegerrequired
last_7dobject4 attributes
acceptedintegerrequiredheldintegerrequiredrefusedintegerrequiredEvery refusal reason, the hourly limit included.
failedintegerrequired
- 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 POST "https://api.brightshoal.com/api/forms/FORM_ID/archive" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"status": "active",
"kind": "enquiry",
"unknown_fields": "keep",
"approved_sites": [
"string"
],
"redirect_url": "https://example.com/hook",
"thank_you": {
"title": "Front desk",
"body": "string"
},
"honeypot_field": "string",
"hold_unsure": true,
"fields": [
{
"key": "string",
"label": "string",
"type": "text",
"required": true,
"options": [
"string"
],
"help": "string",
"placeholder": "string",
"validation": {
"min_length": 1,
"max_length": 1,
"min": 1,
"max": 1,
"integer": true,
"pattern": "string",
"message": "Hi, can I book a trip to Lisbon in May?"
},
"file": {
"accept": [
{}
],
"max_size_mb": 1,
"max_files": 1
},
"consent": {
"channel": "whatsapp",
"purpose": "service"
}
}
],
"field_map": {
"name": "Front desk",
"email": "ana@example.com",
"phone": "+14155550123"
},
"retention_days": 1,
"turnstile": "off",
"turnstile_site_key": "string",
"turnstile_available": true,
"channel": "website",
"keys": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"key": "string",
"mode": "live",
"expires_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z"
}
],
"archived_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z",
"health": "ok",
"google": {
"lead_export": "brightshoal",
"outcome_uploads": "none",
"last_test_at": "2026-10-28T09:30:00.000Z",
"last_lead_at": "2026-10-28T09:30:00.000Z"
},
"stats": {
"last_24h": {
"accepted": 1,
"held": 1,
"refused": 1,
"failed": 1
},
"last_7d": {
"accepted": 1,
"held": 1,
"refused": 1,
"failed": 1
}
}
}
}Get a Google lead form's setup
GET/api/forms/{id}/google
The webhook URLs and the Google key to paste into the Google Ads lead form, the question id overrides, who exports and uploads, and what has arrived. 404 for a website form. Needs the admin role.
Secret API key. How it works
Path parameters
idstringrequiredForm id,
form_....
Returns
200 OK
Response attributes
dataFormGoogleSetuprequired10 attributes
webhook_urlstring | nullrequiredThe live key's URL, for the Google Ads lead form; null with no live key or no public origin configured.
test_webhook_urlstring | nullrequiredThe test key's URL: every lead it gets is a test lead.
google_keystringrequiredgk_...: the key Google Ads sends with each lead. A secret.previous_key_expires_atstring | nullISO 8601 timestampAfter a rotation: when the old key stops working.
column_mapobjectrequiredGoogle question id to field key, overrides only.
lead_exportstringrequiredOne of
brightshoalother_tooloutcome_uploadsstringrequiredOne of
nonebrightshoalclient_crmgoogle_form_idsarray of stringGoogle lead form ids seen on live leads, at most 50.
last_test_atstring | nullISO 8601 timestamplast_lead_atstring | nullISO 8601 timestamp
- 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 "https://api.brightshoal.com/api/forms/FORM_ID/google" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"webhook_url": "https://example.com/hook",
"test_webhook_url": "https://example.com/hook",
"google_key": "string",
"previous_key_expires_at": "2026-10-28T09:30:00.000Z",
"column_map": {
"key": "string"
},
"lead_export": "brightshoal",
"outcome_uploads": "none",
"google_form_ids": [
"id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
],
"last_test_at": "2026-10-28T09:30:00.000Z",
"last_lead_at": "2026-10-28T09:30:00.000Z"
}
}Update a Google lead form's setup
PATCH/api/forms/{id}/google
The question id overrides and who exports and uploads (recorded, not enforced). Needs the admin role; audited.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredForm id,
form_....
Request body
column_mapobjectReplaces the overrides: Google question id to field key.
lead_exportstringWho exports these leads.
One of
brightshoalother_tooloutcome_uploadsstringWho uploads later outcomes to Google. Brightshoal uploads nothing yet.
One of
nonebrightshoalclient_crm
Returns
200 OK
Response attributes
dataFormGoogleSetuprequired10 attributes
webhook_urlstring | nullrequiredThe live key's URL, for the Google Ads lead form; null with no live key or no public origin configured.
test_webhook_urlstring | nullrequiredThe test key's URL: every lead it gets is a test lead.
google_keystringrequiredgk_...: the key Google Ads sends with each lead. A secret.previous_key_expires_atstring | nullISO 8601 timestampAfter a rotation: when the old key stops working.
column_mapobjectrequiredGoogle question id to field key, overrides only.
lead_exportstringrequiredOne of
brightshoalother_tooloutcome_uploadsstringrequiredOne of
nonebrightshoalclient_crmgoogle_form_idsarray of stringGoogle lead form ids seen on live leads, at most 50.
last_test_atstring | nullISO 8601 timestamplast_lead_atstring | nullISO 8601 timestamp
- 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
form_archived: restore the form first. - 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/forms/FORM_ID/google" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"column_map": {
"key": "string"
},
"lead_export": "brightshoal"
}'{
"data": {
"webhook_url": "https://example.com/hook",
"test_webhook_url": "https://example.com/hook",
"google_key": "string",
"previous_key_expires_at": "2026-10-28T09:30:00.000Z",
"column_map": {
"key": "string"
},
"lead_export": "brightshoal",
"outcome_uploads": "none",
"google_form_ids": [
"id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
],
"last_test_at": "2026-10-28T09:30:00.000Z",
"last_lead_at": "2026-10-28T09:30:00.000Z"
}
}Rotate a Google lead form's key
POST/api/forms/{id}/google/rotate-key
A new Google key; the old one keeps working for 7 days, so the Google Ads lead form can be updated. Needs the admin role; audited.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredForm id,
form_....
Returns
200 OK
Response attributes
dataFormGoogleSetuprequired10 attributes
webhook_urlstring | nullrequiredThe live key's URL, for the Google Ads lead form; null with no live key or no public origin configured.
test_webhook_urlstring | nullrequiredThe test key's URL: every lead it gets is a test lead.
google_keystringrequiredgk_...: the key Google Ads sends with each lead. A secret.previous_key_expires_atstring | nullISO 8601 timestampAfter a rotation: when the old key stops working.
column_mapobjectrequiredGoogle question id to field key, overrides only.
lead_exportstringrequiredOne of
brightshoalother_tooloutcome_uploadsstringrequiredOne of
nonebrightshoalclient_crmgoogle_form_idsarray of stringGoogle lead form ids seen on live leads, at most 50.
last_test_atstring | nullISO 8601 timestamplast_lead_atstring | nullISO 8601 timestamp
- 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
form_archived: restore the form first. - 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/forms/FORM_ID/google/rotate-key" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"webhook_url": "https://example.com/hook",
"test_webhook_url": "https://example.com/hook",
"google_key": "string",
"previous_key_expires_at": "2026-10-28T09:30:00.000Z",
"column_map": {
"key": "string"
},
"lead_export": "brightshoal",
"outcome_uploads": "none",
"google_form_ids": [
"id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
],
"last_test_at": "2026-10-28T09:30:00.000Z",
"last_lead_at": "2026-10-28T09:30:00.000Z"
}
}Revoke a form key
POST/api/forms/{id}/keys/{keyId}/revoke
Stops the key at once, for a key that leaked. Needs the admin role.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredForm id,
form_....keyIdstringrequiredThe key's id.
Returns
200 OK
Response attributes
dataFormrequired26 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequirednamestringrequiredup to 200 charactersstatusstringrequiredA paused form refuses posts.
One of
activepausedkindstringWhat the form is for. Default
enquiry.newsletterandcareerssubmissions never make leads.One of
enquirycallbacksupportnewslettercareersotherunknown_fieldsstringkeep(default) keeps submitted fields the definition does not name;rejectrefuses the post (unknown). Controls are never fields, and an empty definition never refuses.One of
keeprejectapproved_sitesarray of stringup to 20 itemsHosts a live key accepts posts from (the request's Origin, else its Referer), such as
www.example.com; a URL is reduced to its host. A host also covers its subdomains. Empty: a live key refuses every browser post (403site_not_approved) until a site is added. Test keys skip the check.redirect_urlstring | nulluriWhere a browser goes after a post, unless the post names an approved
_redirect. Null: the hosted thank-you page.thank_youobject | nullThe hosted thank-you page's text.
2 attributes
titlestringup to 200 charactersbodystringup to 2000 characters
honeypot_fieldstringA hidden field only bots fill (default
botcheck): a post that fills it is answered as a success and kept nowhere. It may not be a control's name (_redirect,_page,_referrer,access_key,cf-turnstile-response, anyutm_*, a click id), a defined field's key or a name the field map reads.hold_unsurebooleanHold submissions the spam check is unsure about for review.
fieldsarray of FormFieldrequiredup to 50 itemsThe fields the form defines, checked in order: a blank required field is
missing, then the type (invalid), length, range andpattern. A key that names a password, card number or national id is refused. Fields the form does not define are kept (seeunknown_fields). Empty: any fields are accepted.10 attributes
keystringrequiredup to 64 charactersThe field's name in the post.
labelstringup to 200 characterstypestringrequiredOne of
textemailphonetextareaurlnumberdatetimedatetimeselectmultiselectcheckboxconsentfilerequiredbooleanDefault
falseoptionsarray of stringThe values a post may send: required for
selectandmultiselect, optional forcheckbox(a group).helpstringup to 500 charactersplaceholderstringup to 200 charactersvalidationobject7 attributes
min_lengthinteger0 to 5000text, textarea, email, phone, url.
max_lengthinteger1 to 5000text, textarea, email, phone, url.
minnumber | stringnumber: a number; date, time, datetime: a value of that type; multiselect, checkbox group: a count of choices.
maxnumber | stringAs
min.integerbooleannumber only.
patternstringup to 500 charactersRE2 syntax, matched against the whole value (text, textarea, email, phone, url).
(?i)for any case. A pattern that does not compile is refused.messagestringup to 200 charactersReplaces the default error message.
fileobjectA
filefield's limits.3 attributes
acceptarray of stringup to 30 itemsmax_size_mbinteger1 to 10max_filesinteger1 to 5
consentobjectA
consentfield only, optional: the channel and purpose its box grants (a ledger consent, never required). Show the project's current consent wording (GET /consent/wordings) beside an unticked checkbox namedkeywhose value is the wording version. A ticked box on a post with a phone records aformgrant in the consent ledger with that version's text; a version the project never had is an invalid field. Without it the field is a plain consent: a ticked box (on,true,yesor1) is stored asyes, and it may be required.2 attributes
channelstringrequiredOne of
whatsappsmsvoice_humanpurposestringrequiredOne of
servicemarketing
field_mapobjectWhich submitted fields hold the person's name, email and phone. Defaults:
name,email,phone.3 attributes
namestringemailstringphonestring
retention_daysinteger1 to 3650Days a submission is kept. Default 365.
turnstilestringOne of
offonturnstile_site_keystring | nullturnstile_availablebooleanWhether this deployment can turn Turnstile on (it has Cloudflare credentials).
channelstringrequiredwebsite, orgoogle_lead_formfor a Google lead form connection. Set on create, never changed.One of
websitegoogle_lead_formkeysarray of FormKeyrequired5 attributes
idstringrequiredkeystringrequiredfkey_live_...orfkey_test_...: what the site posts to. Public, like the form's URL.modestringrequiredOne of
livetestexpires_atstring | nullISO 8601 timestampSet on a rotated key: when it stops working.
created_atstringISO 8601 timestamp
archived_atstring | nullISO 8601 timestampWhen the form was archived; null when it is live.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamphealthstringrequiredThe worst open health incident (
GET /v1/forms/health), orok.One of
okwarningcriticalgoogleobject | nullA Google lead form's ownership and arrivals, never its key; null for a website form.
4 attributes
lead_exportstringOne of
brightshoalother_tooloutcome_uploadsstringOne of
nonebrightshoalclient_crmlast_test_atstring | nullISO 8601 timestamplast_lead_atstring | nullISO 8601 timestamp
statsobjectGET /v1/forms/{id}only: live posts by outcome, from hourly counts.2 attributes
last_24hobject4 attributes
acceptedintegerrequiredheldintegerrequiredrefusedintegerrequiredEvery refusal reason, the hourly limit included.
failedintegerrequired
last_7dobject4 attributes
acceptedintegerrequiredheldintegerrequiredrefusedintegerrequiredEvery refusal reason, the hourly limit included.
failedintegerrequired
- 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 POST "https://api.brightshoal.com/api/forms/FORM_ID/keys/KEY_ID/revoke" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"status": "active",
"kind": "enquiry",
"unknown_fields": "keep",
"approved_sites": [
"string"
],
"redirect_url": "https://example.com/hook",
"thank_you": {
"title": "Front desk",
"body": "string"
},
"honeypot_field": "string",
"hold_unsure": true,
"fields": [
{
"key": "string",
"label": "string",
"type": "text",
"required": true,
"options": [
"string"
],
"help": "string",
"placeholder": "string",
"validation": {
"min_length": 1,
"max_length": 1,
"min": 1,
"max": 1,
"integer": true,
"pattern": "string",
"message": "Hi, can I book a trip to Lisbon in May?"
},
"file": {
"accept": [
{}
],
"max_size_mb": 1,
"max_files": 1
},
"consent": {
"channel": "whatsapp",
"purpose": "service"
}
}
],
"field_map": {
"name": "Front desk",
"email": "ana@example.com",
"phone": "+14155550123"
},
"retention_days": 1,
"turnstile": "off",
"turnstile_site_key": "string",
"turnstile_available": true,
"channel": "website",
"keys": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"key": "string",
"mode": "live",
"expires_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z"
}
],
"archived_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z",
"health": "ok",
"google": {
"lead_export": "brightshoal",
"outcome_uploads": "none",
"last_test_at": "2026-10-28T09:30:00.000Z",
"last_lead_at": "2026-10-28T09:30:00.000Z"
},
"stats": {
"last_24h": {
"accepted": 1,
"held": 1,
"refused": 1,
"failed": 1
},
"last_7d": {
"accepted": 1,
"held": 1,
"refused": 1,
"failed": 1
}
}
}
}Rotate a form key
POST/api/forms/{id}/keys/rotate
Issues a new key of this mode. The current one keeps working for 7 days, so the site can be updated first; with grace: false it stops at once. Needs the admin role.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredForm id,
form_....
Request body
modestringrequiredOne of
livetestgracebooleanFalse stops the current key at once instead of after 7 days.
Returns
200 OK
Response attributes
dataFormrequired26 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequirednamestringrequiredup to 200 charactersstatusstringrequiredA paused form refuses posts.
One of
activepausedkindstringWhat the form is for. Default
enquiry.newsletterandcareerssubmissions never make leads.One of
enquirycallbacksupportnewslettercareersotherunknown_fieldsstringkeep(default) keeps submitted fields the definition does not name;rejectrefuses the post (unknown). Controls are never fields, and an empty definition never refuses.One of
keeprejectapproved_sitesarray of stringup to 20 itemsHosts a live key accepts posts from (the request's Origin, else its Referer), such as
www.example.com; a URL is reduced to its host. A host also covers its subdomains. Empty: a live key refuses every browser post (403site_not_approved) until a site is added. Test keys skip the check.redirect_urlstring | nulluriWhere a browser goes after a post, unless the post names an approved
_redirect. Null: the hosted thank-you page.thank_youobject | nullThe hosted thank-you page's text.
2 attributes
titlestringup to 200 charactersbodystringup to 2000 characters
honeypot_fieldstringA hidden field only bots fill (default
botcheck): a post that fills it is answered as a success and kept nowhere. It may not be a control's name (_redirect,_page,_referrer,access_key,cf-turnstile-response, anyutm_*, a click id), a defined field's key or a name the field map reads.hold_unsurebooleanHold submissions the spam check is unsure about for review.
fieldsarray of FormFieldrequiredup to 50 itemsThe fields the form defines, checked in order: a blank required field is
missing, then the type (invalid), length, range andpattern. A key that names a password, card number or national id is refused. Fields the form does not define are kept (seeunknown_fields). Empty: any fields are accepted.10 attributes
keystringrequiredup to 64 charactersThe field's name in the post.
labelstringup to 200 characterstypestringrequiredOne of
textemailphonetextareaurlnumberdatetimedatetimeselectmultiselectcheckboxconsentfilerequiredbooleanDefault
falseoptionsarray of stringThe values a post may send: required for
selectandmultiselect, optional forcheckbox(a group).helpstringup to 500 charactersplaceholderstringup to 200 charactersvalidationobject7 attributes
min_lengthinteger0 to 5000text, textarea, email, phone, url.
max_lengthinteger1 to 5000text, textarea, email, phone, url.
minnumber | stringnumber: a number; date, time, datetime: a value of that type; multiselect, checkbox group: a count of choices.
maxnumber | stringAs
min.integerbooleannumber only.
patternstringup to 500 charactersRE2 syntax, matched against the whole value (text, textarea, email, phone, url).
(?i)for any case. A pattern that does not compile is refused.messagestringup to 200 charactersReplaces the default error message.
fileobjectA
filefield's limits.3 attributes
acceptarray of stringup to 30 itemsmax_size_mbinteger1 to 10max_filesinteger1 to 5
consentobjectA
consentfield only, optional: the channel and purpose its box grants (a ledger consent, never required). Show the project's current consent wording (GET /consent/wordings) beside an unticked checkbox namedkeywhose value is the wording version. A ticked box on a post with a phone records aformgrant in the consent ledger with that version's text; a version the project never had is an invalid field. Without it the field is a plain consent: a ticked box (on,true,yesor1) is stored asyes, and it may be required.2 attributes
channelstringrequiredOne of
whatsappsmsvoice_humanpurposestringrequiredOne of
servicemarketing
field_mapobjectWhich submitted fields hold the person's name, email and phone. Defaults:
name,email,phone.3 attributes
namestringemailstringphonestring
retention_daysinteger1 to 3650Days a submission is kept. Default 365.
turnstilestringOne of
offonturnstile_site_keystring | nullturnstile_availablebooleanWhether this deployment can turn Turnstile on (it has Cloudflare credentials).
channelstringrequiredwebsite, orgoogle_lead_formfor a Google lead form connection. Set on create, never changed.One of
websitegoogle_lead_formkeysarray of FormKeyrequired5 attributes
idstringrequiredkeystringrequiredfkey_live_...orfkey_test_...: what the site posts to. Public, like the form's URL.modestringrequiredOne of
livetestexpires_atstring | nullISO 8601 timestampSet on a rotated key: when it stops working.
created_atstringISO 8601 timestamp
archived_atstring | nullISO 8601 timestampWhen the form was archived; null when it is live.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamphealthstringrequiredThe worst open health incident (
GET /v1/forms/health), orok.One of
okwarningcriticalgoogleobject | nullA Google lead form's ownership and arrivals, never its key; null for a website form.
4 attributes
lead_exportstringOne of
brightshoalother_tooloutcome_uploadsstringOne of
nonebrightshoalclient_crmlast_test_atstring | nullISO 8601 timestamplast_lead_atstring | nullISO 8601 timestamp
statsobjectGET /v1/forms/{id}only: live posts by outcome, from hourly counts.2 attributes
last_24hobject4 attributes
acceptedintegerrequiredheldintegerrequiredrefusedintegerrequiredEvery refusal reason, the hourly limit included.
failedintegerrequired
last_7dobject4 attributes
acceptedintegerrequiredheldintegerrequiredrefusedintegerrequiredEvery refusal reason, the hourly limit included.
failedintegerrequired
- 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
form_archived: restore the form first. - 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/forms/FORM_ID/keys/rotate" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "live"
}'{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"status": "active",
"kind": "enquiry",
"unknown_fields": "keep",
"approved_sites": [
"string"
],
"redirect_url": "https://example.com/hook",
"thank_you": {
"title": "Front desk",
"body": "string"
},
"honeypot_field": "string",
"hold_unsure": true,
"fields": [
{
"key": "string",
"label": "string",
"type": "text",
"required": true,
"options": [
"string"
],
"help": "string",
"placeholder": "string",
"validation": {
"min_length": 1,
"max_length": 1,
"min": 1,
"max": 1,
"integer": true,
"pattern": "string",
"message": "Hi, can I book a trip to Lisbon in May?"
},
"file": {
"accept": [
{}
],
"max_size_mb": 1,
"max_files": 1
},
"consent": {
"channel": "whatsapp",
"purpose": "service"
}
}
],
"field_map": {
"name": "Front desk",
"email": "ana@example.com",
"phone": "+14155550123"
},
"retention_days": 1,
"turnstile": "off",
"turnstile_site_key": "string",
"turnstile_available": true,
"channel": "website",
"keys": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"key": "string",
"mode": "live",
"expires_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z"
}
],
"archived_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z",
"health": "ok",
"google": {
"lead_export": "brightshoal",
"outcome_uploads": "none",
"last_test_at": "2026-10-28T09:30:00.000Z",
"last_lead_at": "2026-10-28T09:30:00.000Z"
},
"stats": {
"last_24h": {
"accepted": 1,
"held": 1,
"refused": 1,
"failed": 1
},
"last_7d": {
"accepted": 1,
"held": 1,
"refused": 1,
"failed": 1
}
}
}
}Restore an archived form
POST/api/forms/{id}/restore
Its keys accept posts again. Restoring a live form is a no-op. Needs the admin role; audited.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredForm id,
form_....
Returns
200 OK
Response attributes
dataFormrequired26 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequirednamestringrequiredup to 200 charactersstatusstringrequiredA paused form refuses posts.
One of
activepausedkindstringWhat the form is for. Default
enquiry.newsletterandcareerssubmissions never make leads.One of
enquirycallbacksupportnewslettercareersotherunknown_fieldsstringkeep(default) keeps submitted fields the definition does not name;rejectrefuses the post (unknown). Controls are never fields, and an empty definition never refuses.One of
keeprejectapproved_sitesarray of stringup to 20 itemsHosts a live key accepts posts from (the request's Origin, else its Referer), such as
www.example.com; a URL is reduced to its host. A host also covers its subdomains. Empty: a live key refuses every browser post (403site_not_approved) until a site is added. Test keys skip the check.redirect_urlstring | nulluriWhere a browser goes after a post, unless the post names an approved
_redirect. Null: the hosted thank-you page.thank_youobject | nullThe hosted thank-you page's text.
2 attributes
titlestringup to 200 charactersbodystringup to 2000 characters
honeypot_fieldstringA hidden field only bots fill (default
botcheck): a post that fills it is answered as a success and kept nowhere. It may not be a control's name (_redirect,_page,_referrer,access_key,cf-turnstile-response, anyutm_*, a click id), a defined field's key or a name the field map reads.hold_unsurebooleanHold submissions the spam check is unsure about for review.
fieldsarray of FormFieldrequiredup to 50 itemsThe fields the form defines, checked in order: a blank required field is
missing, then the type (invalid), length, range andpattern. A key that names a password, card number or national id is refused. Fields the form does not define are kept (seeunknown_fields). Empty: any fields are accepted.10 attributes
keystringrequiredup to 64 charactersThe field's name in the post.
labelstringup to 200 characterstypestringrequiredOne of
textemailphonetextareaurlnumberdatetimedatetimeselectmultiselectcheckboxconsentfilerequiredbooleanDefault
falseoptionsarray of stringThe values a post may send: required for
selectandmultiselect, optional forcheckbox(a group).helpstringup to 500 charactersplaceholderstringup to 200 charactersvalidationobject7 attributes
min_lengthinteger0 to 5000text, textarea, email, phone, url.
max_lengthinteger1 to 5000text, textarea, email, phone, url.
minnumber | stringnumber: a number; date, time, datetime: a value of that type; multiselect, checkbox group: a count of choices.
maxnumber | stringAs
min.integerbooleannumber only.
patternstringup to 500 charactersRE2 syntax, matched against the whole value (text, textarea, email, phone, url).
(?i)for any case. A pattern that does not compile is refused.messagestringup to 200 charactersReplaces the default error message.
fileobjectA
filefield's limits.3 attributes
acceptarray of stringup to 30 itemsmax_size_mbinteger1 to 10max_filesinteger1 to 5
consentobjectA
consentfield only, optional: the channel and purpose its box grants (a ledger consent, never required). Show the project's current consent wording (GET /consent/wordings) beside an unticked checkbox namedkeywhose value is the wording version. A ticked box on a post with a phone records aformgrant in the consent ledger with that version's text; a version the project never had is an invalid field. Without it the field is a plain consent: a ticked box (on,true,yesor1) is stored asyes, and it may be required.2 attributes
channelstringrequiredOne of
whatsappsmsvoice_humanpurposestringrequiredOne of
servicemarketing
field_mapobjectWhich submitted fields hold the person's name, email and phone. Defaults:
name,email,phone.3 attributes
namestringemailstringphonestring
retention_daysinteger1 to 3650Days a submission is kept. Default 365.
turnstilestringOne of
offonturnstile_site_keystring | nullturnstile_availablebooleanWhether this deployment can turn Turnstile on (it has Cloudflare credentials).
channelstringrequiredwebsite, orgoogle_lead_formfor a Google lead form connection. Set on create, never changed.One of
websitegoogle_lead_formkeysarray of FormKeyrequired5 attributes
idstringrequiredkeystringrequiredfkey_live_...orfkey_test_...: what the site posts to. Public, like the form's URL.modestringrequiredOne of
livetestexpires_atstring | nullISO 8601 timestampSet on a rotated key: when it stops working.
created_atstringISO 8601 timestamp
archived_atstring | nullISO 8601 timestampWhen the form was archived; null when it is live.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamphealthstringrequiredThe worst open health incident (
GET /v1/forms/health), orok.One of
okwarningcriticalgoogleobject | nullA Google lead form's ownership and arrivals, never its key; null for a website form.
4 attributes
lead_exportstringOne of
brightshoalother_tooloutcome_uploadsstringOne of
nonebrightshoalclient_crmlast_test_atstring | nullISO 8601 timestamplast_lead_atstring | nullISO 8601 timestamp
statsobjectGET /v1/forms/{id}only: live posts by outcome, from hourly counts.2 attributes
last_24hobject4 attributes
acceptedintegerrequiredheldintegerrequiredrefusedintegerrequiredEvery refusal reason, the hourly limit included.
failedintegerrequired
last_7dobject4 attributes
acceptedintegerrequiredheldintegerrequiredrefusedintegerrequiredEvery refusal reason, the hourly limit included.
failedintegerrequired
- 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 POST "https://api.brightshoal.com/api/forms/FORM_ID/restore" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"status": "active",
"kind": "enquiry",
"unknown_fields": "keep",
"approved_sites": [
"string"
],
"redirect_url": "https://example.com/hook",
"thank_you": {
"title": "Front desk",
"body": "string"
},
"honeypot_field": "string",
"hold_unsure": true,
"fields": [
{
"key": "string",
"label": "string",
"type": "text",
"required": true,
"options": [
"string"
],
"help": "string",
"placeholder": "string",
"validation": {
"min_length": 1,
"max_length": 1,
"min": 1,
"max": 1,
"integer": true,
"pattern": "string",
"message": "Hi, can I book a trip to Lisbon in May?"
},
"file": {
"accept": [
{}
],
"max_size_mb": 1,
"max_files": 1
},
"consent": {
"channel": "whatsapp",
"purpose": "service"
}
}
],
"field_map": {
"name": "Front desk",
"email": "ana@example.com",
"phone": "+14155550123"
},
"retention_days": 1,
"turnstile": "off",
"turnstile_site_key": "string",
"turnstile_available": true,
"channel": "website",
"keys": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"key": "string",
"mode": "live",
"expires_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z"
}
],
"archived_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z",
"health": "ok",
"google": {
"lead_export": "brightshoal",
"outcome_uploads": "none",
"last_test_at": "2026-10-28T09:30:00.000Z",
"last_lead_at": "2026-10-28T09:30:00.000Z"
},
"stats": {
"last_24h": {
"accepted": 1,
"held": 1,
"refused": 1,
"failed": 1
},
"last_7d": {
"accepted": 1,
"held": 1,
"refused": 1,
"failed": 1
}
}
}
}Get a submission
GET/api/forms/{id}/submissions/{sid}
Secret API key. How it works
Path parameters
idstringrequiredForm id,
form_....sidstringrequiredSubmission id,
fsub_....
Returns
200 OK
Response attributes
dataFormSubmissionrequired24 attributes
idstringrequiredorg_idstringproject_idstringform_idstringrequiredkey_idstring | nullmodestringrequiredOne of
liveteststatusstringrequiredOne of
acceptedheldreleaseddiscardedspam_reasonstring | nullWhy the spam check was unsure, comma-separated:
links,disposable_email,markup,not_text,no_origin. Null when it found nothing.fieldsobjectrequiredpage_urlstring | nullreferrerstring | nullutmobject | nullclick_idsobject | nulloriginstring | nullcountrystring | nullISO 3166-1 alpha-2, from the edge.
dropped_fieldsarray of stringKeys not stored: they named or held a password, card number or national id, or carried a file the form does not define.
consentsarray of object | nullConsent fields ticked, with the wording (the field's label) agreed to.
3 attributes
keystringwordingstringatstringISO 8601 timestamp
contextobject | nullThe page context
forms.jssent (_mlf), or a server'scontext.lead_idstring | nullThe lead it made, if any.
filesarray of objectIts files; download one with
GET /v1/forms/{id}/submissions/{sid}/files/{fileId}.6 attributes
idstringrequiredfield_keystringrequiredfilenamestringrequiredcontent_typestringrequiredThe type its bytes were sniffed as.
size_bytesintegerrequiredscan_statusstringrequiredIts malware scan:
pending(downloads answer 409 until it is done, usually seconds),clean,infected(deleted; downloads answer 410),unscannable(the scanner could not read it: served, unscanned) ornot_scanned(stored while scanning was off).One of
pendingcleaninfectedunscannablenot_scanned
archived_atstring | nullISO 8601 timestampWhen the submission was archived; null when it is live.
external_idstring | nullGoogle's
lead_idfor a Google lead form's lead; null for a website post.adobject | nullThe ids Google sent with a Google lead form's lead (
platform,lead_id,form_id,campaign_id,adgroup_id,creative_id,asset_group_id,gcl_id,lead_source,lead_stage,submitted_at), withcapture_conversion: false: Google already counted it. Null for a website post.received_atstringrequiredISO 8601 timestamp
- 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 "https://api.brightshoal.com/api/forms/FORM_ID/submissions/SID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"form_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"key_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"mode": "live",
"status": "accepted",
"spam_reason": "string",
"fields": {
"key": "string"
},
"page_url": "https://example.com/hook",
"referrer": "string",
"utm": {
"key": "string"
},
"click_ids": {
"key": "string"
},
"origin": "https://www.example.com",
"country": "string",
"dropped_fields": [
"string"
],
"consents": [
{
"key": "string",
"wording": "string",
"at": "2026-10-28T09:30:00.000Z"
}
],
"context": {},
"lead_id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"files": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"field_key": "string",
"filename": "string",
"content_type": "string",
"size_bytes": 1,
"scan_status": "pending"
}
],
"archived_at": "2026-10-28T09:30:00.000Z",
"external_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"ad": {},
"received_at": "2026-10-28T09:30:00.000Z"
}
}Delete an archived submission
DELETE/api/forms/{id}/submissions/{sid}
Permanent: its files are deleted first (503 files_not_deleted when one could not be: the rows are kept, and a retry finishes), then the submission. Its lead, if it made one, stays. Only an archived submission can be deleted: 409 not_archived otherwise. Needs the admin role; audited.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredForm id,
form_....sidstringrequiredSubmission id,
fsub_....
Returns
200 OK
Response attributes
dataDeleteResultrequired2 attributes
idstringrequireddeletedbooleanrequired
- 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
not_archived: archive the submission first. - 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). - 503
files_not_deleted: try again shortly.
curl -X DELETE "https://api.brightshoal.com/api/forms/FORM_ID/submissions/SID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"deleted": true
}
}Archive a submission
POST/api/forms/{id}/submissions/{sid}/archive
It leaves the submissions list and the export. Nothing is deleted: its files stay and still download, its lead stays, and it can be restored (or then deleted for good). Archiving an archived submission is a no-op. Needs the admin role; audited.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredForm id,
form_....sidstringrequiredSubmission id,
fsub_....
Returns
200 OK
Response attributes
dataFormSubmissionrequired24 attributes
idstringrequiredorg_idstringproject_idstringform_idstringrequiredkey_idstring | nullmodestringrequiredOne of
liveteststatusstringrequiredOne of
acceptedheldreleaseddiscardedspam_reasonstring | nullWhy the spam check was unsure, comma-separated:
links,disposable_email,markup,not_text,no_origin. Null when it found nothing.fieldsobjectrequiredpage_urlstring | nullreferrerstring | nullutmobject | nullclick_idsobject | nulloriginstring | nullcountrystring | nullISO 3166-1 alpha-2, from the edge.
dropped_fieldsarray of stringKeys not stored: they named or held a password, card number or national id, or carried a file the form does not define.
consentsarray of object | nullConsent fields ticked, with the wording (the field's label) agreed to.
3 attributes
keystringwordingstringatstringISO 8601 timestamp
contextobject | nullThe page context
forms.jssent (_mlf), or a server'scontext.lead_idstring | nullThe lead it made, if any.
filesarray of objectIts files; download one with
GET /v1/forms/{id}/submissions/{sid}/files/{fileId}.6 attributes
idstringrequiredfield_keystringrequiredfilenamestringrequiredcontent_typestringrequiredThe type its bytes were sniffed as.
size_bytesintegerrequiredscan_statusstringrequiredIts malware scan:
pending(downloads answer 409 until it is done, usually seconds),clean,infected(deleted; downloads answer 410),unscannable(the scanner could not read it: served, unscanned) ornot_scanned(stored while scanning was off).One of
pendingcleaninfectedunscannablenot_scanned
archived_atstring | nullISO 8601 timestampWhen the submission was archived; null when it is live.
external_idstring | nullGoogle's
lead_idfor a Google lead form's lead; null for a website post.adobject | nullThe ids Google sent with a Google lead form's lead (
platform,lead_id,form_id,campaign_id,adgroup_id,creative_id,asset_group_id,gcl_id,lead_source,lead_stage,submitted_at), withcapture_conversion: false: Google already counted it. Null for a website post.received_atstringrequiredISO 8601 timestamp
- 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 POST "https://api.brightshoal.com/api/forms/FORM_ID/submissions/SID/archive" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"form_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"key_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"mode": "live",
"status": "accepted",
"spam_reason": "string",
"fields": {
"key": "string"
},
"page_url": "https://example.com/hook",
"referrer": "string",
"utm": {
"key": "string"
},
"click_ids": {
"key": "string"
},
"origin": "https://www.example.com",
"country": "string",
"dropped_fields": [
"string"
],
"consents": [
{
"key": "string",
"wording": "string",
"at": "2026-10-28T09:30:00.000Z"
}
],
"context": {},
"lead_id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"files": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"field_key": "string",
"filename": "string",
"content_type": "string",
"size_bytes": 1,
"scan_status": "pending"
}
],
"archived_at": "2026-10-28T09:30:00.000Z",
"external_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"ad": {},
"received_at": "2026-10-28T09:30:00.000Z"
}
}Download a submission's file
GET/api/forms/{id}/submissions/{sid}/files/{fileId}
Answers 302 to a download link (/public/forms/files/{fileId}) signed for 10 minutes. With malware scanning on, a new file downloads once its scan is clean, usually within seconds of the post.
Secret API key. How it works
Path parameters
idstringrequiredForm id,
form_....sidstringrequiredSubmission id,
fsub_....fileIdstringrequiredFile id,
ffile_....
Returns
- 302 The signed link, in
Location. - 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
file_scanning: its malware scan is not done yet. Try again in a minute (Retry-After). - 410
file_infected: the scan found malware and the file was deleted. - 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/forms/FORM_ID/submissions/SID/files/FILE_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"Release a held submission
POST/api/forms/{id}/submissions/{sid}/release
Accepts a submission the spam check held: it then makes its lead and sends form.submitted, as an accepted one does. Releasing one twice is a no-op. 409 submission_archived for an archived one: restore it first. Needs the admin role.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredForm id,
form_....sidstringrequiredSubmission id,
fsub_....
Returns
200 OK
Response attributes
dataFormSubmissionrequired24 attributes
idstringrequiredorg_idstringproject_idstringform_idstringrequiredkey_idstring | nullmodestringrequiredOne of
liveteststatusstringrequiredOne of
acceptedheldreleaseddiscardedspam_reasonstring | nullWhy the spam check was unsure, comma-separated:
links,disposable_email,markup,not_text,no_origin. Null when it found nothing.fieldsobjectrequiredpage_urlstring | nullreferrerstring | nullutmobject | nullclick_idsobject | nulloriginstring | nullcountrystring | nullISO 3166-1 alpha-2, from the edge.
dropped_fieldsarray of stringKeys not stored: they named or held a password, card number or national id, or carried a file the form does not define.
consentsarray of object | nullConsent fields ticked, with the wording (the field's label) agreed to.
3 attributes
keystringwordingstringatstringISO 8601 timestamp
contextobject | nullThe page context
forms.jssent (_mlf), or a server'scontext.lead_idstring | nullThe lead it made, if any.
filesarray of objectIts files; download one with
GET /v1/forms/{id}/submissions/{sid}/files/{fileId}.6 attributes
idstringrequiredfield_keystringrequiredfilenamestringrequiredcontent_typestringrequiredThe type its bytes were sniffed as.
size_bytesintegerrequiredscan_statusstringrequiredIts malware scan:
pending(downloads answer 409 until it is done, usually seconds),clean,infected(deleted; downloads answer 410),unscannable(the scanner could not read it: served, unscanned) ornot_scanned(stored while scanning was off).One of
pendingcleaninfectedunscannablenot_scanned
archived_atstring | nullISO 8601 timestampWhen the submission was archived; null when it is live.
external_idstring | nullGoogle's
lead_idfor a Google lead form's lead; null for a website post.adobject | nullThe ids Google sent with a Google lead form's lead (
platform,lead_id,form_id,campaign_id,adgroup_id,creative_id,asset_group_id,gcl_id,lead_source,lead_stage,submitted_at), withcapture_conversion: false: Google already counted it. Null for a website post.received_atstringrequiredISO 8601 timestamp
- 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/forms/FORM_ID/submissions/SID/release" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"form_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"key_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"mode": "live",
"status": "accepted",
"spam_reason": "string",
"fields": {
"key": "string"
},
"page_url": "https://example.com/hook",
"referrer": "string",
"utm": {
"key": "string"
},
"click_ids": {
"key": "string"
},
"origin": "https://www.example.com",
"country": "string",
"dropped_fields": [
"string"
],
"consents": [
{
"key": "string",
"wording": "string",
"at": "2026-10-28T09:30:00.000Z"
}
],
"context": {},
"lead_id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"files": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"field_key": "string",
"filename": "string",
"content_type": "string",
"size_bytes": 1,
"scan_status": "pending"
}
],
"archived_at": "2026-10-28T09:30:00.000Z",
"external_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"ad": {},
"received_at": "2026-10-28T09:30:00.000Z"
}
}Replay a submission's webhooks
POST/api/forms/{id}/submissions/{sid}/replay
Sends the submission's form.submitted and lead.captured events again to the subscriptions that match them now, with the same event ids and idempotency keys, so receivers dedupe. A replayed form.submitted carries its file links signed again for 7 days from the replay. Needs the admin role; audited.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredForm id,
form_....sidstringrequiredSubmission id,
fsub_....
Request body
eventsarray of stringDefault: both.
Returns
200 How many deliveries were queued.
Response attributes
dataobject1 attribute
queuedintegerrequired
- 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
held: a held submission has sent nothing; release it.submission_archived: restore it first. - 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/forms/FORM_ID/submissions/SID/replay" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"events": [
"form.submitted"
]
}'{
"data": {
"queued": 1
}
}Restore an archived submission
POST/api/forms/{id}/submissions/{sid}/restore
It is listed and exported again. Restoring a live submission is a no-op. Needs the admin role; audited.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredForm id,
form_....sidstringrequiredSubmission id,
fsub_....
Returns
200 OK
Response attributes
dataFormSubmissionrequired24 attributes
idstringrequiredorg_idstringproject_idstringform_idstringrequiredkey_idstring | nullmodestringrequiredOne of
liveteststatusstringrequiredOne of
acceptedheldreleaseddiscardedspam_reasonstring | nullWhy the spam check was unsure, comma-separated:
links,disposable_email,markup,not_text,no_origin. Null when it found nothing.fieldsobjectrequiredpage_urlstring | nullreferrerstring | nullutmobject | nullclick_idsobject | nulloriginstring | nullcountrystring | nullISO 3166-1 alpha-2, from the edge.
dropped_fieldsarray of stringKeys not stored: they named or held a password, card number or national id, or carried a file the form does not define.
consentsarray of object | nullConsent fields ticked, with the wording (the field's label) agreed to.
3 attributes
keystringwordingstringatstringISO 8601 timestamp
contextobject | nullThe page context
forms.jssent (_mlf), or a server'scontext.lead_idstring | nullThe lead it made, if any.
filesarray of objectIts files; download one with
GET /v1/forms/{id}/submissions/{sid}/files/{fileId}.6 attributes
idstringrequiredfield_keystringrequiredfilenamestringrequiredcontent_typestringrequiredThe type its bytes were sniffed as.
size_bytesintegerrequiredscan_statusstringrequiredIts malware scan:
pending(downloads answer 409 until it is done, usually seconds),clean,infected(deleted; downloads answer 410),unscannable(the scanner could not read it: served, unscanned) ornot_scanned(stored while scanning was off).One of
pendingcleaninfectedunscannablenot_scanned
archived_atstring | nullISO 8601 timestampWhen the submission was archived; null when it is live.
external_idstring | nullGoogle's
lead_idfor a Google lead form's lead; null for a website post.adobject | nullThe ids Google sent with a Google lead form's lead (
platform,lead_id,form_id,campaign_id,adgroup_id,creative_id,asset_group_id,gcl_id,lead_source,lead_stage,submitted_at), withcapture_conversion: false: Google already counted it. Null for a website post.received_atstringrequiredISO 8601 timestamp
- 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 POST "https://api.brightshoal.com/api/forms/FORM_ID/submissions/SID/restore" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"form_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"key_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"mode": "live",
"status": "accepted",
"spam_reason": "string",
"fields": {
"key": "string"
},
"page_url": "https://example.com/hook",
"referrer": "string",
"utm": {
"key": "string"
},
"click_ids": {
"key": "string"
},
"origin": "https://www.example.com",
"country": "string",
"dropped_fields": [
"string"
],
"consents": [
{
"key": "string",
"wording": "string",
"at": "2026-10-28T09:30:00.000Z"
}
],
"context": {},
"lead_id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"files": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"field_key": "string",
"filename": "string",
"content_type": "string",
"size_bytes": 1,
"scan_status": "pending"
}
],
"archived_at": "2026-10-28T09:30:00.000Z",
"external_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"ad": {},
"received_at": "2026-10-28T09:30:00.000Z"
}
}Export a form's submissions as CSV
GET/api/forms/{id}/submissions/export
Every live submission (with archived=true, every archived one), newest first. Columns: submission_id, received_at, status, mode, the defined fields in order (headed by label, else key), other field keys in first-seen order, page_url, referrer, the five UTMs, gclid, lead_id, files (the file names) and files_scan_status (each file's scan status, in the same order). A cell starting with =, +, -, @, a tab or a carriage return gets a leading '. Needs the admin role; audited.
Secret API key. How it works
Path parameters
idstringrequiredForm id,
form_....
Query parameters
archivedbooleantrue: only archived submissions. Absent: only live ones.
Returns
200 CSV.
- 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 "https://api.brightshoal.com/api/forms/FORM_ID/submissions/export" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-o attachmentErase a person's form data
POST/api/forms/erasures
The way to delete one person's data (with the forms' retention, and deleting an archived form or submission). Deletes the submissions in the org (or project_id), archived ones and those of archived forms included, where a contact field (one defined as email or phone, the form's field_map email or phone key, or on a form with no definition the key email or phone) is this email (any case) or phone (digits compared, the last 10 when longer), the form leads they made or with that email or phone, the webhook events about them, and the submissions' files (first; 503 when one could not be deleted: the rows are kept, and a retry finishes). dry_run only counts. Needs the admin role; audited with the counts and a keyed hash (HMAC) of the identifier, never the identifier.
Secret API key, not a viewer key. How it works
Request body
project_idstringemailstringemailAn email address.
phonestringA phone number: 7 to 15 digits.
dry_runboolean
Returns
200 What was (or, on a dry run, would be) erased.
Response attributes
dataobject4 attributes
submissionsintegerrequiredfilesintegerrequiredleadsintegerrequireddry_runbooleanrequired
- 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 - 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/forms/erasures" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"email": "ana@example.com"
}'{
"data": {
"submissions": 1,
"files": 1,
"leads": 1,
"dry_run": true
}
}List form health incidents
GET/api/forms/health
Problems the form health checker found, newest first: a form gone quiet against its own history (form_quiet), refusing posts (form_refusing, one per reason), failing to store them (form_failing), or whose form.submitted deliveries are not arriving (form_undelivered). Live posts only.
Secret API key. How it works
Query parameters
project_idstringstatusstringOne of
openresolvedform_idstringcursorstringOpaque
next_cursorfrom the previous page.limitinteger1 to 200
Returns
200 OK
Response attributes
dataarray of FormHealthIncidentrequired14 attributes
idstringrequiredform_idstringrequiredform_namestringrulestringrequiredOne of
form_quietform_refusingform_failingform_undeliveredseveritystringrequiredOne of
warningcriticalstatusstringrequiredOne of
openresolvedreasonstring | nullform_refusing: the refusal (refused_site,refused_fields,refused_google_key, ...); else null.detailobjectrequiredThe rule's numbers.
form_quiet:last_24h,one_week_ago,two_weeks_ago.form_refusing:refused,posts,reason.form_failing:failed.form_undelivered:undelivered,gave_up,subscription_id,last_status.first_seen_atstringISO 8601 timestamplast_seen_atstringISO 8601 timestampopened_atstringrequiredISO 8601 timestampresolved_atstring | nullISO 8601 timestampresolutionstring | nullOne of
recoveredquietmanualform_archivedtitlestringWhat the console and Slack show.
next_cursorstring | 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/forms/health" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"form_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"form_name": "string",
"rule": "form_quiet",
"severity": "warning",
"status": "open",
"reason": "string",
"detail": {},
"first_seen_at": "2026-10-28T09:30:00.000Z",
"last_seen_at": "2026-10-28T09:30:00.000Z",
"opened_at": "2026-10-28T09:30:00.000Z",
"resolved_at": "2026-10-28T09:30:00.000Z",
"resolution": "recovered",
"title": "Front desk"
}
],
"next_cursor": "eyJ0IjoiMjAyNi0xMC0yOCJ9"
}Resolve a form health incident
POST/api/forms/health/{incidentId}/resolve
Closes it by hand (resolution: manual); the same problem does not reopen for 24 hours. Sends form.health.resolved. A resolved incident is a no-op. Needs the admin role; audited.
Secret API key, not a viewer key. How it works
Path parameters
incidentIdstringrequiredfhinc_....
Returns
200 OK
Response attributes
dataFormHealthIncidentrequired14 attributes
idstringrequiredform_idstringrequiredform_namestringrulestringrequiredOne of
form_quietform_refusingform_failingform_undeliveredseveritystringrequiredOne of
warningcriticalstatusstringrequiredOne of
openresolvedreasonstring | nullform_refusing: the refusal (refused_site,refused_fields,refused_google_key, ...); else null.detailobjectrequiredThe rule's numbers.
form_quiet:last_24h,one_week_ago,two_weeks_ago.form_refusing:refused,posts,reason.form_failing:failed.form_undelivered:undelivered,gave_up,subscription_id,last_status.first_seen_atstringISO 8601 timestamplast_seen_atstringISO 8601 timestampopened_atstringrequiredISO 8601 timestampresolved_atstring | nullISO 8601 timestampresolutionstring | nullOne of
recoveredquietmanualform_archivedtitlestringWhat the console and Slack show.
- 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 POST "https://api.brightshoal.com/api/forms/health/INCIDENT_ID/resolve" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"form_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"form_name": "string",
"rule": "form_quiet",
"severity": "warning",
"status": "open",
"reason": "string",
"detail": {},
"first_seen_at": "2026-10-28T09:30:00.000Z",
"last_seen_at": "2026-10-28T09:30:00.000Z",
"opened_at": "2026-10-28T09:30:00.000Z",
"resolved_at": "2026-10-28T09:30:00.000Z",
"resolution": "recovered",
"title": "Front desk"
}
}