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.
A person submits a form or sends information through your system.
Your system sends Boxly one POST request.
Boxly checks if the lead already exists using phone or email.
If the lead exists → Boxly updates it.
If the lead does not exist → Boxly creates a new one.
The message and structured data appear inside the lead’s timeline.
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.
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
Each form submission must be sent in a single POST request.
Do not split:
Lead details
Message content
Structured form data
Notes
Even when sending:
A follow-up message
An additional reply
A note
Correct format example:
+447700900123
Incorrect formats (will cause matching issues):
07700900123
447700900123
(07700) 900123
If you send:
labels
treatment_labels
location
Go to Channels → API Channel
Click Create Channel
Choose Standard
Name the channel
Go to API Keys
Generate a new key
Provide the API key to your developer
POST https://api.boxly.ai/api/api_channel/api/v1/submit_enquiry/
Authentication
Include this header:
X-API-KEY: your_api_key
All requests must follow this structure:
{
"root": {
"lead": { ... },
"reply": { ... },
"notes": [ ... ]
}
}
lead → Required
reply → Optional
notes → Optional
Used to identify or create the lead.
At minimum, you must include:
first_name OR full_name
phone OR email
The reply object adds a message to the lead’s timeline.
This is typically used for:
Form message content
Chatbot messages
CRM submissions
{
"root": {
"lead": {
"first_name": "Alice",
"last_name": "Smith",
"phone": "+447700900123",
"email": "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"
}
}
}
Used to add internal notes.
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
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
Boxly Phones API Integration Guide
A Clear, Simple Explanation for Everyone Followed by the Full Developer Specification
Boxly is here to help you work smarter, not harder - let’s keep streamlining your lead management together!
Contact us at support@boxly.ai if you need any assistance!
