The Phones API allows Boxly to receive information about your phone calls automatically. When someone calls your practice, your phone system already knows everything about the call. All this guide does is tell your phone system how to send that information to Boxly so it appears inside the correct lead’s timeline.
A call happens at your practice.
When the call ends, your phone system sends Boxly a message containing the details of that call.
Boxly reads the phone number of the person who called.
If the person already exists as a lead in Boxly:
Boxly adds that call to the same lead’s conversation thread.
If the person is new:
Boxly creates a brand-new lead automatically.
Boxly shows:
Inbound calls on the left
Outbound calls on the right
If your phone system includes a summary or transcript, Boxly can understand what the call was about (for example, “Invisalign enquiry”, “Implant follow-up”, “Voicemail”, “Cancelled appointment”).
With this context, Boxly can automatically route the lead to the correct treatment box.
If your phone system includes a recording link, Boxly will make the recording playable inside the lead’s history.
You do not need to do anything else.
There is no syncing.
There is no searching for leads.
There is no complex setup.
Your phone provider simply sends Boxly one message per call, and Boxly handles everything after that.
Your phone system cannot and should not try to search Boxly.
Only send us the call details.
Boxly takes care of matching and creating leads.
All call information must be included in a single POST request.
Do not split a call into separate requests.
The call should be fully completed before sending the request.
It helps Boxly understand the purpose of the call and route the lead correctly.
Recordings cannot be added later or retrieved by Boxly.
If you are not on the Pro plan, this integration will not work.
All-in-One Marketing Suite Guide
All-in-One Marketing Suite Inside Boxly Guide
Go to Settings → API Channel
Click “Create Channel” and choose “Phones”
Give the channel a name
Go to Settings → API Keys and create a new key
Copy the API key and give it to your phone provider or developer
Add all your phone numbers under Settings → Phone Numbers
Your IT person or phone provider uses the API key and this guide to send your call data to Boxly
Everything else is handled automatically by Boxly.
All fields are clearly marked as Required, Strongly Recommended or Optional.
POST https://api.boxly.ai/api/api_channel/api/v1/submit_enquiry/
Authentication
Include this header:
X-API-KEY: your_api_key
All fields must be included in one payload:
{
"root": {
"lead": { ... },
"reply": { ... },
"notes": [ ... ]
}
}
Used by Boxly to identify the lead.
Required
Field | Example | Description |
phone | "+447700900123" | Must be E.164 format. This is how Boxly finds or creates the lead. |
Optional but useful
Field | Example | Description |
first_name | "Sarah" | Used if a new lead is created |
last_name | "Doyle" | Optional |
"test@example.com" | Optional | |
gender | "Female" | Optional |
date_of_birth | "1990-05-10" | Optional |
This is the most important part of the request.
Required fields
Field | Example | Description |
message | "Call ended" | Short description of the call. Placeholder allowed. |
message_type | "phone" | Must always be “phone”. |
from_number | "+447700900123" | Caller number. |
to_number | "+441234567890" | Receiver number. |
date_time | "2025-10-15T09:45:00Z" | ISO timestamp. |
Strongly Recommended Fields
These are needed for call quality, routing, and context.
Field | Example | Description |
duration | { "seconds": 120 } | Length of call. |
direction | "inbound" | inbound or outbound. Controls left or right placement in the timeline. |
call_outcome | "answered" | answered, missed, busy, voicemail. |
summary | "Enquired about Invisalign" | Helps Boxly route the lead correctly. |
recording_link | "https://audio.com/call123.mp3" | Direct audio file URL. |
recording_link_redirect | "https://view.com/call123" | Browser view link. |
extension | "101" | Phone extension used. |
Optional Fields
Field | Example | Description |
call_action | "voicemail" | Call category. |
call_outcome_reason | "busy" | Reason for outcome. |
status | "completed" | Status of the call. |
Field | Example | Description |
description | "Voicemail left" | Required in each note. |
files | ["https://cdn.com/file.pdf"] | Optional file URLs. |
links | [{ "url": "...", "label": "..." }] | Optional links. |
{
"root": {
"lead": {
"phone": "+447700900123",
"first_name": "Sarah",
"last_name": "Doyle"
},
"reply": {
"message": "Inbound call",
"message_type": "phone",
"from_number": "+447700900123",
"to_number": "+441234567890",
"date_time": "2025-10-15T09:45:00Z",
"duration": { "seconds": 120 },
"direction": "inbound",
"call_outcome": "answered",
"summary": "Lead asked about Invisalign consultation",
"recording_link": "https://recordings.example.com/rec123.mp3",
"recording_link_redirect": "https://view.example.com/rec123",
"status": "completed",
"extension": "101"
},
"notes": [
{
"description": "Invisalign related enquiry"
}
]
}
}
Sending multiple POST requests for the same call
Only one request per call is allowed.
Missing required fields
Boxly cannot process calls without message, message_type, from_number, to_number, or date_time.
Not including a summary
Without a summary, Boxly cannot classify or route the call.
Incorrect phone number formatting
Phone numbers must be in E.164 format.
Not sending recording links immediately
Recordings cannot be added later.
Trying to search Boxly
This is not supported.
Just send the call, and Boxly will handle everything automatically.
201 – Lead created
A new lead was created and the call was attached.
200 – Lead found
Existing lead updated with the call.
400 – Invalid payload
Usually due to missing fields or badly formatted data.
401 – Invalid API key
Authentication header missing or incorrect.
403 – Channel disabled
Phones API channel not active.
500 – Server error
Unexpected error. Contact Boxly support.
When each call finishes:
Your phone system sends Boxly the call information
Boxly checks if the caller is already a lead
If yes, Boxly adds the call to the existing lead
If not, Boxly creates a new lead
Inbound calls appear on the left
Outbound calls appear on the right
Summaries help Boxly understand the call and route the lead
Recording links appear inside the lead’s timeline
Everything is tracked in the API log
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!