Lead forms

Hosted lead forms: their public page and embed snippet, fields and settings, and the submissions they received.

Every route takes Authorization: Bearer <ACCESS_TOKEN> unless the auth line says otherwise. Ids are numbers. Errors use the shape on the errors page.

Route	Scope	What it does
`GET /v1/lead-forms`	`lead_forms.read`	The hosted lead forms of a workspace, newest first.
`GET /v1/lead-forms/{id}`	`lead_forms.read`	One lead form with its fields and settings.
`POST /v1/lead-forms`	`lead_forms.write`	Create a hosted lead form.
`PATCH /v1/lead-forms/{id}`	`lead_forms.write`	Change a form's name, text, fields, settings or active state.
`DELETE /v1/lead-forms/{id}`	`lead_forms.write`	Delete a form; its page stops answering at once.
`GET /v1/lead-forms/{id}/submissions`	`lead_forms.read`	What was submitted on a form, newest first.

List lead forms

GET https://api.bluereacher.com/v1/lead-forms

Auth: Bearer access token. Scope: lead_forms.read.

The hosted lead forms of a workspace, newest first.

Each form has a public_url (the hosted page) and an embed_snippet for a website. A submission creates or updates the contact the form's fields map to and can start automations.

Parameters

Name	In	Type	Required	Description
`workspace_id`	query	number	yes	A workspace of the installer.
`search`	query	string	no	Part of a name.
`page`	query	number	no	Default 1.
`limit`	query	number	no	1–100, default 25.

Request

curl -X GET "https://api.bluereacher.com/v1/lead-forms?workspace_id=7&page=1&limit=25" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Responses

A 200 reply (OK):

{
  "success": true,
  "data": [
    {
      "id": 31,
      "workspace_id": 7,
      "name": "Website quote form",
      "slug": "f3a9c1d2e4b5f607",
      "title": "Get a quote",
      "description": "Tell us about your project.",
      "fields": [
        {
          "key": "first_name",
          "type": "text",
          "label": "First name",
          "required": true
        },
        {
          "key": "email",
          "type": "email",
          "label": "Email",
          "required": true
        },
        {
          "key": "phone_number",
          "type": "phone",
          "label": "Mobile",
          "required": false
        },
        {
          "key": "lead_source",
          "type": "select",
          "label": "How did you hear about us?",
          "options": [
            "Web",
            "Referral",
            "Event"
          ],
          "custom_field_id": 41
        },
        {
          "key": "sms_consent",
          "type": "sms_consent",
          "label": "Text me updates",
          "consent_text": "By ticking this box you agree to receive messages from Acme. Reply STOP to opt out."
        }
      ],
      "settings": {
        "submit_button_text": "Get a quote",
        "thank_you_message": "Thanks — we will be in touch today.",
        "redirect_url": null,
        "tags": [
          "web-lead"
        ],
        "allowed_domains": [
          "acme.example"
        ],
        "daily_limit": 500,
        "style": {
          "primary_color": "#2563eb",
          "button_text_color": "#ffffff",
          "background_color": "#ffffff",
          "page_background": "#f8fafc",
          "text_color": "#0f172a",
          "border_radius": 8,
          "font_family": "system"
        }
      },
      "is_active": true,
      "submission_count": 128,
      "created_at": "2026-10-01T00:00:00.000Z",
      "updated_at": "2026-11-01T00:00:00.000Z",
      "public_url": "https://api.bluereacher.com/f/f3a9c1d2e4b5f607",
      "embed_snippet": "<script src=\"https://api.bluereacher.com/embed/forms.js\" data-form=\"f3a9c1d2e4b5f607\" async></script>"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 1,
    "total_pages": 1
  }
}

Status	When	Message
200	OK
400	No workspace_id	`workspace_id is required.`
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): lead_forms.read. This integration was granted: …`
404	Workspace does not exist or is not the installer's (same response for both)	`Workspace not found or not accessible to this token`

Get lead form

GET https://api.bluereacher.com/v1/lead-forms/{id}

Auth: Bearer access token. Scope: lead_forms.read.

One lead form with its fields and settings.

Parameters

Name	In	Type	Required	Description
`id`	path	number	yes	The form id.

Request

curl -X GET "https://api.bluereacher.com/v1/lead-forms/31" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Responses

A 200 reply (OK):

{
  "success": true,
  "data": {
    "id": 31,
    "workspace_id": 7,
    "name": "Website quote form",
    "slug": "f3a9c1d2e4b5f607",
    "title": "Get a quote",
    "description": "Tell us about your project.",
    "fields": [
      {
        "key": "first_name",
        "type": "text",
        "label": "First name",
        "required": true
      },
      {
        "key": "email",
        "type": "email",
        "label": "Email",
        "required": true
      },
      {
        "key": "phone_number",
        "type": "phone",
        "label": "Mobile",
        "required": false
      },
      {
        "key": "lead_source",
        "type": "select",
        "label": "How did you hear about us?",
        "options": [
          "Web",
          "Referral",
          "Event"
        ],
        "custom_field_id": 41
      },
      {
        "key": "sms_consent",
        "type": "sms_consent",
        "label": "Text me updates",
        "consent_text": "By ticking this box you agree to receive messages from Acme. Reply STOP to opt out."
      }
    ],
    "settings": {
      "submit_button_text": "Get a quote",
      "thank_you_message": "Thanks — we will be in touch today.",
      "redirect_url": null,
      "tags": [
        "web-lead"
      ],
      "allowed_domains": [
        "acme.example"
      ],
      "daily_limit": 500,
      "style": {
        "primary_color": "#2563eb",
        "button_text_color": "#ffffff",
        "background_color": "#ffffff",
        "page_background": "#f8fafc",
        "text_color": "#0f172a",
        "border_radius": 8,
        "font_family": "system"
      }
    },
    "is_active": true,
    "submission_count": 128,
    "created_at": "2026-10-01T00:00:00.000Z",
    "updated_at": "2026-11-01T00:00:00.000Z",
    "public_url": "https://api.bluereacher.com/f/f3a9c1d2e4b5f607",
    "embed_snippet": "<script src=\"https://api.bluereacher.com/embed/forms.js\" data-form=\"f3a9c1d2e4b5f607\" async></script>"
  }
}

Status	When	Message
200	OK
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): lead_forms.read. This integration was granted: …`
404	Form does not exist or is not the installer's (same response for both)	`Form not found or not accessible to this token`

Create lead form

POST https://api.bluereacher.com/v1/lead-forms

Auth: Bearer access token. Scope: lead_forms.write.

Create a hosted lead form.

Checked with the dashboard's own rules: at least one field, every key a contact column or an existing custom field of the workspace, and an email or phone_number field so the submitter can be reached. The form is live at its public_url at once (is_active defaults to true).

Parameters

Name	In	Type	Required	Description
`workspace_id`	body	number	yes	A workspace of the installer.
`name`	body	string	yes	Internal name (up to 191 characters).
`fields`	body	array<object>	yes	1–30 fields, each { key, type, label, required?, placeholder?, options?, custom_field_id?, consent_text? }. type: text, email, phone, textarea, select, checkbox, url, date, number, sms_consent. key is a contact column (first_name, last_name, email, phone_number, company_name, website, address, city, state, country) or a workspace custom field's key with its custom_field_id; the form needs an email or phone_number field. sms_consent is the opt-in checkbox (key sms_consent, consent_text up to 1000 characters).
`title`	body	string	no	Heading on the hosted page.
`description`	body	string	no	Text under the heading (up to 5000 characters).
`settings`	body	object	no	submit_button_text, thank_you_message, redirect_url (https), tags (added to the contact, up to 20), allowed_domains (where it may be embedded, up to 20), daily_limit, style { primary_color, button_text_color, background_color, page_background, text_color (hex), border_radius 0–32, font_family system\|serif\|mono }.
`is_active`	body	boolean	no	Default true. An inactive form's page answers 404.

Request

curl -X POST "https://api.bluereacher.com/v1/lead-forms" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "workspace_id": 7,
  "name": "Website quote form",
  "title": "Get a quote",
  "fields": [
    {
      "key": "first_name",
      "type": "text",
      "label": "First name",
      "required": true
    },
    {
      "key": "email",
      "type": "email",
      "label": "Email",
      "required": true
    },
    {
      "key": "phone_number",
      "type": "phone",
      "label": "Mobile",
      "required": false
    }
  ],
  "settings": {
    "submit_button_text": "Get a quote",
    "tags": [
      "web-lead"
    ]
  }
}'

Responses

A 201 reply (Created):

{
  "success": true,
  "data": {
    "id": 31,
    "workspace_id": 7,
    "name": "Website quote form",
    "slug": "f3a9c1d2e4b5f607",
    "title": "Get a quote",
    "description": "Tell us about your project.",
    "fields": [
      {
        "key": "first_name",
        "type": "text",
        "label": "First name",
        "required": true
      },
      {
        "key": "email",
        "type": "email",
        "label": "Email",
        "required": true
      },
      {
        "key": "phone_number",
        "type": "phone",
        "label": "Mobile",
        "required": false
      },
      {
        "key": "lead_source",
        "type": "select",
        "label": "How did you hear about us?",
        "options": [
          "Web",
          "Referral",
          "Event"
        ],
        "custom_field_id": 41
      },
      {
        "key": "sms_consent",
        "type": "sms_consent",
        "label": "Text me updates",
        "consent_text": "By ticking this box you agree to receive messages from Acme. Reply STOP to opt out."
      }
    ],
    "settings": {
      "submit_button_text": "Get a quote",
      "thank_you_message": "Thanks — we will be in touch today.",
      "redirect_url": null,
      "tags": [
        "web-lead"
      ],
      "allowed_domains": [
        "acme.example"
      ],
      "daily_limit": 500,
      "style": {
        "primary_color": "#2563eb",
        "button_text_color": "#ffffff",
        "background_color": "#ffffff",
        "page_background": "#f8fafc",
        "text_color": "#0f172a",
        "border_radius": 8,
        "font_family": "system"
      }
    },
    "is_active": true,
    "submission_count": 0,
    "created_at": "2026-10-01T00:00:00.000Z",
    "updated_at": "2026-11-01T00:00:00.000Z",
    "public_url": "https://api.bluereacher.com/f/f3a9c1d2e4b5f607",
    "embed_snippet": "<script src=\"https://api.bluereacher.com/embed/forms.js\" data-form=\"f3a9c1d2e4b5f607\" async></script>"
  }
}

Status	When	Message
201	Created
400	A rule failed (Joi message or field rule)	`Form must include an email or phone number field`
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): lead_forms.write. This integration was granted: …`
404	Workspace does not exist or is not the installer's (same response for both)	`Workspace not found or not accessible to this token`

Update lead form

PATCH https://api.bluereacher.com/v1/lead-forms/{id}

Auth: Bearer access token. Scope: lead_forms.write.

Change a form's name, text, fields, settings or active state.

Send only what changes. fields replaces the whole list and is checked like on create. Past submissions keep their own payloads.

Parameters

Name	In	Type	Required	Description
`id`	path	number	yes	The form id.
`name`	body	string	no	Internal name.
`title`	body	string	no	Heading.
`description`	body	string	no	Text under the heading.
`fields`	body	array<object>	no	1–30 fields, each { key, type, label, required?, placeholder?, options?, custom_field_id?, consent_text? }. type: text, email, phone, textarea, select, checkbox, url, date, number, sms_consent. key is a contact column (first_name, last_name, email, phone_number, company_name, website, address, city, state, country) or a workspace custom field's key with its custom_field_id; the form needs an email or phone_number field. sms_consent is the opt-in checkbox (key sms_consent, consent_text up to 1000 characters).
`settings`	body	object	no	submit_button_text, thank_you_message, redirect_url (https), tags (added to the contact, up to 20), allowed_domains (where it may be embedded, up to 20), daily_limit, style { primary_color, button_text_color, background_color, page_background, text_color (hex), border_radius 0–32, font_family system\|serif\|mono }.
`is_active`	body	boolean	no	false takes the page offline (404) without deleting the form.

Request

curl -X PATCH "https://api.bluereacher.com/v1/lead-forms/31" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "is_active": false
}'

Responses

A 200 reply (OK):

{
  "success": true,
  "data": {
    "id": 31,
    "workspace_id": 7,
    "name": "Website quote form",
    "slug": "f3a9c1d2e4b5f607",
    "title": "Get a quote",
    "description": "Tell us about your project.",
    "fields": [
      {
        "key": "first_name",
        "type": "text",
        "label": "First name",
        "required": true
      },
      {
        "key": "email",
        "type": "email",
        "label": "Email",
        "required": true
      },
      {
        "key": "phone_number",
        "type": "phone",
        "label": "Mobile",
        "required": false
      },
      {
        "key": "lead_source",
        "type": "select",
        "label": "How did you hear about us?",
        "options": [
          "Web",
          "Referral",
          "Event"
        ],
        "custom_field_id": 41
      },
      {
        "key": "sms_consent",
        "type": "sms_consent",
        "label": "Text me updates",
        "consent_text": "By ticking this box you agree to receive messages from Acme. Reply STOP to opt out."
      }
    ],
    "settings": {
      "submit_button_text": "Get a quote",
      "thank_you_message": "Thanks — we will be in touch today.",
      "redirect_url": null,
      "tags": [
        "web-lead"
      ],
      "allowed_domains": [
        "acme.example"
      ],
      "daily_limit": 500,
      "style": {
        "primary_color": "#2563eb",
        "button_text_color": "#ffffff",
        "background_color": "#ffffff",
        "page_background": "#f8fafc",
        "text_color": "#0f172a",
        "border_radius": 8,
        "font_family": "system"
      }
    },
    "is_active": false,
    "submission_count": 128,
    "created_at": "2026-10-01T00:00:00.000Z",
    "updated_at": "2026-11-01T00:00:00.000Z",
    "public_url": "https://api.bluereacher.com/f/f3a9c1d2e4b5f607",
    "embed_snippet": "<script src=\"https://api.bluereacher.com/embed/forms.js\" data-form=\"f3a9c1d2e4b5f607\" async></script>"
  }
}

Status	When	Message
200	OK
400	Nothing to change, or a rule failed	`No editable fields provided.`
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): lead_forms.write. This integration was granted: …`
404	Form does not exist or is not the installer's (same response for both)	`Form not found or not accessible to this token`

Delete lead form

DELETE https://api.bluereacher.com/v1/lead-forms/{id}

Auth: Bearer access token. Scope: lead_forms.write.

Delete a form; its page stops answering at once.

Submissions already received stay with the contacts they created.

Parameters

Name	In	Type	Required	Description
`id`	path	number	yes	The form id.

Request

curl -X DELETE "https://api.bluereacher.com/v1/lead-forms/31" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Responses

A 200 reply (OK):

{
  "success": true,
  "message": "Form deleted",
  "data": {
    "id": 31
  }
}

Status	When	Message
200	OK
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): lead_forms.write. This integration was granted: …`
404	Form does not exist or is not the installer's (same response for both)	`Form not found or not accessible to this token`

List submissions

GET https://api.bluereacher.com/v1/lead-forms/{id}/submissions

Auth: Bearer access token. Scope: lead_forms.read.

What was submitted on a form, newest first.

payload is the submitted values by field key; contact is the contact the submission created (is_new_contact: true) or updated.

Parameters

Name	In	Type	Required	Description
`id`	path	number	yes	The form id.
`page`	query	number	no	Default 1.
`limit`	query	number	no	1–100, default 25.

Request

curl -X GET "https://api.bluereacher.com/v1/lead-forms/31/submissions?page=1&limit=25" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Responses

A 200 reply (OK):

{
  "success": true,
  "data": {
    "form": {
      "id": 31,
      "name": "Website quote form",
      "fields": [
        {
          "key": "first_name",
          "type": "text",
          "label": "First name",
          "required": true
        },
        {
          "key": "email",
          "type": "email",
          "label": "Email",
          "required": true
        },
        {
          "key": "phone_number",
          "type": "phone",
          "label": "Mobile",
          "required": false
        },
        {
          "key": "lead_source",
          "type": "select",
          "label": "How did you hear about us?",
          "options": [
            "Web",
            "Referral",
            "Event"
          ],
          "custom_field_id": 41
        },
        {
          "key": "sms_consent",
          "type": "sms_consent",
          "label": "Text me updates",
          "consent_text": "By ticking this box you agree to receive messages from Acme. Reply STOP to opt out."
        }
      ]
    },
    "submissions": [
      {
        "id": 501,
        "form_id": 31,
        "workspace_id": 7,
        "contact_id": 1234,
        "contact": {
          "id": 1234,
          "first_name": "Ann",
          "last_name": "Lee",
          "email": "ann@example.com",
          "phone_number": "+61412345678"
        },
        "is_new_contact": true,
        "payload": {
          "first_name": "Ann",
          "email": "ann@example.com",
          "phone_number": "+61412345678",
          "lead_source": "Referral",
          "sms_consent": true
        },
        "page_url": "https://acme.example/pricing",
        "referrer": "https://google.com/",
        "created_at": "2026-11-04T01:00:00.000Z"
      }
    ]
  },
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 128,
    "total_pages": 6
  }
}

Status	When	Message
200	OK
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): lead_forms.read. This integration was granted: …`
404	Form does not exist or is not the installer's (same response for both)	`Form not found or not accessible to this token`

Lead forms

On this page