Forms
Add a form to your website
Post your site's own forms to Brightshoal, check every field before it is stored, and turn each submission into a lead.
A Brightshoal form takes posts from a form on your own site, checks them against the fields you define, and turns each accepted submission into a lead, the same lead the chat assistant would save.
Create the form
In the console, open Channels > Forms and create a form. Or create it with POST/api/forms:
curl -X POST https://api.brightshoal.com/api/forms \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Contact",
"project_id": "'"$BRIGHTSHOAL_PROJECT_ID"'",
"approved_sites": ["acmetravel.com"],
"fields": [
{ "key": "name", "label": "Name", "type": "text", "required": true },
{ "key": "email", "label": "Email", "type": "email", "required": true },
{ "key": "message", "label": "Message", "type": "textarea", "validation": { "max_length": 2000 } }
]
}'{
"data": {
"id": "form_4e7a1c9d2b3f4a5e8c6d0b1a2f3e4d5c",
"name": "Contact",
"status": "active",
"kind": "enquiry",
"approved_sites": ["acmetravel.com"],
"honeypot_field": "botcheck",
"fields": [ "..." ],
"field_map": { "name": "name", "email": "email", "phone": "phone" },
"keys": [
{ "id": "fk_...", "key": "fkey_live_9b2e4c6a8d0f4e1a3c5b7d9e1f2a4c6b", "mode": "live", "expires_at": null },
{ "id": "fk_...", "key": "fkey_test_1c3e5a7b9d2f4a6c8e0b2d4f6a8c0e2b", "mode": "test", "expires_at": null }
]
}
}field_map names the fields that hold the person's name, email and phone, which become the lead's contact details. Every other field is kept in the lead's fields.
Pick a key
Every form has two keys. Both are public: they sit in your page's HTML, like the form's URL.
| Key | Use it for |
|---|---|
fkey_live_... | Your real site. Posts are accepted only from the form's approved sites (none until you add one), and Turnstile applies when it is on. |
fkey_test_... | Trying the form. Posts are accepted from any site, skip Turnstile, and are stored as test submissions. Only admins are shown this key. |
To replace a key, rotate it in the console or with POST/api/forms/{id}/keys/rotate and { "mode": "live" }. The new key works at once and the old one keeps working for 7 days, so you can update the site first. Send "grace": false to stop the old key at once. A key that leaked can be stopped on its own with POST/api/forms/{id}/keys/{keyId}/revoke.
Add the form to your page
The form posts straight to https://api.brightshoal.com/public/forms/<key>:
<form
action="https://api.brightshoal.com/public/forms/fkey_live_9b2e4c6a8d0f4e1a3c5b7d9e1f2a4c6b"
method="POST"
data-brightshoal-form
>
<label>Name <input type="text" name="name" required></label>
<label>Email <input type="email" name="email" required></label>
<label>Message <textarea name="message"></textarea></label>
<input type="hidden" name="_redirect" value="https://www.acmetravel.com/thanks">
<input type="text" name="botcheck" tabindex="-1" autocomplete="off" style="display:none">
<button type="submit">Send</button>
</form>
<script src="https://api.brightshoal.com/widget/v1/forms.js" defer></script>Each input's name is the field's key. The console copies this snippet for you, with your form's fields.
data-brightshoal-formmarks the form forforms.js, which adds the page context on submit.botcheckis the honeypot: a hidden field that people never see and bots fill. Keep it hidden and empty. The name is the form'shoneypot_field._redirectis where the browser goes after a successful post. It is used only when its host is one of the form's approved sites. Otherwise the browser goes to the form'sredirect_url, or to a hosted thank-you page showing the form'sthank_youtext.
Post with fetch
To stay on the page and show your own messages, post with fetch and ask for JSON. A JSON body, or an Accept: application/json header, makes every answer JSON, refusals included.
const res = await fetch('https://api.brightshoal.com/public/forms/fkey_live_9b2e4c6a8d0f4e1a3c5b7d9e1f2a4c6b', {
method: 'POST',
headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
body: JSON.stringify({
name: 'Ana Silva',
email: 'ana@example.com',
message: 'Two weeks in Lisbon in May.',
_mlf: JSON.stringify(brightshoalForms.context()),
}),
})
const result = await res.json()
// { success: true, submission_id, lead_id, status } or { success: false, error, message, fields }In a JSON body each value is a string, a number or boolean (kept as text), or an array of strings for a list. A null is left out. An object is refused, so send _mlf as a JSON string, as above.
A list (checkboxes, a multi-select, a JSON array, or the same name repeated in a form post) is one field. Its values are checked one by one and stored joined with ", ".
Page context: forms.js
forms.js records where the visitor came from and sends it with the form. It makes no requests of its own and loads no chat.
<script src="https://api.brightshoal.com/widget/v1/forms.js" defer></script>On submit of any form[data-brightshoal-form], or any form whose action contains /public/forms/, it sets a hidden _mlf input to the context. Forms added to the page later are covered too. For fetch posts, brightshoalForms.context() returns the same object:
{
"v": 1,
"visitor_id": "6f1d2c3b-8a9e-4b7c-9d0e-1f2a3b4c5d6e",
"page": "https://www.acmetravel.com/contact",
"referrer": "https://www.acmetravel.com/lisbon",
"landing_page": "https://www.acmetravel.com/lisbon?utm_source=google&utm_medium=cpc",
"utm": { "utm_source": "google", "utm_medium": "cpc" },
"click_ids": {},
"rendered_at": "2026-11-04T10:12:44.381Z"
}landing_page, utm and click_ids are the first ones seen in this browser session, so a form on a later page still gets the campaign that brought the visitor. visitor_id is the chat widget's visitor id when the widget is on the same site, so a form and a chat from one visitor link up.
For sites that need consent before tracking (the UK and the EU), add data-consent="required":
<script src="https://api.brightshoal.com/widget/v1/forms.js" data-consent="required" defer></script>Until the visitor has allowed analytics in the chat widget, the context is only { v, page, referrer } and forms.js stores nothing.
The intake reads _mlf (JSON of at most 4 KiB), never keeps it as a field, and uses it to fill the page, referrer, UTMs and click ids the post itself lacks. A bad _mlf is ignored, never refused.
Fields and validation
A form's fields (at most 50) is its definition. Each field has a key, an optional label (used in error messages), a type, required, and optional help, placeholder, options, validation and file. With no definition, any fields are accepted, and a lead is made only when there is an email or a phone.
| Type | A value is valid when | Rules it takes |
|---|---|---|
text | Any text. Runs of spaces become one. | min_length, max_length, pattern |
textarea | Any text. Line breaks are kept. | min_length, max_length, pattern |
email | It looks like name@domain.tld. Stored lowercased. | min_length, max_length, pattern |
phone | Digits with spaces, dots, dashes, brackets and a leading +; 7 to 15 digits. Stored as typed. | min_length, max_length, pattern |
url | An absolute http:// or https:// URL. | min_length, max_length, pattern |
number | A plain decimal, such as -12 or 3.5. No +, exponent or thousands separators. | min, max, integer |
date | YYYY-MM-DD, a real calendar date. | min, max as dates |
time | HH:MM or HH:MM:SS, 24 hour. | min, max as times |
datetime | YYYY-MM-DDTHH:MM (what datetime-local sends), optional :SS, optional Z or +HH:MM. A value with a zone is compared in UTC; one without is compared as written. | min, max as date-times |
select | Exactly one of options (required). | |
multiselect | Each value is one of options (required). | min, max as a count of choices |
checkbox | With options, a group: each value is one of them. Without, a single box: any value means ticked. | min, max as a count of choices |
consent | Ticked: on, true, yes or 1, in any case. off, false, no and 0 count as blank. Stored as yes, with the label kept as the wording agreed to. | |
file | See File uploads. | file |
Every type also takes validation.message, which replaces the default error message for that field (at most 200 characters). Lengths are 0 to 5,000 characters. A field definition is refused when it uses a rule its type does not take.
[
{ "key": "email", "label": "Work email", "type": "email", "required": true,
"validation": { "pattern": "(?i).+@acmetravel\\.com", "message": "Use your acmetravel.com address." } },
{ "key": "budget", "label": "Budget", "type": "number",
"validation": { "min": 1000, "integer": true } },
{ "key": "depart", "label": "Departure", "type": "date",
"validation": { "min": "2026-11-01" } },
{ "key": "rooms", "label": "Rooms", "type": "multiselect",
"options": ["Single", "Double", "Suite"], "validation": { "max": 2 } }
]Patterns use RE2 syntax and must match the whole value, as the HTML pattern attribute does. Add (?i) at the start for any case. A pattern that does not compile is refused when the form is saved. RE2 has no lookarounds or backreferences, so a pattern always runs in linear time.
Each field is checked in this order, and the first failure is reported:
- A blank required field is
missing. A blank optional field passes. - The type:
invalid. - The length:
too_short,too_long. - The range:
too_small,too_large. - The pattern:
pattern.
Every field with a problem is reported, so one refusal lists everything the person needs to fix.
Values are trimmed before they are checked. Fields the form does not define are kept as they are. To refuse them instead, set the form's unknown_fields to reject: each one is then reported as unknown. Controls (_redirect, _mlf, the honeypot, UTMs, click ids) are never fields, so they are never unknown.
File uploads
A file field accepts files from a browser form posted as multipart/form-data. Add enctype="multipart/form-data" to the <form>, or post a FormData with fetch.
{ "key": "cv", "label": "CV", "type": "file", "required": true,
"file": { "accept": [".pdf", ".docx"], "max_size_mb": 5, "max_files": 1 } }<form action="https://api.brightshoal.com/public/forms/fkey_live_..." method="POST" enctype="multipart/form-data" data-brightshoal-form>
<label>CV <input type="file" name="cv" accept=".pdf,.docx" required></label>
...
</form>| Setting | Meaning |
|---|---|
file.accept | Up to 30 extensions (.pdf) or types (application/pdf, image/*). Default: .pdf .png .jpg .jpeg .gif .webp .heic .txt .csv .doc .docx .xls .xlsx .ppt .pptx. |
file.max_size_mb | Per file, 1 to 10. Default 5. |
file.max_files | Per field, 1 to 5. Default 1. |
- A submission may carry at most 10 files and 10 MiB of files in all. Only a form with a
filefield takes the larger body: a multipart post to any other form is held to 64 KiB, like every other post, and over that is a413. - A file's extension and its content (read from its first bytes) must both fit
accept. Soacceptonly works for types whose content can be recognised: images, PDF, Word, Excel, PowerPoint, plain text and CSV. Anything else, such as.zip, is refused. - These are always refused, whatever
acceptsays:.exe .bat .cmd .com .msi .sh .js .mjs .html .htm .svg .php .jar .apk .dmg .app .scr .ps1 .vbs. - Problems are reported per field as
file_type,file_too_largeandtoo_many_files. - The field's value in the submission is the file names, joined with
", ". The files themselves are listed in the submission'sfilesand inform.submitted. - A file sent under a name that is not a
filefield is not stored. Its key goes intodropped_fieldsand the post is still accepted, unlessunknown_fieldsisreject. - When malware scanning is on, each file is scanned as it is stored. Each file in a submission has a
scan_status:pendingwhile it is scanned,clean,infected(the file is deleted as soon as the scan finds malware, and its stored copies expire within a day; its name, size and type stay),unscannable(the scanner could not read it, or gave no verdict within an hour, so it is served unscanned) ornot_scanned(stored while scanning was off). - With scanning on, a file's download link works once its scan is clean, usually within seconds of the post. Until then the link answers
409 file_scanningwithRetry-After: 60; for an infected file it answers410 file_infected. The links inform.submittedare made when the submission arrives, so a receiver that downloads at once should retry a409after theRetry-After. - Treat files as untrusted when you open them, scanned or not. Older Office files (
.doc,.xls,.ppt) may contain macros; leave them out ofacceptif you do not need them. - Server-to-server posts cannot carry files.
Approved sites and CORS
A form's approved_sites lists the hosts that may post to it with its live key, such as acmetravel.com. A host also covers its subdomains, so acmetravel.com covers www.acmetravel.com. Up to 20.
| Approved sites | Live key | Test key |
|---|---|---|
| Empty | No site may post: 403 site_not_approved. | Any site may post. |
| Listed | Only those sites (and their subdomains). | Any site may post. |
The check runs twice:
- In the browser (CORS). A
fetchfrom an approved site can read the answer. From any other site, the answer carries noAccess-Control-Allow-Origin, so the browser refuses it and yourfetchrejects with a network error. A JSON post is preflighted, so from an unapproved site it is never sent at all. - At the intake. A plain HTML form post needs no CORS, so the intake checks the request's
Origin, else itsReferer, and refuses a live key's post from an unapproved site with403 site_not_approved.
A live key needs at least one approved site. Until the form has one, every browser post with the live key is refused with 403 site_not_approved ("Add this site to the form's approved sites first."), and the console shows Add a site to go live on the form. Test keys, server-to-server posts and Google lead forms are not affected.
Forms that took live posts before 2026-11-04 had their posting sites added automatically.
A newly approved site can take up to a minute to be allowed by CORS.
Spam protection
- Honeypot. A post that fills the hidden honeypot field is answered with a normal success, and nothing is kept.
- Held submissions. Each post is checked for signs of spam: more than two links, a throwaway email domain, markup such as
<script>or[url=, a message that is mostly not letters, or noOriginand noReferer. When any is found and the form holds unsure posts (hold_unsure, on by default), the submission is stored asheld: no lead, no webhooks, and the sender sees the usual success with"status": "held". Release it in the console or with POST/api/forms/{id}/submissions/{sid}/releaseto make its lead and send its events, or archive it to set it aside. - Turnstile (optional). Turn on Cloudflare Turnstile in the form's settings (it needs 1 to 10 approved sites). The console's snippet then includes the widget, which adds
cf-turnstile-responseto the post. A live key's post without a valid token is refused with400 turnstile_failed. Test keys skip it.
The intake also limits each address to 10 posts a minute and 100 a day, and each key to 600 stored submissions an hour.
Send submissions from your server
When your own backend collects the form, send each submission with POST/api/forms/{id}/submissions and an API key. Any key that may write works; viewer keys cannot.
curl -X POST https://api.brightshoal.com/api/forms/form_4e7a1c9d2b3f4a5e8c6d0b1a2f3e4d5c/submissions \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"fields": { "name": "Ana Silva", "email": "ana@example.com", "message": "Two weeks in Lisbon in May." },
"page_url": "https://www.acmetravel.com/contact",
"utm": { "utm_source": "google", "utm_medium": "cpc" },
"click_ids": { "gclid": "Cj0KCQjw..." }
}'| Field | Meaning |
|---|---|
fields | Required. Name to value: a string, a number or boolean (kept as text), an array of strings, or null (left out). |
mode | live (the default) or test, which stores a test submission. |
page_url, referrer | The page the form was on and its referrer, up to 2,000 characters. |
utm | The five utm_* parameters. Other keys are ignored. |
click_ids | gclid, gbraid, wbraid, fbclid, msclkid, ttclid, li_fat_id. Other keys are ignored. |
context | The object brightshoalForms.context() returned, as an object (not a string). |
The body is JSON of at most 64 KiB. It gets the same field checks, sensitive-field drop, normalisation, form kind, spam check and 10-minute duplicate window as a browser post. It skips the approved sites, Turnstile, the per-address limits and the missing Origin signal. Each form allows 600 server submissions an hour. The answer is 201 with the same receipt as a browser post; a field problem is 400 invalid_fields in the same shape, and a malformed body is the API's usual 400 invalid_request.
What each answer means
A browser's form post gets a redirect or an HTML page. A fetch with a JSON body or Accept: application/json, and every server-to-server post, gets JSON.
{
"success": true,
"submission_id": "fsub_8c1f3a5e7b9d4c2e8a0f1b3d5e7a9c1e",
"lead_id": "lead_3a9c7e1f5b2d4c8e9f0a1b2c3d4e5f6a",
"status": "accepted"
}status is accepted, or held when the spam check held it. lead_id is null when the submission was held, the form's kind makes no leads, or there was nothing to make a lead from. Otherwise it is final: the lead is written together with the submission, so the receipt never changes later.
{
"success": false,
"error": "invalid_fields",
"message": "Some fields need attention.",
"fields": [
{ "key": "budget", "label": "Budget", "problem": "too_small", "message": "Budget must be at least 1000." }
]
}message is written for the person filling in the form, so you can show it as is. Branch on error and problem, which are stable. A browser post that is refused gets a plain HTML page listing the same messages.
| Status | Means | Retry? |
|---|---|---|
200 | Accepted (a public post asking for JSON). | No. |
201 | Accepted (a server-to-server post). | No. |
303 | Accepted (a browser form post). Location is where the browser goes next. | No. |
400 | invalid_fields: see fields below. invalid_body: the body could not be read. field_too_long: a value over 5,000 characters. too_many_fields: more than 50. turnstile_failed: the Turnstile token was missing or rejected. | No, not unchanged. Fix the fields; for turnstile_failed, get a fresh token. |
403 | form_archived: the form is archived. form_paused: the form is paused. site_not_approved: a live key posted from a site the form does not list, or the form has no approved sites yet. | No. |
404 | form_not_found: the key is unknown, revoked or expired. | No. |
413 | body_too_large: over 64 KiB (or, for a form with a file field, over the file limits), or more than 1,000 values or 20 file parts. | No. |
415 | unsupported_content_type: not a form post, multipart or JSON. | No. |
429 | rate_limited: too many posts. | Yes, after Retry-After seconds. |
500 | internal_error: nothing was stored. | Yes, once or twice with backoff. |
503 | rate_limit_unavailable, turnstile_unavailable or files_unavailable: a dependency is briefly down. | Yes, with backoff. |
Each entry in fields has a problem:
problem | Meaning |
|---|---|
missing | A required field is blank (or was dropped as sensitive). |
invalid | The value is not of the field's type, or not one of its options. |
too_short, too_long | Shorter than min_length or longer than max_length. |
too_small, too_large | Below min or above max (for a list, too few or too many choices). |
pattern | Does not match pattern. |
unknown | Not a field of this form, and unknown_fields is reject. |
file_type | A file's extension or content is not accepted. |
file_too_large | A file is over max_size_mb. |
too_many_files | More files than max_files. |
Duplicates. The same fields posted to the same form with the same kind of key within 10 minutes are stored once: the repeat answers with the first submission's receipt. A double click, or a retry after a timeout or a 500, never makes a second submission or lead.
Test keys
A post with the fkey_test_... key is a test submission (mode: "test"). It is accepted from any site and skips Turnstile, and it runs the same field checks. Its lead is a sandbox lead, and its webhooks go only to sandbox subscriptions (mode: "test"), with livemode: false. A test post never answers as the duplicate of a live one.
Get each submission as a webhook
Subscribe a webhook to form.submitted. It fires for every accepted submission and for every held one you release. It is opt-in: a subscription receives it only when its events lists it by name. Each submission that makes a lead also sends lead.captured. The payload is in Webhook events.
Form kinds
A form's kind says what it is for: enquiry (the default), callback, support, newsletter, careers or other. newsletter and careers submissions never make leads: they stay submissions, and their form.submitted says "lead_id": null. Every other kind makes leads.
Read submissions with GET/api/forms/{id}/submissions, or export them as CSV with GET/api/forms/{id}/submissions/export.
Archive first, then delete permanently if you need to
Forms and submissions are archived first. Archiving is reversible; only an archived form or submission can then be deleted permanently.
- Archive a form with POST
/api/forms/{id}/archive(or Archive form in the console). Its keys stop accepting posts at once (403 form_archived), and it leaves the forms list. Its keys, Turnstile widget, submissions, files and leads are all kept, and an archived form cannot be changed. POST/api/forms/{id}/restorebrings it back as it was. List archived forms withGET /v1/forms?archived=true. - Archive a submission with POST
/api/forms/{id}/submissions/{sid}/archive. It leaves the submissions list and the CSV export; its files still download and its lead stays. POST/api/forms/{id}/submissions/{sid}/restorebrings it back. Passarchived=trueto the list or the export to see only archived ones. - Delete permanently with DELETE
/api/forms/{id}or DELETE/api/forms/{id}/submissions/{sid}(or Delete permanently on an archived form or submission in the console). This cannot be undone: a form goes with its keys, Turnstile widget, submissions and files; a submission with its files. Leads stay. A live one answers409 not_archived: archive it first. If a file cannot be deleted the answer is503 files_not_deletedand nothing is removed, so try again. A deleted file's stored copies expire within a day.
Otherwise, data about a person is removed in two ways only: an erasure request (POST/api/forms/erasures, which deletes their submissions, files and form leads, archived ones included), and the form's retention period (retention_days, 365 by default), after which submissions are deleted. Either way their files are deleted at once, and the files' stored copies expire within a day.
Form health
Brightshoal watches every form's live posts (test keys never count) and tells you when one stops working. Each problem is an incident; you are told when it opens, again if it turns critical, and when it ends, through a webhook subscribed to form.health.opened and form.health.resolved (opt-in, payloads in Webhook events) or a Slack rule with Form problems. Never by email. The console shows a health dot on the forms list and a banner on the form.
| Rule | Title | When it opens | Severity | When it ends |
|---|---|---|---|---|
form_quiet | No submissions to form in the last day (No Google leads, for a Google lead form) | An active form at least 15 days old had no accepted or held post in the last 24 hours, while the same day one week and two weeks earlier each had 3 or more | warning | At the next accepted or held post, or when the usual traffic no longer holds |
form_refusing | By reason, below | In the last hour one refusal reason reached 3 posts and half of the hour's posts | warning; critical at 10 and 80% | 30 minutes with no such refusal and an accepted post since, or 2 hours with none |
form_failing | form is failing to save submissions | 2 or more posts the platform could not store in the last hour | critical | 2 hours with none and an accepted post since, or 6 hours with none |
form_undelivered | form's submissions are not reaching your webhook | A form.submitted delivery failed, or is still pending after 10 minutes | warning; critical at 3, or once one gave up | When that subscription receives a later one, or after 24 hours |
form_refusing titles: form is refusing posts from your site (not an approved site), form is refusing posts for missing or invalid fields, form is failing Turnstile checks, Your site still posts to a paused form, Your site still posts to an archived form, Google lead form key does not match, and form hit its hourly limit. A wrong Google key and the hourly limit open at the first post; on a Google lead form every refusal does, since Google never resends a refused lead.
Each form shows health (ok, warning or critical), and GET /v1/forms/{id} adds stats: its accepted, held, refused and failed posts over the last 24 hours and 7 days. List incidents with GET /v1/forms/health (?project_id=, status=open|resolved, form_id=, cursor paged). An admin can close one with POST /v1/forms/health/{incidentId}/resolve (Resolve in the console): the same problem does not reopen for 24 hours. Archiving a form resolves its incidents, except the one saying a site still posts to it.
Google lead form ads
A lead form ad's leads can arrive in Brightshoal as they do from your site: each one becomes a submission and a lead, next to your chat and form leads, marked Google lead form (channel ad_form), with the campaign, ad group, Google form and click ids Google sent.
Set it up
- Create the connection: New form, then Google lead form in the console, or
POST /v1/formswith"channel": "google_lead_form". It is a form, so its keys, submissions, export, replay, erasure, retention, archive and delete work as for any form. On it,approved_sites,redirect_url,thank_you,turnstile,honeypot_field,hold_unsure,fields,unknown_fieldsandfield_mapdo not apply (400 not_for_google_forms), andchannelnever changes (400 channel_immutable). - Copy the webhook URL and the key from the form's setup card, or from
GET /v1/forms/{id}/google(admins only):webhook_url,test_webhook_urlandgoogle_key. - In Google Ads, open the lead form, then Export leads, Other data integration options, Webhook integration. Paste the URL and the key.
- Press Send test data. The test lead shows on the setup card with its fields as received, so you can check the field names. Then save the lead form in Google Ads.
One connection can take several Google lead forms: give each the same URL and key.
The key and rotation
The key (gk_...) is a secret Google sends with every lead; a lead with the wrong key is refused. POST /v1/forms/{id}/google/rotate-key makes a new one, and the old one keeps working for 7 days so you can update Google Ads. After that a lead with the old key is refused, and form health raises Google lead form key does not match at once: those leads are only in Google now, so download them from Google Ads within 30 days.
Field names
Each answer becomes a field. Google's standard questions keep their id in lowercase (full_name, email, phone_number, postal_code, company_name, ...); other questions are named after their text (What is your budget? becomes what_is_your_budget). Override a name with column_map in PATCH /v1/forms/{id}/google ({ "column_map": { "<question id>": "budget" } }, at most 100). The lead's name is full_name (else first_name and last_name), its email email (else work_email) and its phone phone_number (else work_phone), as Google sent it. A lead with neither an email nor a phone is kept as a submission without a lead. Fields that look like a card or national id are dropped, as on any form.
Who exports and uploads
Google allows one data integration per lead form. Record who exports these leads (lead_export: brightshoal or other_tool) and who uploads later outcomes to Google (outcome_uploads: none, brightshoal or client_crm) with PATCH /v1/forms/{id}/google. Brightshoal uploads nothing to Google today; the record is for your team.
Test leads
A lead sent with Send test data (is_test: true) or to the test_webhook_url is stored as a test submission and a test lead. It is never posted to Slack and goes only to test webhook subscriptions. Test leads are never deduplicated, since Google may reuse one test id.
What Google is told
| Answer | Meaning |
|---|---|
200 {} | Stored, or a lead already stored (Google retries the same lead_id; it is stored once) |
400 | Not JSON, or no lead_id. Google does not resend it |
401 invalid_google_key | The key does not match. Google does not resend it |
403 form_paused, 403 form_archived | The connection is paused or archived. Google does not resend it |
404 unknown_key | Not a Google lead form's URL |
503 | Over 1,200 leads an hour for this connection, with Retry-After: 300. Google retries, so the lead is delayed, not lost |
500 | The platform could not store it. Google retries |
Do not count it twice
Google already counted each lead form lead as a conversion. Its lead.captured says data.channel: "ad_form" and carries data.attribution.ad_form with capture_conversion: false and no visit, and form.submitted has data.form.channel: "google_lead_form" and data.submission.ad. When channel is ad_form, do not upload a lead conversion; upload only later outcomes (a sale, a qualified lead) against gcl_id.