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.
Before or during the call, your phone system can look up the caller's number in Boxly. If they're an existing lead, Boxly returns a direct URL to their lead record. What your phone system does with that URL is up to your implementation.
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 can optionally look up a caller before submitting the call.
✅ If a match is found, Boxly returns the lead URL — your phone system can use it however it needs to.
✅ The lookup is optional. If you skip it, Boxly still matches or creates the lead automatically when the call is submitted.
✅ Always submit the call data after the call ends regardless of whether you ran a lookup first.
✅ 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 Channels → API Channel
Click “Create Channel” and choose “Phones”
Give the channel a name
Go to this channel→ 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.
GET https://api.boxly.ai/api/api_channel/api/v1/search_enquiry/
Authentication: X-API-KEY: your_api_key
Query parameter: phone — caller's number in E.164 format
Response
Meaning
What your system can do
| No existing lead | Treat as new — Boxly creates the lead automatically on submission |
| Existing lead found | Use the |
| Invalid or missing API key | Check your API key |
What Boxly provides: a lead_url pointing directly to the lead record in Boxly. What your phone system does with that URL is entirely up to your implementation.
Always submit the call after the call ends regardless of the lookup result.
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
Optional but useful
✅ This is the most important part of the request.
Required fields
Strongly Recommended Fields
These are needed for call quality, routing, and context.
Optional Fields
array |
{
"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.
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 [email protected] if you need any assistance!
