BrightshoalDocsOpen console
MenuForms

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.

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_idstring

  • channelstring

    Default website. google_lead_form also makes its Google key. On a Google lead form, approved_sites, redirect_url, thank_you, turnstile, honeypot_field, hold_unsure, fields, unknown_fields and field_map do not apply: setting one is 400 not_for_google_forms.

    One of website google_lead_form

  • namestringrequiredup to 200 characters

  • statusstring

    A paused form refuses posts.

    One of active paused

  • kindstring

    What the form is for. Default enquiry. newsletter and careers submissions never make leads.

    One of enquiry callback support newsletter careers other

  • unknown_fieldsstring

    keep (default) keeps submitted fields the definition does not name; reject refuses the post (unknown). Controls are never fields, and an empty definition never refuses.

    One of keep reject

  • approved_sitesarray of stringup to 20 items

    Hosts 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 (403 site_not_approved) until a site is added. Test keys skip the check.

  • redirect_urlstring | nulluri

    Where a browser goes after a post, unless the post names an approved _redirect. Null: the hosted thank-you page.

  • thank_youobject | null

    The hosted thank-you page's text.

    2 attributes
    • titlestringup to 200 characters

    • bodystringup to 2000 characters

  • honeypot_fieldstring

    A 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, any utm_*, a click id), a defined field's key or a name the field map reads.

  • hold_unsureboolean

    Hold submissions the spam check is unsure about for review.

  • fieldsarray of FormFieldup to 50 items

    The fields the form defines, checked in order: a blank required field is missing, then the type (invalid), length, range and pattern. A key that names a password, card number or national id is refused. Fields the form does not define are kept (see unknown_fields). Empty: any fields are accepted.

    10 attributes
    • keystringrequiredup to 64 characters

      The field's name in the post.

    • labelstringup to 200 characters

    • typestringrequired

      One of text email phone textarea url number date time datetime select multiselect checkbox consent file

    • requiredboolean

      Default false

    • optionsarray of string

      The values a post may send: required for select and multiselect, optional for checkbox (a group).

    • helpstringup to 500 characters

    • placeholderstringup to 200 characters

    • validationobject

      7 attributes
      • min_lengthinteger0 to 5000

        text, textarea, email, phone, url.

      • max_lengthinteger1 to 5000

        text, textarea, email, phone, url.

      • minnumber | string

        number: a number; date, time, datetime: a value of that type; multiselect, checkbox group: a count of choices.

      • maxnumber | string

        As min.

      • integerboolean

        number only.

      • patternstringup to 500 characters

        RE2 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 characters

        Replaces the default error message.

    • fileobject

      A file field's limits.

      3 attributes
      • acceptarray of stringup to 30 items

      • max_size_mbinteger1 to 10

      • max_filesinteger1 to 5

    • consentobject

      A consent field 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 named key whose value is the wording version. A ticked box on a post with a phone records a form grant 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, yes or 1) is stored as yes, and it may be required.

      2 attributes
      • channelstringrequired

        One of whatsapp sms voice_human

      • purposestringrequired

        One of service marketing

  • field_mapobject

    Which submitted fields hold the person's name, email and phone. Defaults: name, email, phone.

    3 attributes
    • namestring

    • emailstring

    • phonestring

  • retention_daysinteger1 to 3650

    Days a submission is kept. Default 365.

Returns

201 OK

Response attributes
  • dataFormrequired

    26 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • namestringrequiredup to 200 characters

    • statusstringrequired

      A paused form refuses posts.

      One of active paused

    • kindstring

      What the form is for. Default enquiry. newsletter and careers submissions never make leads.

      One of enquiry callback support newsletter careers other

    • unknown_fieldsstring

      keep (default) keeps submitted fields the definition does not name; reject refuses the post (unknown). Controls are never fields, and an empty definition never refuses.

      One of keep reject

    • approved_sitesarray of stringup to 20 items

      Hosts 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 (403 site_not_approved) until a site is added. Test keys skip the check.

    • redirect_urlstring | nulluri

      Where a browser goes after a post, unless the post names an approved _redirect. Null: the hosted thank-you page.

    • thank_youobject | null

      The hosted thank-you page's text.

      2 attributes
      • titlestringup to 200 characters

      • bodystringup to 2000 characters

    • honeypot_fieldstring

      A 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, any utm_*, a click id), a defined field's key or a name the field map reads.

    • hold_unsureboolean

      Hold submissions the spam check is unsure about for review.

    • fieldsarray of FormFieldrequiredup to 50 items

      The fields the form defines, checked in order: a blank required field is missing, then the type (invalid), length, range and pattern. A key that names a password, card number or national id is refused. Fields the form does not define are kept (see unknown_fields). Empty: any fields are accepted.

      10 attributes
      • keystringrequiredup to 64 characters

        The field's name in the post.

      • labelstringup to 200 characters

      • typestringrequired

        One of text email phone textarea url number date time datetime select multiselect checkbox consent file

      • requiredboolean

        Default false

      • optionsarray of string

        The values a post may send: required for select and multiselect, optional for checkbox (a group).

      • helpstringup to 500 characters

      • placeholderstringup to 200 characters

      • validationobject

        7 attributes
        • min_lengthinteger0 to 5000

          text, textarea, email, phone, url.

        • max_lengthinteger1 to 5000

          text, textarea, email, phone, url.

        • minnumber | string

          number: a number; date, time, datetime: a value of that type; multiselect, checkbox group: a count of choices.

        • maxnumber | string

          As min.

        • integerboolean

          number only.

        • patternstringup to 500 characters

          RE2 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 characters

          Replaces the default error message.

      • fileobject

        A file field's limits.

        3 attributes
        • acceptarray of stringup to 30 items

        • max_size_mbinteger1 to 10

        • max_filesinteger1 to 5

      • consentobject

        A consent field 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 named key whose value is the wording version. A ticked box on a post with a phone records a form grant 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, yes or 1) is stored as yes, and it may be required.

        2 attributes
        • channelstringrequired

          One of whatsapp sms voice_human

        • purposestringrequired

          One of service marketing

    • field_mapobject

      Which submitted fields hold the person's name, email and phone. Defaults: name, email, phone.

      3 attributes
      • namestring

      • emailstring

      • phonestring

    • retention_daysinteger1 to 3650

      Days a submission is kept. Default 365.

    • turnstilestring

      One of off on

    • turnstile_site_keystring | null

    • turnstile_availableboolean

      Whether this deployment can turn Turnstile on (it has Cloudflare credentials).

    • channelstringrequired

      website, or google_lead_form for a Google lead form connection. Set on create, never changed.

      One of website google_lead_form

    • keysarray of FormKeyrequired

      5 attributes
      • idstringrequired

      • keystringrequired

        fkey_live_... or fkey_test_...: what the site posts to. Public, like the form's URL.

      • modestringrequired

        One of live test

      • expires_atstring | nullISO 8601 timestamp

        Set on a rotated key: when it stops working.

      • created_atstringISO 8601 timestamp

    • archived_atstring | nullISO 8601 timestamp

      When the form was archived; null when it is live.

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • healthstringrequired

      The worst open health incident (GET /v1/forms/health), or ok.

      One of ok warning critical

    • googleobject | null

      A Google lead form's ownership and arrivals, never its key; null for a website form.

      4 attributes
      • lead_exportstring

        One of brightshoal other_tool

      • outcome_uploadsstring

        One of none brightshoal client_crm

      • last_test_atstring | nullISO 8601 timestamp

      • last_lead_atstring | nullISO 8601 timestamp

    • statsobject

      GET /v1/forms/{id} only: live posts by outcome, from hourly counts.

      2 attributes
      • last_24hobject

        4 attributes
        • acceptedintegerrequired

        • heldintegerrequired

        • refusedintegerrequired

          Every refusal reason, the hourly limit included.

        • failedintegerrequired

      • last_7dobject

        4 attributes
        • acceptedintegerrequired

        • heldintegerrequired

        • refusedintegerrequired

          Every refusal reason, the hourly limit included.

        • failedintegerrequired

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
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": "Front desk"
}'
Response 201
{
  "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_idstring

    Only this project's forms.

  • archivedboolean

    true: only archived forms. Absent: only live ones.

Returns

200 OK

Response attributes
  • dataarray of Formrequired

    26 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • namestringrequiredup to 200 characters

    • statusstringrequired

      A paused form refuses posts.

      One of active paused

    • kindstring

      What the form is for. Default enquiry. newsletter and careers submissions never make leads.

      One of enquiry callback support newsletter careers other

    • unknown_fieldsstring

      keep (default) keeps submitted fields the definition does not name; reject refuses the post (unknown). Controls are never fields, and an empty definition never refuses.

      One of keep reject

    • approved_sitesarray of stringup to 20 items

      Hosts 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 (403 site_not_approved) until a site is added. Test keys skip the check.

    • redirect_urlstring | nulluri

      Where a browser goes after a post, unless the post names an approved _redirect. Null: the hosted thank-you page.

    • thank_youobject | null

      The hosted thank-you page's text.

      2 attributes
      • titlestringup to 200 characters

      • bodystringup to 2000 characters

    • honeypot_fieldstring

      A 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, any utm_*, a click id), a defined field's key or a name the field map reads.

    • hold_unsureboolean

      Hold submissions the spam check is unsure about for review.

    • fieldsarray of FormFieldrequiredup to 50 items

      The fields the form defines, checked in order: a blank required field is missing, then the type (invalid), length, range and pattern. A key that names a password, card number or national id is refused. Fields the form does not define are kept (see unknown_fields). Empty: any fields are accepted.

      10 attributes
      • keystringrequiredup to 64 characters

        The field's name in the post.

      • labelstringup to 200 characters

      • typestringrequired

        One of text email phone textarea url number date time datetime select multiselect checkbox consent file

      • requiredboolean

        Default false

      • optionsarray of string

        The values a post may send: required for select and multiselect, optional for checkbox (a group).

      • helpstringup to 500 characters

      • placeholderstringup to 200 characters

      • validationobject

        7 attributes
        • min_lengthinteger0 to 5000

          text, textarea, email, phone, url.

        • max_lengthinteger1 to 5000

          text, textarea, email, phone, url.

        • minnumber | string

          number: a number; date, time, datetime: a value of that type; multiselect, checkbox group: a count of choices.

        • maxnumber | string

          As min.

        • integerboolean

          number only.

        • patternstringup to 500 characters

          RE2 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 characters

          Replaces the default error message.

      • fileobject

        A file field's limits.

        3 attributes
        • acceptarray of stringup to 30 items

        • max_size_mbinteger1 to 10

        • max_filesinteger1 to 5

      • consentobject

        A consent field 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 named key whose value is the wording version. A ticked box on a post with a phone records a form grant 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, yes or 1) is stored as yes, and it may be required.

        2 attributes
        • channelstringrequired

          One of whatsapp sms voice_human

        • purposestringrequired

          One of service marketing

    • field_mapobject

      Which submitted fields hold the person's name, email and phone. Defaults: name, email, phone.

      3 attributes
      • namestring

      • emailstring

      • phonestring

    • retention_daysinteger1 to 3650

      Days a submission is kept. Default 365.

    • turnstilestring

      One of off on

    • turnstile_site_keystring | null

    • turnstile_availableboolean

      Whether this deployment can turn Turnstile on (it has Cloudflare credentials).

    • channelstringrequired

      website, or google_lead_form for a Google lead form connection. Set on create, never changed.

      One of website google_lead_form

    • keysarray of FormKeyrequired

      5 attributes
      • idstringrequired

      • keystringrequired

        fkey_live_... or fkey_test_...: what the site posts to. Public, like the form's URL.

      • modestringrequired

        One of live test

      • expires_atstring | nullISO 8601 timestamp

        Set on a rotated key: when it stops working.

      • created_atstringISO 8601 timestamp

    • archived_atstring | nullISO 8601 timestamp

      When the form was archived; null when it is live.

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • healthstringrequired

      The worst open health incident (GET /v1/forms/health), or ok.

      One of ok warning critical

    • googleobject | null

      A Google lead form's ownership and arrivals, never its key; null for a website form.

      4 attributes
      • lead_exportstring

        One of brightshoal other_tool

      • outcome_uploadsstring

        One of none brightshoal client_crm

      • last_test_atstring | nullISO 8601 timestamp

      • last_lead_atstring | nullISO 8601 timestamp

    • statsobject

      GET /v1/forms/{id} only: live posts by outcome, from hourly counts.

      2 attributes
      • last_24hobject

        4 attributes
        • acceptedintegerrequired

        • heldintegerrequired

        • refusedintegerrequired

          Every refusal reason, the hourly limit included.

        • failedintegerrequired

      • last_7dobject

        4 attributes
        • acceptedintegerrequired

        • heldintegerrequired

        • refusedintegerrequired

          Every refusal reason, the hourly limit included.

        • failedintegerrequired

  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
GET /api/forms
curl "https://api.brightshoal.com/api/forms" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    Form id, form_....

Returns

200 OK

Response attributes
  • dataFormrequired

    26 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • namestringrequiredup to 200 characters

    • statusstringrequired

      A paused form refuses posts.

      One of active paused

    • kindstring

      What the form is for. Default enquiry. newsletter and careers submissions never make leads.

      One of enquiry callback support newsletter careers other

    • unknown_fieldsstring

      keep (default) keeps submitted fields the definition does not name; reject refuses the post (unknown). Controls are never fields, and an empty definition never refuses.

      One of keep reject

    • approved_sitesarray of stringup to 20 items

      Hosts 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 (403 site_not_approved) until a site is added. Test keys skip the check.

    • redirect_urlstring | nulluri

      Where a browser goes after a post, unless the post names an approved _redirect. Null: the hosted thank-you page.

    • thank_youobject | null

      The hosted thank-you page's text.

      2 attributes
      • titlestringup to 200 characters

      • bodystringup to 2000 characters

    • honeypot_fieldstring

      A 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, any utm_*, a click id), a defined field's key or a name the field map reads.

    • hold_unsureboolean

      Hold submissions the spam check is unsure about for review.

    • fieldsarray of FormFieldrequiredup to 50 items

      The fields the form defines, checked in order: a blank required field is missing, then the type (invalid), length, range and pattern. A key that names a password, card number or national id is refused. Fields the form does not define are kept (see unknown_fields). Empty: any fields are accepted.

      10 attributes
      • keystringrequiredup to 64 characters

        The field's name in the post.

      • labelstringup to 200 characters

      • typestringrequired

        One of text email phone textarea url number date time datetime select multiselect checkbox consent file

      • requiredboolean

        Default false

      • optionsarray of string

        The values a post may send: required for select and multiselect, optional for checkbox (a group).

      • helpstringup to 500 characters

      • placeholderstringup to 200 characters

      • validationobject

        7 attributes
        • min_lengthinteger0 to 5000

          text, textarea, email, phone, url.

        • max_lengthinteger1 to 5000

          text, textarea, email, phone, url.

        • minnumber | string

          number: a number; date, time, datetime: a value of that type; multiselect, checkbox group: a count of choices.

        • maxnumber | string

          As min.

        • integerboolean

          number only.

        • patternstringup to 500 characters

          RE2 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 characters

          Replaces the default error message.

      • fileobject

        A file field's limits.

        3 attributes
        • acceptarray of stringup to 30 items

        • max_size_mbinteger1 to 10

        • max_filesinteger1 to 5

      • consentobject

        A consent field 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 named key whose value is the wording version. A ticked box on a post with a phone records a form grant 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, yes or 1) is stored as yes, and it may be required.

        2 attributes
        • channelstringrequired

          One of whatsapp sms voice_human

        • purposestringrequired

          One of service marketing

    • field_mapobject

      Which submitted fields hold the person's name, email and phone. Defaults: name, email, phone.

      3 attributes
      • namestring

      • emailstring

      • phonestring

    • retention_daysinteger1 to 3650

      Days a submission is kept. Default 365.

    • turnstilestring

      One of off on

    • turnstile_site_keystring | null

    • turnstile_availableboolean

      Whether this deployment can turn Turnstile on (it has Cloudflare credentials).

    • channelstringrequired

      website, or google_lead_form for a Google lead form connection. Set on create, never changed.

      One of website google_lead_form

    • keysarray of FormKeyrequired

      5 attributes
      • idstringrequired

      • keystringrequired

        fkey_live_... or fkey_test_...: what the site posts to. Public, like the form's URL.

      • modestringrequired

        One of live test

      • expires_atstring | nullISO 8601 timestamp

        Set on a rotated key: when it stops working.

      • created_atstringISO 8601 timestamp

    • archived_atstring | nullISO 8601 timestamp

      When the form was archived; null when it is live.

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • healthstringrequired

      The worst open health incident (GET /v1/forms/health), or ok.

      One of ok warning critical

    • googleobject | null

      A Google lead form's ownership and arrivals, never its key; null for a website form.

      4 attributes
      • lead_exportstring

        One of brightshoal other_tool

      • outcome_uploadsstring

        One of none brightshoal client_crm

      • last_test_atstring | nullISO 8601 timestamp

      • last_lead_atstring | nullISO 8601 timestamp

    • statsobject

      GET /v1/forms/{id} only: live posts by outcome, from hourly counts.

      2 attributes
      • last_24hobject

        4 attributes
        • acceptedintegerrequired

        • heldintegerrequired

        • refusedintegerrequired

          Every refusal reason, the hourly limit included.

        • failedintegerrequired

      • last_7dobject

        4 attributes
        • acceptedintegerrequired

        • heldintegerrequired

        • refusedintegerrequired

          Every 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). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
GET /api/forms/{id}
curl "https://api.brightshoal.com/api/forms/FORM_ID" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    Form id, form_....

Request body

  • namestringup to 200 characters

  • statusstring

    A paused form refuses posts.

    One of active paused

  • kindstring

    What the form is for. Default enquiry. newsletter and careers submissions never make leads.

    One of enquiry callback support newsletter careers other

  • unknown_fieldsstring

    keep (default) keeps submitted fields the definition does not name; reject refuses the post (unknown). Controls are never fields, and an empty definition never refuses.

    One of keep reject

  • approved_sitesarray of stringup to 20 items

    Hosts 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 (403 site_not_approved) until a site is added. Test keys skip the check.

  • redirect_urlstring | nulluri

    Where a browser goes after a post, unless the post names an approved _redirect. Null: the hosted thank-you page.

  • thank_youobject | null

    The hosted thank-you page's text.

    2 attributes
    • titlestringup to 200 characters

    • bodystringup to 2000 characters

  • honeypot_fieldstring

    A 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, any utm_*, a click id), a defined field's key or a name the field map reads.

  • hold_unsureboolean

    Hold submissions the spam check is unsure about for review.

  • fieldsarray of FormFieldup to 50 items

    The fields the form defines, checked in order: a blank required field is missing, then the type (invalid), length, range and pattern. A key that names a password, card number or national id is refused. Fields the form does not define are kept (see unknown_fields). Empty: any fields are accepted.

    10 attributes
    • keystringrequiredup to 64 characters

      The field's name in the post.

    • labelstringup to 200 characters

    • typestringrequired

      One of text email phone textarea url number date time datetime select multiselect checkbox consent file

    • requiredboolean

      Default false

    • optionsarray of string

      The values a post may send: required for select and multiselect, optional for checkbox (a group).

    • helpstringup to 500 characters

    • placeholderstringup to 200 characters

    • validationobject

      7 attributes
      • min_lengthinteger0 to 5000

        text, textarea, email, phone, url.

      • max_lengthinteger1 to 5000

        text, textarea, email, phone, url.

      • minnumber | string

        number: a number; date, time, datetime: a value of that type; multiselect, checkbox group: a count of choices.

      • maxnumber | string

        As min.

      • integerboolean

        number only.

      • patternstringup to 500 characters

        RE2 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 characters

        Replaces the default error message.

    • fileobject

      A file field's limits.

      3 attributes
      • acceptarray of stringup to 30 items

      • max_size_mbinteger1 to 10

      • max_filesinteger1 to 5

    • consentobject

      A consent field 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 named key whose value is the wording version. A ticked box on a post with a phone records a form grant 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, yes or 1) is stored as yes, and it may be required.

      2 attributes
      • channelstringrequired

        One of whatsapp sms voice_human

      • purposestringrequired

        One of service marketing

  • field_mapobject

    Which submitted fields hold the person's name, email and phone. Defaults: name, email, phone.

    3 attributes
    • namestring

    • emailstring

    • phonestring

  • retention_daysinteger1 to 3650

    Days a submission is kept. Default 365.

  • turnstilestring

    One of off on

Returns

200 OK

Response attributes
  • dataFormrequired

    26 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • namestringrequiredup to 200 characters

    • statusstringrequired

      A paused form refuses posts.

      One of active paused

    • kindstring

      What the form is for. Default enquiry. newsletter and careers submissions never make leads.

      One of enquiry callback support newsletter careers other

    • unknown_fieldsstring

      keep (default) keeps submitted fields the definition does not name; reject refuses the post (unknown). Controls are never fields, and an empty definition never refuses.

      One of keep reject

    • approved_sitesarray of stringup to 20 items

      Hosts 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 (403 site_not_approved) until a site is added. Test keys skip the check.

    • redirect_urlstring | nulluri

      Where a browser goes after a post, unless the post names an approved _redirect. Null: the hosted thank-you page.

    • thank_youobject | null

      The hosted thank-you page's text.

      2 attributes
      • titlestringup to 200 characters

      • bodystringup to 2000 characters

    • honeypot_fieldstring

      A 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, any utm_*, a click id), a defined field's key or a name the field map reads.

    • hold_unsureboolean

      Hold submissions the spam check is unsure about for review.

    • fieldsarray of FormFieldrequiredup to 50 items

      The fields the form defines, checked in order: a blank required field is missing, then the type (invalid), length, range and pattern. A key that names a password, card number or national id is refused. Fields the form does not define are kept (see unknown_fields). Empty: any fields are accepted.

      10 attributes
      • keystringrequiredup to 64 characters

        The field's name in the post.

      • labelstringup to 200 characters

      • typestringrequired

        One of text email phone textarea url number date time datetime select multiselect checkbox consent file

      • requiredboolean

        Default false

      • optionsarray of string

        The values a post may send: required for select and multiselect, optional for checkbox (a group).

      • helpstringup to 500 characters

      • placeholderstringup to 200 characters

      • validationobject

        7 attributes
        • min_lengthinteger0 to 5000

          text, textarea, email, phone, url.

        • max_lengthinteger1 to 5000

          text, textarea, email, phone, url.

        • minnumber | string

          number: a number; date, time, datetime: a value of that type; multiselect, checkbox group: a count of choices.

        • maxnumber | string

          As min.

        • integerboolean

          number only.

        • patternstringup to 500 characters

          RE2 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 characters

          Replaces the default error message.

      • fileobject

        A file field's limits.

        3 attributes
        • acceptarray of stringup to 30 items

        • max_size_mbinteger1 to 10

        • max_filesinteger1 to 5

      • consentobject

        A consent field 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 named key whose value is the wording version. A ticked box on a post with a phone records a form grant 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, yes or 1) is stored as yes, and it may be required.

        2 attributes
        • channelstringrequired

          One of whatsapp sms voice_human

        • purposestringrequired

          One of service marketing

    • field_mapobject

      Which submitted fields hold the person's name, email and phone. Defaults: name, email, phone.

      3 attributes
      • namestring

      • emailstring

      • phonestring

    • retention_daysinteger1 to 3650

      Days a submission is kept. Default 365.

    • turnstilestring

      One of off on

    • turnstile_site_keystring | null

    • turnstile_availableboolean

      Whether this deployment can turn Turnstile on (it has Cloudflare credentials).

    • channelstringrequired

      website, or google_lead_form for a Google lead form connection. Set on create, never changed.

      One of website google_lead_form

    • keysarray of FormKeyrequired

      5 attributes
      • idstringrequired

      • keystringrequired

        fkey_live_... or fkey_test_...: what the site posts to. Public, like the form's URL.

      • modestringrequired

        One of live test

      • expires_atstring | nullISO 8601 timestamp

        Set on a rotated key: when it stops working.

      • created_atstringISO 8601 timestamp

    • archived_atstring | nullISO 8601 timestamp

      When the form was archived; null when it is live.

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • healthstringrequired

      The worst open health incident (GET /v1/forms/health), or ok.

      One of ok warning critical

    • googleobject | null

      A Google lead form's ownership and arrivals, never its key; null for a website form.

      4 attributes
      • lead_exportstring

        One of brightshoal other_tool

      • outcome_uploadsstring

        One of none brightshoal client_crm

      • last_test_atstring | nullISO 8601 timestamp

      • last_lead_atstring | nullISO 8601 timestamp

    • statsobject

      GET /v1/forms/{id} only: live posts by outcome, from hourly counts.

      2 attributes
      • last_24hobject

        4 attributes
        • acceptedintegerrequired

        • heldintegerrequired

        • refusedintegerrequired

          Every refusal reason, the hourly limit included.

        • failedintegerrequired

      • last_7dobject

        4 attributes
        • acceptedintegerrequired

        • heldintegerrequired

        • refusedintegerrequired

          Every refusal reason, the hourly limit included.

        • failedintegerrequired

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 409 form_archived: restore the form first. turnstile_not_configured: this deployment has no Cloudflare credentials for Turnstile.
  • 422 turnstile_needs_sites or turnstile_too_many_sites.
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
  • 502 turnstile_unavailable: Cloudflare refused or did not answer.
PATCH /api/forms/{id}
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"
}'
Response 200
{
  "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

  • idstringrequired

    Form id, form_....

Request body

  • fieldsobjectrequired

    Name to value; a number or boolean is kept as text, a list joined with ", ", a null left out.

  • modestring

    One of live test

    Default "live"

  • page_urlstringup to 2000 characters

  • referrerstringup to 2000 characters

  • utmobject

  • click_idsobject

  • contextobject

    The _mlf object from forms.js, if the server has it.

Returns

201 Stored.

Response attributes
  • successtruerequired

  • submission_idstringrequired

  • lead_idstring | nullrequired

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

  • statusstringrequired

    One of accepted held released

  • 400 invalid_fields (with fields) or invalid_request.
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 form_archived or form_paused, or the key may not write.
  • 404 Not found, or outside what the key can see
  • 413 body_too_large.
  • 429 rate_limited: wait Retry-After seconds.
POST /api/forms/{id}/submissions
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"
  }
}'
Response 201
{
  "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

  • idstringrequired

    Form id, form_....

Query parameters

  • archivedboolean

    true: only archived submissions. Absent: only live ones.

  • statusstring

    Only submissions in this state (held: waiting for review). Absent: any.

    One of accepted held released

  • cursorstring

    Opaque next_cursor from the previous page. Keep the same filters while paging.

  • beforestringISO 8601 timestamp

    Only 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 200

    Default 50

Returns

200 OK

Response attributes
  • dataarray of FormSubmissionrequired

    24 attributes
    • idstringrequired

    • org_idstring

    • project_idstring

    • form_idstringrequired

    • key_idstring | null

    • modestringrequired

      One of live test

    • statusstringrequired

      One of accepted held released discarded

    • spam_reasonstring | null

      Why the spam check was unsure, comma-separated: links, disposable_email, markup, not_text, no_origin. Null when it found nothing.

    • fieldsobjectrequired

    • page_urlstring | null

    • referrerstring | null

    • utmobject | null

    • click_idsobject | null

    • originstring | null

    • countrystring | null

      ISO 3166-1 alpha-2, from the edge.

    • dropped_fieldsarray of string

      Keys 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 | null

      Consent fields ticked, with the wording (the field's label) agreed to.

      3 attributes
      • keystring

      • wordingstring

      • atstringISO 8601 timestamp

    • contextobject | null

      The page context forms.js sent (_mlf), or a server's context.

    • lead_idstring | null

      The lead it made, if any.

    • filesarray of object

      Its files; download one with GET /v1/forms/{id}/submissions/{sid}/files/{fileId}.

      6 attributes
      • idstringrequired

      • field_keystringrequired

      • filenamestringrequired

      • content_typestringrequired

        The type its bytes were sniffed as.

      • size_bytesintegerrequired

      • scan_statusstringrequired

        Its 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) or not_scanned (stored while scanning was off).

        One of pending clean infected unscannable not_scanned

    • archived_atstring | nullISO 8601 timestamp

      When the submission was archived; null when it is live.

    • external_idstring | null

      Google's lead_id for a Google lead form's lead; null for a website post.

    • adobject | null

      The 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), with capture_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 in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
GET /api/forms/{id}/submissions
curl "https://api.brightshoal.com/api/forms/FORM_ID/submissions" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    Form id, form_....

Returns

200 OK

Response attributes
  • dataDeleteResultrequired

    2 attributes
    • idstringrequired

    • deletedbooleanrequired

  • 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). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
  • 503 files_not_deleted: try again shortly.
DELETE /api/forms/{id}
curl -X DELETE "https://api.brightshoal.com/api/forms/FORM_ID" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    Form id, form_....

Returns

200 OK

Response attributes
  • dataFormrequired

    26 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • namestringrequiredup to 200 characters

    • statusstringrequired

      A paused form refuses posts.

      One of active paused

    • kindstring

      What the form is for. Default enquiry. newsletter and careers submissions never make leads.

      One of enquiry callback support newsletter careers other

    • unknown_fieldsstring

      keep (default) keeps submitted fields the definition does not name; reject refuses the post (unknown). Controls are never fields, and an empty definition never refuses.

      One of keep reject

    • approved_sitesarray of stringup to 20 items

      Hosts 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 (403 site_not_approved) until a site is added. Test keys skip the check.

    • redirect_urlstring | nulluri

      Where a browser goes after a post, unless the post names an approved _redirect. Null: the hosted thank-you page.

    • thank_youobject | null

      The hosted thank-you page's text.

      2 attributes
      • titlestringup to 200 characters

      • bodystringup to 2000 characters

    • honeypot_fieldstring

      A 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, any utm_*, a click id), a defined field's key or a name the field map reads.

    • hold_unsureboolean

      Hold submissions the spam check is unsure about for review.

    • fieldsarray of FormFieldrequiredup to 50 items

      The fields the form defines, checked in order: a blank required field is missing, then the type (invalid), length, range and pattern. A key that names a password, card number or national id is refused. Fields the form does not define are kept (see unknown_fields). Empty: any fields are accepted.

      10 attributes
      • keystringrequiredup to 64 characters

        The field's name in the post.

      • labelstringup to 200 characters

      • typestringrequired

        One of text email phone textarea url number date time datetime select multiselect checkbox consent file

      • requiredboolean

        Default false

      • optionsarray of string

        The values a post may send: required for select and multiselect, optional for checkbox (a group).

      • helpstringup to 500 characters

      • placeholderstringup to 200 characters

      • validationobject

        7 attributes
        • min_lengthinteger0 to 5000

          text, textarea, email, phone, url.

        • max_lengthinteger1 to 5000

          text, textarea, email, phone, url.

        • minnumber | string

          number: a number; date, time, datetime: a value of that type; multiselect, checkbox group: a count of choices.

        • maxnumber | string

          As min.

        • integerboolean

          number only.

        • patternstringup to 500 characters

          RE2 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 characters

          Replaces the default error message.

      • fileobject

        A file field's limits.

        3 attributes
        • acceptarray of stringup to 30 items

        • max_size_mbinteger1 to 10

        • max_filesinteger1 to 5

      • consentobject

        A consent field 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 named key whose value is the wording version. A ticked box on a post with a phone records a form grant 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, yes or 1) is stored as yes, and it may be required.

        2 attributes
        • channelstringrequired

          One of whatsapp sms voice_human

        • purposestringrequired

          One of service marketing

    • field_mapobject

      Which submitted fields hold the person's name, email and phone. Defaults: name, email, phone.

      3 attributes
      • namestring

      • emailstring

      • phonestring

    • retention_daysinteger1 to 3650

      Days a submission is kept. Default 365.

    • turnstilestring

      One of off on

    • turnstile_site_keystring | null

    • turnstile_availableboolean

      Whether this deployment can turn Turnstile on (it has Cloudflare credentials).

    • channelstringrequired

      website, or google_lead_form for a Google lead form connection. Set on create, never changed.

      One of website google_lead_form

    • keysarray of FormKeyrequired

      5 attributes
      • idstringrequired

      • keystringrequired

        fkey_live_... or fkey_test_...: what the site posts to. Public, like the form's URL.

      • modestringrequired

        One of live test

      • expires_atstring | nullISO 8601 timestamp

        Set on a rotated key: when it stops working.

      • created_atstringISO 8601 timestamp

    • archived_atstring | nullISO 8601 timestamp

      When the form was archived; null when it is live.

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • healthstringrequired

      The worst open health incident (GET /v1/forms/health), or ok.

      One of ok warning critical

    • googleobject | null

      A Google lead form's ownership and arrivals, never its key; null for a website form.

      4 attributes
      • lead_exportstring

        One of brightshoal other_tool

      • outcome_uploadsstring

        One of none brightshoal client_crm

      • last_test_atstring | nullISO 8601 timestamp

      • last_lead_atstring | nullISO 8601 timestamp

    • statsobject

      GET /v1/forms/{id} only: live posts by outcome, from hourly counts.

      2 attributes
      • last_24hobject

        4 attributes
        • acceptedintegerrequired

        • heldintegerrequired

        • refusedintegerrequired

          Every refusal reason, the hourly limit included.

        • failedintegerrequired

      • last_7dobject

        4 attributes
        • acceptedintegerrequired

        • heldintegerrequired

        • refusedintegerrequired

          Every 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). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
POST /api/forms/{id}/archive
curl -X POST "https://api.brightshoal.com/api/forms/FORM_ID/archive" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    Form id, form_....

Returns

200 OK

Response attributes
  • dataFormGoogleSetuprequired

    10 attributes
    • webhook_urlstring | nullrequired

      The live key's URL, for the Google Ads lead form; null with no live key or no public origin configured.

    • test_webhook_urlstring | nullrequired

      The test key's URL: every lead it gets is a test lead.

    • google_keystringrequired

      gk_...: the key Google Ads sends with each lead. A secret.

    • previous_key_expires_atstring | nullISO 8601 timestamp

      After a rotation: when the old key stops working.

    • column_mapobjectrequired

      Google question id to field key, overrides only.

    • lead_exportstringrequired

      One of brightshoal other_tool

    • outcome_uploadsstringrequired

      One of none brightshoal client_crm

    • google_form_idsarray of string

      Google lead form ids seen on live leads, at most 50.

    • last_test_atstring | nullISO 8601 timestamp

    • last_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). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
GET /api/forms/{id}/google
curl "https://api.brightshoal.com/api/forms/FORM_ID/google" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    Form id, form_....

Request body

  • column_mapobject

    Replaces the overrides: Google question id to field key.

  • lead_exportstring

    Who exports these leads.

    One of brightshoal other_tool

  • outcome_uploadsstring

    Who uploads later outcomes to Google. Brightshoal uploads nothing yet.

    One of none brightshoal client_crm

Returns

200 OK

Response attributes
  • dataFormGoogleSetuprequired

    10 attributes
    • webhook_urlstring | nullrequired

      The live key's URL, for the Google Ads lead form; null with no live key or no public origin configured.

    • test_webhook_urlstring | nullrequired

      The test key's URL: every lead it gets is a test lead.

    • google_keystringrequired

      gk_...: the key Google Ads sends with each lead. A secret.

    • previous_key_expires_atstring | nullISO 8601 timestamp

      After a rotation: when the old key stops working.

    • column_mapobjectrequired

      Google question id to field key, overrides only.

    • lead_exportstringrequired

      One of brightshoal other_tool

    • outcome_uploadsstringrequired

      One of none brightshoal client_crm

    • google_form_idsarray of string

      Google lead form ids seen on live leads, at most 50.

    • last_test_atstring | nullISO 8601 timestamp

    • last_lead_atstring | nullISO 8601 timestamp

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 409 form_archived: restore the form first.
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
PATCH /api/forms/{id}/google
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"
}'
Response 200
{
  "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

  • idstringrequired

    Form id, form_....

Returns

200 OK

Response attributes
  • dataFormGoogleSetuprequired

    10 attributes
    • webhook_urlstring | nullrequired

      The live key's URL, for the Google Ads lead form; null with no live key or no public origin configured.

    • test_webhook_urlstring | nullrequired

      The test key's URL: every lead it gets is a test lead.

    • google_keystringrequired

      gk_...: the key Google Ads sends with each lead. A secret.

    • previous_key_expires_atstring | nullISO 8601 timestamp

      After a rotation: when the old key stops working.

    • column_mapobjectrequired

      Google question id to field key, overrides only.

    • lead_exportstringrequired

      One of brightshoal other_tool

    • outcome_uploadsstringrequired

      One of none brightshoal client_crm

    • google_form_idsarray of string

      Google lead form ids seen on live leads, at most 50.

    • last_test_atstring | nullISO 8601 timestamp

    • last_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). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
POST /api/forms/{id}/google/rotate-key
curl -X POST "https://api.brightshoal.com/api/forms/FORM_ID/google/rotate-key" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    Form id, form_....

  • keyIdstringrequired

    The key's id.

Returns

200 OK

Response attributes
  • dataFormrequired

    26 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • namestringrequiredup to 200 characters

    • statusstringrequired

      A paused form refuses posts.

      One of active paused

    • kindstring

      What the form is for. Default enquiry. newsletter and careers submissions never make leads.

      One of enquiry callback support newsletter careers other

    • unknown_fieldsstring

      keep (default) keeps submitted fields the definition does not name; reject refuses the post (unknown). Controls are never fields, and an empty definition never refuses.

      One of keep reject

    • approved_sitesarray of stringup to 20 items

      Hosts 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 (403 site_not_approved) until a site is added. Test keys skip the check.

    • redirect_urlstring | nulluri

      Where a browser goes after a post, unless the post names an approved _redirect. Null: the hosted thank-you page.

    • thank_youobject | null

      The hosted thank-you page's text.

      2 attributes
      • titlestringup to 200 characters

      • bodystringup to 2000 characters

    • honeypot_fieldstring

      A 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, any utm_*, a click id), a defined field's key or a name the field map reads.

    • hold_unsureboolean

      Hold submissions the spam check is unsure about for review.

    • fieldsarray of FormFieldrequiredup to 50 items

      The fields the form defines, checked in order: a blank required field is missing, then the type (invalid), length, range and pattern. A key that names a password, card number or national id is refused. Fields the form does not define are kept (see unknown_fields). Empty: any fields are accepted.

      10 attributes
      • keystringrequiredup to 64 characters

        The field's name in the post.

      • labelstringup to 200 characters

      • typestringrequired

        One of text email phone textarea url number date time datetime select multiselect checkbox consent file

      • requiredboolean

        Default false

      • optionsarray of string

        The values a post may send: required for select and multiselect, optional for checkbox (a group).

      • helpstringup to 500 characters

      • placeholderstringup to 200 characters

      • validationobject

        7 attributes
        • min_lengthinteger0 to 5000

          text, textarea, email, phone, url.

        • max_lengthinteger1 to 5000

          text, textarea, email, phone, url.

        • minnumber | string

          number: a number; date, time, datetime: a value of that type; multiselect, checkbox group: a count of choices.

        • maxnumber | string

          As min.

        • integerboolean

          number only.

        • patternstringup to 500 characters

          RE2 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 characters

          Replaces the default error message.

      • fileobject

        A file field's limits.

        3 attributes
        • acceptarray of stringup to 30 items

        • max_size_mbinteger1 to 10

        • max_filesinteger1 to 5

      • consentobject

        A consent field 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 named key whose value is the wording version. A ticked box on a post with a phone records a form grant 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, yes or 1) is stored as yes, and it may be required.

        2 attributes
        • channelstringrequired

          One of whatsapp sms voice_human

        • purposestringrequired

          One of service marketing

    • field_mapobject

      Which submitted fields hold the person's name, email and phone. Defaults: name, email, phone.

      3 attributes
      • namestring

      • emailstring

      • phonestring

    • retention_daysinteger1 to 3650

      Days a submission is kept. Default 365.

    • turnstilestring

      One of off on

    • turnstile_site_keystring | null

    • turnstile_availableboolean

      Whether this deployment can turn Turnstile on (it has Cloudflare credentials).

    • channelstringrequired

      website, or google_lead_form for a Google lead form connection. Set on create, never changed.

      One of website google_lead_form

    • keysarray of FormKeyrequired

      5 attributes
      • idstringrequired

      • keystringrequired

        fkey_live_... or fkey_test_...: what the site posts to. Public, like the form's URL.

      • modestringrequired

        One of live test

      • expires_atstring | nullISO 8601 timestamp

        Set on a rotated key: when it stops working.

      • created_atstringISO 8601 timestamp

    • archived_atstring | nullISO 8601 timestamp

      When the form was archived; null when it is live.

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • healthstringrequired

      The worst open health incident (GET /v1/forms/health), or ok.

      One of ok warning critical

    • googleobject | null

      A Google lead form's ownership and arrivals, never its key; null for a website form.

      4 attributes
      • lead_exportstring

        One of brightshoal other_tool

      • outcome_uploadsstring

        One of none brightshoal client_crm

      • last_test_atstring | nullISO 8601 timestamp

      • last_lead_atstring | nullISO 8601 timestamp

    • statsobject

      GET /v1/forms/{id} only: live posts by outcome, from hourly counts.

      2 attributes
      • last_24hobject

        4 attributes
        • acceptedintegerrequired

        • heldintegerrequired

        • refusedintegerrequired

          Every refusal reason, the hourly limit included.

        • failedintegerrequired

      • last_7dobject

        4 attributes
        • acceptedintegerrequired

        • heldintegerrequired

        • refusedintegerrequired

          Every 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). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
POST /api/forms/{id}/keys/{keyId}/revoke
curl -X POST "https://api.brightshoal.com/api/forms/FORM_ID/keys/KEY_ID/revoke" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    Form id, form_....

Request body

  • modestringrequired

    One of live test

  • graceboolean

    False stops the current key at once instead of after 7 days.

Returns

200 OK

Response attributes
  • dataFormrequired

    26 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • namestringrequiredup to 200 characters

    • statusstringrequired

      A paused form refuses posts.

      One of active paused

    • kindstring

      What the form is for. Default enquiry. newsletter and careers submissions never make leads.

      One of enquiry callback support newsletter careers other

    • unknown_fieldsstring

      keep (default) keeps submitted fields the definition does not name; reject refuses the post (unknown). Controls are never fields, and an empty definition never refuses.

      One of keep reject

    • approved_sitesarray of stringup to 20 items

      Hosts 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 (403 site_not_approved) until a site is added. Test keys skip the check.

    • redirect_urlstring | nulluri

      Where a browser goes after a post, unless the post names an approved _redirect. Null: the hosted thank-you page.

    • thank_youobject | null

      The hosted thank-you page's text.

      2 attributes
      • titlestringup to 200 characters

      • bodystringup to 2000 characters

    • honeypot_fieldstring

      A 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, any utm_*, a click id), a defined field's key or a name the field map reads.

    • hold_unsureboolean

      Hold submissions the spam check is unsure about for review.

    • fieldsarray of FormFieldrequiredup to 50 items

      The fields the form defines, checked in order: a blank required field is missing, then the type (invalid), length, range and pattern. A key that names a password, card number or national id is refused. Fields the form does not define are kept (see unknown_fields). Empty: any fields are accepted.

      10 attributes
      • keystringrequiredup to 64 characters

        The field's name in the post.

      • labelstringup to 200 characters

      • typestringrequired

        One of text email phone textarea url number date time datetime select multiselect checkbox consent file

      • requiredboolean

        Default false

      • optionsarray of string

        The values a post may send: required for select and multiselect, optional for checkbox (a group).

      • helpstringup to 500 characters

      • placeholderstringup to 200 characters

      • validationobject

        7 attributes
        • min_lengthinteger0 to 5000

          text, textarea, email, phone, url.

        • max_lengthinteger1 to 5000

          text, textarea, email, phone, url.

        • minnumber | string

          number: a number; date, time, datetime: a value of that type; multiselect, checkbox group: a count of choices.

        • maxnumber | string

          As min.

        • integerboolean

          number only.

        • patternstringup to 500 characters

          RE2 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 characters

          Replaces the default error message.

      • fileobject

        A file field's limits.

        3 attributes
        • acceptarray of stringup to 30 items

        • max_size_mbinteger1 to 10

        • max_filesinteger1 to 5

      • consentobject

        A consent field 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 named key whose value is the wording version. A ticked box on a post with a phone records a form grant 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, yes or 1) is stored as yes, and it may be required.

        2 attributes
        • channelstringrequired

          One of whatsapp sms voice_human

        • purposestringrequired

          One of service marketing

    • field_mapobject

      Which submitted fields hold the person's name, email and phone. Defaults: name, email, phone.

      3 attributes
      • namestring

      • emailstring

      • phonestring

    • retention_daysinteger1 to 3650

      Days a submission is kept. Default 365.

    • turnstilestring

      One of off on

    • turnstile_site_keystring | null

    • turnstile_availableboolean

      Whether this deployment can turn Turnstile on (it has Cloudflare credentials).

    • channelstringrequired

      website, or google_lead_form for a Google lead form connection. Set on create, never changed.

      One of website google_lead_form

    • keysarray of FormKeyrequired

      5 attributes
      • idstringrequired

      • keystringrequired

        fkey_live_... or fkey_test_...: what the site posts to. Public, like the form's URL.

      • modestringrequired

        One of live test

      • expires_atstring | nullISO 8601 timestamp

        Set on a rotated key: when it stops working.

      • created_atstringISO 8601 timestamp

    • archived_atstring | nullISO 8601 timestamp

      When the form was archived; null when it is live.

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • healthstringrequired

      The worst open health incident (GET /v1/forms/health), or ok.

      One of ok warning critical

    • googleobject | null

      A Google lead form's ownership and arrivals, never its key; null for a website form.

      4 attributes
      • lead_exportstring

        One of brightshoal other_tool

      • outcome_uploadsstring

        One of none brightshoal client_crm

      • last_test_atstring | nullISO 8601 timestamp

      • last_lead_atstring | nullISO 8601 timestamp

    • statsobject

      GET /v1/forms/{id} only: live posts by outcome, from hourly counts.

      2 attributes
      • last_24hobject

        4 attributes
        • acceptedintegerrequired

        • heldintegerrequired

        • refusedintegerrequired

          Every refusal reason, the hourly limit included.

        • failedintegerrequired

      • last_7dobject

        4 attributes
        • acceptedintegerrequired

        • heldintegerrequired

        • refusedintegerrequired

          Every refusal reason, the hourly limit included.

        • failedintegerrequired

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 409 form_archived: restore the form first.
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
POST /api/forms/{id}/keys/rotate
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"
}'
Response 200
{
  "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

  • idstringrequired

    Form id, form_....

Returns

200 OK

Response attributes
  • dataFormrequired

    26 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • namestringrequiredup to 200 characters

    • statusstringrequired

      A paused form refuses posts.

      One of active paused

    • kindstring

      What the form is for. Default enquiry. newsletter and careers submissions never make leads.

      One of enquiry callback support newsletter careers other

    • unknown_fieldsstring

      keep (default) keeps submitted fields the definition does not name; reject refuses the post (unknown). Controls are never fields, and an empty definition never refuses.

      One of keep reject

    • approved_sitesarray of stringup to 20 items

      Hosts 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 (403 site_not_approved) until a site is added. Test keys skip the check.

    • redirect_urlstring | nulluri

      Where a browser goes after a post, unless the post names an approved _redirect. Null: the hosted thank-you page.

    • thank_youobject | null

      The hosted thank-you page's text.

      2 attributes
      • titlestringup to 200 characters

      • bodystringup to 2000 characters

    • honeypot_fieldstring

      A 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, any utm_*, a click id), a defined field's key or a name the field map reads.

    • hold_unsureboolean

      Hold submissions the spam check is unsure about for review.

    • fieldsarray of FormFieldrequiredup to 50 items

      The fields the form defines, checked in order: a blank required field is missing, then the type (invalid), length, range and pattern. A key that names a password, card number or national id is refused. Fields the form does not define are kept (see unknown_fields). Empty: any fields are accepted.

      10 attributes
      • keystringrequiredup to 64 characters

        The field's name in the post.

      • labelstringup to 200 characters

      • typestringrequired

        One of text email phone textarea url number date time datetime select multiselect checkbox consent file

      • requiredboolean

        Default false

      • optionsarray of string

        The values a post may send: required for select and multiselect, optional for checkbox (a group).

      • helpstringup to 500 characters

      • placeholderstringup to 200 characters

      • validationobject

        7 attributes
        • min_lengthinteger0 to 5000

          text, textarea, email, phone, url.

        • max_lengthinteger1 to 5000

          text, textarea, email, phone, url.

        • minnumber | string

          number: a number; date, time, datetime: a value of that type; multiselect, checkbox group: a count of choices.

        • maxnumber | string

          As min.

        • integerboolean

          number only.

        • patternstringup to 500 characters

          RE2 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 characters

          Replaces the default error message.

      • fileobject

        A file field's limits.

        3 attributes
        • acceptarray of stringup to 30 items

        • max_size_mbinteger1 to 10

        • max_filesinteger1 to 5

      • consentobject

        A consent field 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 named key whose value is the wording version. A ticked box on a post with a phone records a form grant 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, yes or 1) is stored as yes, and it may be required.

        2 attributes
        • channelstringrequired

          One of whatsapp sms voice_human

        • purposestringrequired

          One of service marketing

    • field_mapobject

      Which submitted fields hold the person's name, email and phone. Defaults: name, email, phone.

      3 attributes
      • namestring

      • emailstring

      • phonestring

    • retention_daysinteger1 to 3650

      Days a submission is kept. Default 365.

    • turnstilestring

      One of off on

    • turnstile_site_keystring | null

    • turnstile_availableboolean

      Whether this deployment can turn Turnstile on (it has Cloudflare credentials).

    • channelstringrequired

      website, or google_lead_form for a Google lead form connection. Set on create, never changed.

      One of website google_lead_form

    • keysarray of FormKeyrequired

      5 attributes
      • idstringrequired

      • keystringrequired

        fkey_live_... or fkey_test_...: what the site posts to. Public, like the form's URL.

      • modestringrequired

        One of live test

      • expires_atstring | nullISO 8601 timestamp

        Set on a rotated key: when it stops working.

      • created_atstringISO 8601 timestamp

    • archived_atstring | nullISO 8601 timestamp

      When the form was archived; null when it is live.

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • healthstringrequired

      The worst open health incident (GET /v1/forms/health), or ok.

      One of ok warning critical

    • googleobject | null

      A Google lead form's ownership and arrivals, never its key; null for a website form.

      4 attributes
      • lead_exportstring

        One of brightshoal other_tool

      • outcome_uploadsstring

        One of none brightshoal client_crm

      • last_test_atstring | nullISO 8601 timestamp

      • last_lead_atstring | nullISO 8601 timestamp

    • statsobject

      GET /v1/forms/{id} only: live posts by outcome, from hourly counts.

      2 attributes
      • last_24hobject

        4 attributes
        • acceptedintegerrequired

        • heldintegerrequired

        • refusedintegerrequired

          Every refusal reason, the hourly limit included.

        • failedintegerrequired

      • last_7dobject

        4 attributes
        • acceptedintegerrequired

        • heldintegerrequired

        • refusedintegerrequired

          Every 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). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
POST /api/forms/{id}/restore
curl -X POST "https://api.brightshoal.com/api/forms/FORM_ID/restore" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    Form id, form_....

  • sidstringrequired

    Submission id, fsub_....

Returns

200 OK

Response attributes
  • dataFormSubmissionrequired

    24 attributes
    • idstringrequired

    • org_idstring

    • project_idstring

    • form_idstringrequired

    • key_idstring | null

    • modestringrequired

      One of live test

    • statusstringrequired

      One of accepted held released discarded

    • spam_reasonstring | null

      Why the spam check was unsure, comma-separated: links, disposable_email, markup, not_text, no_origin. Null when it found nothing.

    • fieldsobjectrequired

    • page_urlstring | null

    • referrerstring | null

    • utmobject | null

    • click_idsobject | null

    • originstring | null

    • countrystring | null

      ISO 3166-1 alpha-2, from the edge.

    • dropped_fieldsarray of string

      Keys 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 | null

      Consent fields ticked, with the wording (the field's label) agreed to.

      3 attributes
      • keystring

      • wordingstring

      • atstringISO 8601 timestamp

    • contextobject | null

      The page context forms.js sent (_mlf), or a server's context.

    • lead_idstring | null

      The lead it made, if any.

    • filesarray of object

      Its files; download one with GET /v1/forms/{id}/submissions/{sid}/files/{fileId}.

      6 attributes
      • idstringrequired

      • field_keystringrequired

      • filenamestringrequired

      • content_typestringrequired

        The type its bytes were sniffed as.

      • size_bytesintegerrequired

      • scan_statusstringrequired

        Its 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) or not_scanned (stored while scanning was off).

        One of pending clean infected unscannable not_scanned

    • archived_atstring | nullISO 8601 timestamp

      When the submission was archived; null when it is live.

    • external_idstring | null

      Google's lead_id for a Google lead form's lead; null for a website post.

    • adobject | null

      The 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), with capture_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). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
GET /api/forms/{id}/submissions/{sid}
curl "https://api.brightshoal.com/api/forms/FORM_ID/submissions/SID" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    Form id, form_....

  • sidstringrequired

    Submission id, fsub_....

Returns

200 OK

Response attributes
  • dataDeleteResultrequired

    2 attributes
    • idstringrequired

    • deletedbooleanrequired

  • 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). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
  • 503 files_not_deleted: try again shortly.
DELETE /api/forms/{id}/submissions/{sid}
curl -X DELETE "https://api.brightshoal.com/api/forms/FORM_ID/submissions/SID" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    Form id, form_....

  • sidstringrequired

    Submission id, fsub_....

Returns

200 OK

Response attributes
  • dataFormSubmissionrequired

    24 attributes
    • idstringrequired

    • org_idstring

    • project_idstring

    • form_idstringrequired

    • key_idstring | null

    • modestringrequired

      One of live test

    • statusstringrequired

      One of accepted held released discarded

    • spam_reasonstring | null

      Why the spam check was unsure, comma-separated: links, disposable_email, markup, not_text, no_origin. Null when it found nothing.

    • fieldsobjectrequired

    • page_urlstring | null

    • referrerstring | null

    • utmobject | null

    • click_idsobject | null

    • originstring | null

    • countrystring | null

      ISO 3166-1 alpha-2, from the edge.

    • dropped_fieldsarray of string

      Keys 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 | null

      Consent fields ticked, with the wording (the field's label) agreed to.

      3 attributes
      • keystring

      • wordingstring

      • atstringISO 8601 timestamp

    • contextobject | null

      The page context forms.js sent (_mlf), or a server's context.

    • lead_idstring | null

      The lead it made, if any.

    • filesarray of object

      Its files; download one with GET /v1/forms/{id}/submissions/{sid}/files/{fileId}.

      6 attributes
      • idstringrequired

      • field_keystringrequired

      • filenamestringrequired

      • content_typestringrequired

        The type its bytes were sniffed as.

      • size_bytesintegerrequired

      • scan_statusstringrequired

        Its 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) or not_scanned (stored while scanning was off).

        One of pending clean infected unscannable not_scanned

    • archived_atstring | nullISO 8601 timestamp

      When the submission was archived; null when it is live.

    • external_idstring | null

      Google's lead_id for a Google lead form's lead; null for a website post.

    • adobject | null

      The 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), with capture_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). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
POST /api/forms/{id}/submissions/{sid}/archive
curl -X POST "https://api.brightshoal.com/api/forms/FORM_ID/submissions/SID/archive" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    Form id, form_....

  • sidstringrequired

    Submission id, fsub_....

  • fileIdstringrequired

    File 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). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
GET /api/forms/{id}/submissions/{sid}/files/{fileId}
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

  • idstringrequired

    Form id, form_....

  • sidstringrequired

    Submission id, fsub_....

Returns

200 OK

Response attributes
  • dataFormSubmissionrequired

    24 attributes
    • idstringrequired

    • org_idstring

    • project_idstring

    • form_idstringrequired

    • key_idstring | null

    • modestringrequired

      One of live test

    • statusstringrequired

      One of accepted held released discarded

    • spam_reasonstring | null

      Why the spam check was unsure, comma-separated: links, disposable_email, markup, not_text, no_origin. Null when it found nothing.

    • fieldsobjectrequired

    • page_urlstring | null

    • referrerstring | null

    • utmobject | null

    • click_idsobject | null

    • originstring | null

    • countrystring | null

      ISO 3166-1 alpha-2, from the edge.

    • dropped_fieldsarray of string

      Keys 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 | null

      Consent fields ticked, with the wording (the field's label) agreed to.

      3 attributes
      • keystring

      • wordingstring

      • atstringISO 8601 timestamp

    • contextobject | null

      The page context forms.js sent (_mlf), or a server's context.

    • lead_idstring | null

      The lead it made, if any.

    • filesarray of object

      Its files; download one with GET /v1/forms/{id}/submissions/{sid}/files/{fileId}.

      6 attributes
      • idstringrequired

      • field_keystringrequired

      • filenamestringrequired

      • content_typestringrequired

        The type its bytes were sniffed as.

      • size_bytesintegerrequired

      • scan_statusstringrequired

        Its 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) or not_scanned (stored while scanning was off).

        One of pending clean infected unscannable not_scanned

    • archived_atstring | nullISO 8601 timestamp

      When the submission was archived; null when it is live.

    • external_idstring | null

      Google's lead_id for a Google lead form's lead; null for a website post.

    • adobject | null

      The 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), with capture_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). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
POST /api/forms/{id}/submissions/{sid}/release
curl -X POST "https://api.brightshoal.com/api/forms/FORM_ID/submissions/SID/release" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    Form id, form_....

  • sidstringrequired

    Submission id, fsub_....

Request body

  • eventsarray of string

    Default: both.

Returns

200 How many deliveries were queued.

Response attributes
  • dataobject

    1 attribute
    • queuedintegerrequired

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 409 held: a held submission has sent nothing; release it. submission_archived: restore it first.
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
POST /api/forms/{id}/submissions/{sid}/replay
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"
  ]
}'
Response 200
{
  "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

  • idstringrequired

    Form id, form_....

  • sidstringrequired

    Submission id, fsub_....

Returns

200 OK

Response attributes
  • dataFormSubmissionrequired

    24 attributes
    • idstringrequired

    • org_idstring

    • project_idstring

    • form_idstringrequired

    • key_idstring | null

    • modestringrequired

      One of live test

    • statusstringrequired

      One of accepted held released discarded

    • spam_reasonstring | null

      Why the spam check was unsure, comma-separated: links, disposable_email, markup, not_text, no_origin. Null when it found nothing.

    • fieldsobjectrequired

    • page_urlstring | null

    • referrerstring | null

    • utmobject | null

    • click_idsobject | null

    • originstring | null

    • countrystring | null

      ISO 3166-1 alpha-2, from the edge.

    • dropped_fieldsarray of string

      Keys 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 | null

      Consent fields ticked, with the wording (the field's label) agreed to.

      3 attributes
      • keystring

      • wordingstring

      • atstringISO 8601 timestamp

    • contextobject | null

      The page context forms.js sent (_mlf), or a server's context.

    • lead_idstring | null

      The lead it made, if any.

    • filesarray of object

      Its files; download one with GET /v1/forms/{id}/submissions/{sid}/files/{fileId}.

      6 attributes
      • idstringrequired

      • field_keystringrequired

      • filenamestringrequired

      • content_typestringrequired

        The type its bytes were sniffed as.

      • size_bytesintegerrequired

      • scan_statusstringrequired

        Its 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) or not_scanned (stored while scanning was off).

        One of pending clean infected unscannable not_scanned

    • archived_atstring | nullISO 8601 timestamp

      When the submission was archived; null when it is live.

    • external_idstring | null

      Google's lead_id for a Google lead form's lead; null for a website post.

    • adobject | null

      The 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), with capture_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). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
POST /api/forms/{id}/submissions/{sid}/restore
curl -X POST "https://api.brightshoal.com/api/forms/FORM_ID/submissions/SID/restore" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    Form id, form_....

Query parameters

  • archivedboolean

    true: 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). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
GET /api/forms/{id}/submissions/export
curl "https://api.brightshoal.com/api/forms/FORM_ID/submissions/export" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -o attachment

Erase 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_idstring

  • emailstringemail

    An email address.

  • phonestring

    A phone number: 7 to 15 digits.

  • dry_runboolean

Returns

200 What was (or, on a dry run, would be) erased.

Response attributes
  • dataobject

    4 attributes
    • submissionsintegerrequired

    • filesintegerrequired

    • leadsintegerrequired

    • dry_runbooleanrequired

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
POST /api/forms/erasures
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"
}'
Response 200
{
  "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_idstring

  • statusstring

    One of open resolved

  • form_idstring

  • cursorstring

    Opaque next_cursor from the previous page.

  • limitinteger1 to 200

Returns

200 OK

Response attributes
  • dataarray of FormHealthIncidentrequired

    14 attributes
    • idstringrequired

    • form_idstringrequired

    • form_namestring

    • rulestringrequired

      One of form_quiet form_refusing form_failing form_undelivered

    • severitystringrequired

      One of warning critical

    • statusstringrequired

      One of open resolved

    • reasonstring | null

      form_refusing: the refusal (refused_site, refused_fields, refused_google_key, ...); else null.

    • detailobjectrequired

      The 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 timestamp

    • last_seen_atstringISO 8601 timestamp

    • opened_atstringrequiredISO 8601 timestamp

    • resolved_atstring | nullISO 8601 timestamp

    • resolutionstring | null

      One of recovered quiet manual form_archived

    • titlestring

      What the console and Slack show.

  • next_cursorstring | nullrequired

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

  • incidentIdstringrequired

    fhinc_....

Returns

200 OK

Response attributes
  • dataFormHealthIncidentrequired

    14 attributes
    • idstringrequired

    • form_idstringrequired

    • form_namestring

    • rulestringrequired

      One of form_quiet form_refusing form_failing form_undelivered

    • severitystringrequired

      One of warning critical

    • statusstringrequired

      One of open resolved

    • reasonstring | null

      form_refusing: the refusal (refused_site, refused_fields, refused_google_key, ...); else null.

    • detailobjectrequired

      The 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 timestamp

    • last_seen_atstringISO 8601 timestamp

    • opened_atstringrequiredISO 8601 timestamp

    • resolved_atstring | nullISO 8601 timestamp

    • resolutionstring | null

      One of recovered quiet manual form_archived

    • titlestring

      What 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). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
POST /api/forms/health/{incidentId}/resolve
curl -X POST "https://api.brightshoal.com/api/forms/health/INCIDENT_ID/resolve" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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"
  }
}