--- title: "Boxly Lead Creation API Integration Guide" description: "A Clear, Simple Explanation for Forms, CRM & External Systems: Followed by the Full Developer Specification" url: https://help.boxly.ai/en/articles/10182789-boxly-lead-creation-api-integration-guide collection: "API Documents to get leads into Boxly" updated: 2026-11-09 language: en --- # Boxly Lead Creation API Integration Guide A Clear, Simple Explanation for Forms, CRM & External Systems: Followed by the Full Developer Specification ## How the Boxly Lead Creation API Works * * * The Lead Creation API allows external systems to create or update leads inside Boxly automatically. This integration is typically used for: - Website contact forms - Landing pages - Chatbots and AI agents - CRM systems - Zapier or middleware tools - Custom backend systems > When someone submits information, your system sends Boxly a single request. Boxly handles the rest. ## What Happens in Simple Terms * * * 1. A person submits a form or sends information through your system. 2. Your system sends Boxly one POST request. 3. Boxly checks if the lead already exists using phone or email. 4. If the lead exists → Boxly updates it. 5. If the lead does not exist → Boxly creates a new one. 6. The message and structured data appear inside the lead’s timeline. 7. Labels, treatment labels, and location are applied if included. There is: - No need to search for leads - No syncing required - No duplicate handling required on your side ✅ Boxly automatically manages matching and creation. ## Important Information Before You Start * * * ### 1\. Boxly Does Not Provide Lead Search ❌ Your system should not attempt to search for a lead before sending data. Just send the lead information. Boxly will automatically match by: - Phone number - Email address ### 2\. One Request Per Submission ✅ Each form submission must be sent in a single POST request. Do not split: - Lead details - Message content - Structured form data - Notes > **Success:** All data must be included together. ### 3\. Lead Object Is Always Required Even when sending: - A follow-up message - An additional reply - A note > **Success:** You must always include the **_lead_** object. ### 4\. Phone Numbers Must Be in E.164 Format ✅ **Correct** format example: +447700900123 ❌ **Incorrect** formats (will cause matching issues): 07700900123 447700900123 (07700) 900123 ### 5\. Labels and Locations Must Already Exist If you send: - **labels** - **treatment\_labels** - **location** > **Success:** They must already be configured inside Boxly with the same format. > **If they do not exist, they will be ignored.** ## How to Set Up the Lead Creation API in Boxly * * * 1. Go to **Channels → API Channel** 2. Click **Create Channel** 3. Choose **Standard** 4. Name the channel 5. Go to **API Keys** 6. Generate a new key 7. Provide the API key to your developer ## Developer Guide * * * > **Success:** This section contains the full technical specification. ## 1\. Endpoint * * * POST [https://api.boxly.ai/api/api\_channel/api/v1/submit\_enquiry/](https://api.boxly.ai/api/api_channel/api/v1/submit_enquiry/) > **Authentication** > > Include this header: > X-API-KEY: your\_api\_key > **Info:** If the key is invalid or missing, the request will return **401**. ## 2\. Payload Structure * * * All requests must follow this structure: > { > "root": { > "lead": { ... }, > "reply": { ... }, > "notes": \[ ... \] > } > } - **lead** → Required - **reply** → Optional - **notes** → Optional > **Info:** The **lead** object must always be included. ## 3\. Lead Object * * * Used to identify or create the lead. At minimum, you must include: - **first\_name** OR **full\_name** - **phone** OR **email** > **Warning:** At least one contact method is required. ### Lead Fields

Field

Type

Required

Description

first_name

string

Required*

Lead’s first name

last_name

string

Optional

Lead’s last name

full_name

string

Conditional

Overrides first/last if provided

phone

string

Conditional

Required if email not provided

email

string

Conditional

Required if phone not provided

gender

string

Optional

Gender

date_of_birth

string

Optional

Format: YYYY-MM-DD

labels

array

Optional

Must already exist in Boxly

treatment_labels

array

Optional

Must already exist in Boxly

location

string

Optional

Must already exist in Boxly

dentally_patient_id

string

Optional

For Dentally-linked accounts

## 4\. Reply Object (Standard Format) * * * The reply object adds a message to the lead’s timeline. This is typically used for: - Form message content - Chatbot messages - CRM submissions ### Required fields

Field

Type

Required

Description

message

string

Yes

The content of the submission

message_type

string

Yes

Must be "standard"

### Optional Fields

Field

Type

Description

sub_data

array

Structured question/answer pairs

submission_link

string

URL to original submission

### Example: Form Submission > { > "root": { > "lead": { > "first\_name": "Alice", > "last\_name": "Smith", > "phone": "+447700900123", > "email": "[alice@example.com](mailto:alice@example.com)", > "labels": \["New Patient"\], > "treatment\_labels": \["Invisalign"\], > "location": "Downtown Clinic" > }, > "reply": { > "message": "I would like more information about Invisalign.", > "message\_type": "standard", > "sub\_data": \[ > { > "question": "Preferred contact time", > "answer": "Afternoon" > }, > { > "question": "Budget range", > "answer": "£2000–£3000" > } > \], > "submission\_link": "[https://example.com/form/123](https://example.com/form/123)" > } > } > } ## 5\. Notes Object (Optional) * * * > Used to add internal notes. ### Notes Fields

Field

Type

Required

description

string

Yes

files

array

No

links

array

No

## 6\. API Responses * * *

Status Code

Meaning

201

Lead created

200

Existing lead updated

400

Invalid payload

401

Invalid API key

403

Channel disabled

500

Server error

## 7\. Common Developer Errors (Must Avoid) * * * - Sending multiple requests for a single submission - Not including the **lead** object - Missing **message\_type** - Incorrect phone number format - Using labels that do not exist - Attempting to search Boxly before sending data - Sending empty message fields ## What Happens After You Send the Data * * * When a request is successfully processed: - Boxly checks for an existing lead - Creates one if needed - Adds the message to the timeline - Applies labels and treatment labels - Assigns the location (if valid) - Logs the event in API logs > **Info:** No additional syncing is required. * * * [ Boxly Phones API Integration Guide A Clear, Simple Explanation for Everyone Followed by the Full Developer Specification ](https://help.boxly.ai/en/articles/10182772-boxly-phones-api-integration-guide.md) - [BI SQL API Developer Guide](gleap://article/10182774) - [BI Query Developer Guide](gleap://article/10182773) **Boxly is here to help you work smarter, not harder -** let’s keep streamlining your lead management together!  > Contact us at [support@boxly.ai](mailto:support@boxly.ai) if you need any assistance!