BrightshoalDocsOpen console
MenuAdd a form to your website

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 } }
    ]
  }'
Response 201
{
  "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.

KeyUse 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>:

HTML
<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-form marks the form for forms.js, which adds the page context on submit.
  • botcheck is the honeypot: a hidden field that people never see and bots fill. Keep it hidden and empty. The name is the form's honeypot_field.
  • _redirect is 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's redirect_url, or to a hosted thank-you page showing the form's thank_you text.

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.

HTML
<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:

brightshoalForms.context()
{
  "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":

HTML
<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.

TypeA value is valid whenRules it takes
textAny text. Runs of spaces become one.min_length, max_length, pattern
textareaAny text. Line breaks are kept.min_length, max_length, pattern
emailIt looks like name@domain.tld. Stored lowercased.min_length, max_length, pattern
phoneDigits with spaces, dots, dashes, brackets and a leading +; 7 to 15 digits. Stored as typed.min_length, max_length, pattern
urlAn absolute http:// or https:// URL.min_length, max_length, pattern
numberA plain decimal, such as -12 or 3.5. No +, exponent or thousands separators.min, max, integer
dateYYYY-MM-DD, a real calendar date.min, max as dates
timeHH:MM or HH:MM:SS, 24 hour.min, max as times
datetimeYYYY-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
selectExactly one of options (required).
multiselectEach value is one of options (required).min, max as a count of choices
checkboxWith options, a group: each value is one of them. Without, a single box: any value means ticked.min, max as a count of choices
consentTicked: 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.
fileSee 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.

fields
[
  { "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:

  1. A blank required field is missing. A blank optional field passes.
  2. The type: invalid.
  3. The length: too_short, too_long.
  4. The range: too_small, too_large.
  5. 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.

A file field
{ "key": "cv", "label": "CV", "type": "file", "required": true,
  "file": { "accept": [".pdf", ".docx"], "max_size_mb": 5, "max_files": 1 } }
HTML
<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>
SettingMeaning
file.acceptUp 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_mbPer file, 1 to 10. Default 5.
file.max_filesPer 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 file field takes the larger body: a multipart post to any other form is held to 64 KiB, like every other post, and over that is a 413.
  • A file's extension and its content (read from its first bytes) must both fit accept. So accept only 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 accept says: .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_large and too_many_files.
  • The field's value in the submission is the file names, joined with ", ". The files themselves are listed in the submission's files and in form.submitted.
  • A file sent under a name that is not a file field is not stored. Its key goes into dropped_fields and the post is still accepted, unless unknown_fields is reject.
  • When malware scanning is on, each file is scanned as it is stored. Each file in a submission has a scan_status: pending while 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) or not_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_scanning with Retry-After: 60; for an infected file it answers 410 file_infected. The links in form.submitted are made when the submission arrives, so a receiver that downloads at once should retry a 409 after the Retry-After.
  • Treat files as untrusted when you open them, scanned or not. Older Office files (.doc, .xls, .ppt) may contain macros; leave them out of accept if 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 sitesLive keyTest key
EmptyNo site may post: 403 site_not_approved.Any site may post.
ListedOnly those sites (and their subdomains).Any site may post.

The check runs twice:

  • In the browser (CORS). A fetch from an approved site can read the answer. From any other site, the answer carries no Access-Control-Allow-Origin, so the browser refuses it and your fetch rejects 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 its Referer, and refuses a live key's post from an unapproved site with 403 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 no Origin and no Referer. When any is found and the form holds unsure posts (hold_unsure, on by default), the submission is stored as held: 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}/release to 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-response to the post. A live key's post without a valid token is refused with 400 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..." }
  }'
FieldMeaning
fieldsRequired. Name to value: a string, a number or boolean (kept as text), an array of strings, or null (left out).
modelive (the default) or test, which stores a test submission.
page_url, referrerThe page the form was on and its referrer, up to 2,000 characters.
utmThe five utm_* parameters. Other keys are ignored.
click_idsgclid, gbraid, wbraid, fbclid, msclkid, ttclid, li_fat_id. Other keys are ignored.
contextThe 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.

Accepted
{
  "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.

Refused
{
  "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.

StatusMeansRetry?
200Accepted (a public post asking for JSON).No.
201Accepted (a server-to-server post).No.
303Accepted (a browser form post). Location is where the browser goes next.No.
400invalid_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.
403form_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.
404form_not_found: the key is unknown, revoked or expired.No.
413body_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.
415unsupported_content_type: not a form post, multipart or JSON.No.
429rate_limited: too many posts.Yes, after Retry-After seconds.
500internal_error: nothing was stored.Yes, once or twice with backoff.
503rate_limit_unavailable, turnstile_unavailable or files_unavailable: a dependency is briefly down.Yes, with backoff.

Each entry in fields has a problem:

problemMeaning
missingA required field is blank (or was dropped as sensitive).
invalidThe value is not of the field's type, or not one of its options.
too_short, too_longShorter than min_length or longer than max_length.
too_small, too_largeBelow min or above max (for a list, too few or too many choices).
patternDoes not match pattern.
unknownNot a field of this form, and unknown_fields is reject.
file_typeA file's extension or content is not accepted.
file_too_largeA file is over max_size_mb.
too_many_filesMore 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}/restore brings it back as it was. List archived forms with GET /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}/restore brings it back. Pass archived=true to 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 answers 409 not_archived: archive it first. If a file cannot be deleted the answer is 503 files_not_deleted and 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.

RuleTitleWhen it opensSeverityWhen it ends
form_quietNo 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 morewarningAt the next accepted or held post, or when the usual traffic no longer holds
form_refusingBy reason, belowIn the last hour one refusal reason reached 3 posts and half of the hour's postswarning; critical at 10 and 80%30 minutes with no such refusal and an accepted post since, or 2 hours with none
form_failingform is failing to save submissions2 or more posts the platform could not store in the last hourcritical2 hours with none and an accepted post since, or 6 hours with none
form_undeliveredform's submissions are not reaching your webhookA form.submitted delivery failed, or is still pending after 10 minuteswarning; critical at 3, or once one gave upWhen 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

  1. Create the connection: New form, then Google lead form in the console, or POST /v1/forms with "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_fields and field_map do not apply (400 not_for_google_forms), and channel never changes (400 channel_immutable).
  2. 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_url and google_key.
  3. In Google Ads, open the lead form, then Export leads, Other data integration options, Webhook integration. Paste the URL and the key.
  4. 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

AnswerMeaning
200 {}Stored, or a lead already stored (Google retries the same lead_id; it is stored once)
400Not JSON, or no lead_id. Google does not resend it
401 invalid_google_keyThe key does not match. Google does not resend it
403 form_paused, 403 form_archivedThe connection is paused or archived. Google does not resend it
404 unknown_keyNot a Google lead form's URL
503Over 1,200 leads an hour for this connection, with Retry-After: 300. Google retries, so the lead is delayed, not lost
500The 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.

Stuck on add a form to your website?