Skip to Content
DevelopersAPI ReferenceLeads Website Forms

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 statusMeaning
201The first live submission returns status: created and the enquiry_id.
200A test returns status: test_passed. A repeated live submission returns status: duplicate with the original ID.
401 or 403Check the connection key, its permission, and Leads access for the business.
409The submission ID was previously used for different content on this form.
422Check the required fields and ID format.
429The 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.

Last updated on