Leads Website Forms
Connect an existing website form to Leads → Enquiries. A business admin with access to Settings creates a key in Settings → Integrations → API Keys and selects Receive website enquiries. The business owner can also start from Leads → Enquiries → Connect a website form. See the Leads product guide.
Send requests from your website server or a form provider that can store a secret. Keep the bearer key in the provider’s secure settings or your server’s secret store.
Send a test submission
Send POST /api/v1/external/enquiries with Authorization: Bearer YOUR_KEY and Content-Type: application/json. The key selects the business. Set test to true to verify that the key and request work.
{
"form_id": "contact-us",
"submission_id": "submission-123",
"subject": "Website enquiry",
"name": "Example Customer",
"email": "example@example.com",
"message": "I would like a quote.",
"custom_fields": {
"Service type": "Kitchen renovation",
"Site postcode": "0500"
},
"test": true
}The test returns HTTP 200 with {"status":"test_passed"} and leaves your
inbox untouched. Omit test or set it to false for live submissions. The
first live delivery returns HTTP 201 with its enquiry_id. An identical retry
returns HTTP 200 with the same ID. Changed content with the same submission
ID returns HTTP 409.
Use a consistent form_id and a unique submission_id from your form
system. Use letters, digits, underscores or hyphens for these IDs.
form_id, submission_id, and subject are required. The
name, email, phone, and message fields are optional. The source and
contact details appear on the Enquiry, where the team can decide whether to
create an opportunity.
Use the optional custom_fields object for extra answers from your form. Send
up to 20 label and text pairs. Labels can have up to 80 characters and answers
up to 500. Send numbers such as postcodes as strings to preserve leading
zeros. Rebased shows them under Form answers on the enquiry and under
Source enquiry on a linked opportunity. An identical retry can send fields
in any order. A changed answer with the same submission ID returns HTTP 409.
Handle the response
| HTTP status | Meaning |
|---|---|
| 201 | The first live submission returns status: created and the enquiry_id. |
| 200 | A test returns status: test_passed. A repeated live submission returns status: duplicate with the original ID. |
| 401 or 403 | Check the connection key, its permission, and Leads access for the business. |
| 409 | The submission ID was previously used for different content on this form. |
| 422 | Check the required fields and ID format. |
| 429 | The request reached the API key’s limit. Retry using the same form and submission IDs after the rate-limit window. |
Use a live connection key for real submissions. Rebased keeps the original enquiry when your form provider retries it.