Boxly Phones API Integration Guide

How the Boxly Phones API Works

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.

Here is what happens in simple terms

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.

Important Information Before You Start

1. Boxly does not provide an API for searching leads

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.

2. Only one request per call

All call information must be included in a single POST request.
Do not split a call into separate requests.

3. Send the data after the call ends

The call should be fully completed before sending the request.

4. The summary is extremely important

It helps Boxly understand the purpose of the call and route the lead correctly.

5. Recording links should be sent immediately

Recordings cannot be added later or retrieved by Boxly.

6. The Phones API is part of the Boxly Pro plan

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

How to Set Up the Phones API in Boxly

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.

Developer Guide

This section contains everything your developer or phone provider needs to implement the integration correctly.

All fields are clearly marked as Required, Strongly Recommended or Optional.

1. Endpoint

POST https://api.boxly.ai/api/api_channel/api/v1/submit_enquiry/

Authentication
Include this header:
X-API-KEY: your_api_key

2. Payload Structure

All fields must be included in one payload:

{
"root": {
"lead": { ... },
"reply": { ... },
"notes": [ ... ]
}
}

3. Lead Object

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
email	"test@example.com"	Optional
gender	"Female"	Optional
date_of_birth	"1990-05-10"	Optional

4. Reply Object (Call Metadata)

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.

5. Notes Object (Optional)

Field	Example	Description
description	"Voicemail left"	Required in each note.
files	["https://cdn.com/file.pdf"]	Optional file URLs.
links	[{ "url": "...", "label": "..." }]	Optional links.

6. Full Example Payload

{
  "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"
      }
    ]
  }
}

7. Common Developer Errors (Must Avoid)

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.

8. API Responses

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.

Summary of What Will Happen After You Send the Data

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

You do not have to do any searching or syncing.
Your phone system simply sends the call, and Boxly handles the rest.

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!

Help center

Help center

Boxly Phones API Integration Guide

A Clear, Simple Explanation for Everyone Followed by the Full Developer Specification

How the Boxly Phones API Works

Here is what happens in simple terms

Important Information Before You Start

1. Boxly does not provide an API for searching leads

2. Only one request per call

3. Send the data after the call ends

4. The summary is extremely important

5. Recording links should be sent immediately

6. The Phones API is part of the Boxly Pro plan

How to Set Up the Phones API in Boxly

Developer Guide

1. Endpoint

2. Payload Structure

3. Lead Object

4. Reply Object (Call Metadata)

5. Notes Object (Optional)

6. Full Example Payload

7. Common Developer Errors (Must Avoid)

8. API Responses

Summary of What Will Happen After You Send the Data