---
title: "Boxly Phones API Integration Guide"
description: "A Clear, Simple Explanation for Everyone Followed by the Full Developer Specification"
url: https://help.boxly.ai/en/articles/10182772-boxly-phones-api-integration-guide
collection: "API Documents to get leads into Boxly"
updated: 2026-11-16
language: en
---

# Boxly Phones API Integration Guide

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

## 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

1.  A call happens at your practice.
    
2.  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.
    
3.  When the call ends, your phone system sends Boxly a message containing the details of that call.
    
4.  Boxly reads the phone number of the person who called.
    
5.  If the person already exists as a lead in Boxly:  
    Boxly adds that call to the same lead’s conversation thread.
    
6.  If the person is new:  
    Boxly creates a brand-new lead automatically.
    
7.  Boxly shows:
    
    -   Inbound calls on the left
        
    -   Outbound calls on the right
        
8.  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”).
    
9.  With this context, Boxly can automatically route the lead to the correct treatment box.
    
10.  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.**

### **Call patients back in one click**

Ask your phone provider or IT person to turn on one-click calling with Boxly. Once it’s set up, you’ll see a **Call** button in the patient’s conversation instead of **Log Call**.

Click **Call** and your own phone system opens, ready for you to call the patient back.

## Important Information Before You Start

* * *

### 1\. A lead lookup endpoint is available (optional)

✅ 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.

### 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

](https://help.boxly.ai/en/articles/10182757-all-in-one-marketing-suite-guide.md)

## How to Set Up the Phones API in Boxly

* * *

1.  Go to **Channels** → **API Channel**
    
2.  Click **“Create Channel”** and choose **“Phones”**
    
3.  Give the channel a name
    
4.  Go to this channel→ API Keys and create a new key
    
5.  Copy the API key and give it to your phone provider or developer
    
6.  Add all your phone numbers under **Settings → Phone Numbers**
    
7.  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

* * *

> **Info:** 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\. Lead Lookup (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

<table data-id="6e7be32c-0db3-444a-a717-f556f62df794" style="min-width: 75px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><td colspan="1" rowspan="1"><p data-id="1bf8fb76-42fa-479e-a4b4-f578d4a5ead7"><code>200</code> + <code>{"lead_found": "No"}</code></p></td><td colspan="1" rowspan="1"><p data-id="8869fd91-f1a2-4bbd-86ac-650a416b7f58">No existing lead</p></td><td colspan="1" rowspan="1"><p data-id="c5910623-4a89-45ce-ab1e-4118761d1b56">Treat as new — Boxly creates the lead automatically on submission</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="f0fe6076-f4e9-4c01-9014-1dbb0127f9c0"><code>200</code> + lead details including <code>lead_url</code></p></td><td colspan="1" rowspan="1"><p data-id="49e04164-5da0-4e1c-9e1d-15aeb14505ef">Existing lead found</p></td><td colspan="1" rowspan="1"><p data-id="d8e7b181-f147-48f1-b96b-13bb6edffea6">Use the <code>lead_url</code> however your phone system needs to — for example as a screen pop when the agent answers</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="7f5c7db4-c7fc-4678-b799-e14ca8348a67"><code>401</code></p></td><td colspan="1" rowspan="1"><p data-id="c8643608-8ee3-4ac7-b791-bf87552102d2">Invalid or missing API key</p></td><td colspan="1" rowspan="1"><p data-id="a47450e5-d3a2-4882-a961-389364c0a50d">Check your API key</p></td></tr></tbody></table>

**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.**

### 2\. 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

### 3\. Payload Structure

All fields must be included in one payload:

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

### 4\. Lead Object

Used by Boxly to identify the lead.

**Required**

<table data-id="1a8c83a8-964b-4853-960c-d7cb9a612716" style="min-width: 201px;"><colgroup><col style="width: 39.34%;"><col style="width: 21.33%;"><col style="width: 39.34%;"></colgroup><tbody><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="deb045b4-ad56-4672-b6e8-a9ab9179db58" style="text-align: center;"><span style="color: #000000;"><strong>Field</strong></span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="8a6789c3-d215-4014-aebc-3534ad2a8343" style="text-align: center;"><span style="color: #000000;"><strong>Example</strong></span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="5aea123a-9d6b-43a2-8e5a-2d9ab9aaabe4" style="text-align: center;"><span style="color: #000000;"><strong>Description</strong></span></p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="8638f42d-51fc-4103-ad7e-fc56b717a230"><span style="color: #000000;">phone</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="69ed1f17-4cbc-4b2c-a9f6-6b92d1823479"><span style="color: #000000;">"+447700900123"</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="bfd35552-5128-4421-b907-6fe71f10bc10"><span style="color: #000000;">Must be E.164 format. This is how Boxly finds or creates the lead.</span></p></td></tr></tbody></table>

**Optional but useful**

<table data-id="9d1f04b3-27de-40f6-9bd7-74d17f9c672d" style="min-width: 75px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="7cee75d4-9eca-44c0-b6e5-f4dada1c5efc" style="text-align: center;"><span style="color: #000000;"><strong>Field</strong></span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="476f2c11-1e43-4ce6-afdf-9aaca6f569e9" style="text-align: center;"><span style="color: #000000;"><strong>Example</strong></span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="5c5da613-3ff2-44bf-800d-1359c005fe19" style="text-align: center;"><span style="color: #000000;"><strong>Description</strong></span></p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="81aa3d18-7916-4945-bb24-fa2a8a94a3da"><span style="color: #000000;">first_name</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="544f7e72-c913-4f45-9e48-e273a6b51d30"><span style="color: #000000;">"Sarah"</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="bfd239f0-e4ce-4942-8716-894336eb93da"><span style="color: #000000;">Used if a new lead is created</span></p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="8d1ecc72-1f33-4f66-bcc1-65def3fed854"><span style="color: #000000;">last_name</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="ee544135-b4c5-46c6-9f85-032c96f61b57"><span style="color: #000000;">"Doyle"</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="f99488e6-d662-4c5e-8d22-6bd1ddd578eb"><span style="color: #000000;">Optional</span></p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="e68d8260-dd0b-4038-ac70-3d54fcda9be0"><span style="color: #000000;">email</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="bb384a3d-16e2-42d7-bc6c-bff7b1961741"><span style="color: #000000;">"test@example.com"</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="e901c843-ad46-48e8-bb67-e4bd67135cbd"><span style="color: #000000;">Optional</span></p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="9c29ffdb-808a-4c9d-ad55-8e415fce671a"><span style="color: #000000;">gender</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="33a2b20d-0071-4d04-9bf1-3a45e80a9324"><span style="color: #000000;">"Female"</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="e488bba1-15fd-464b-ad17-d56cab0c8a5e"><span style="color: #000000;">Optional</span></p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="4433cc99-94fe-4758-8d13-e5a4ab599be1"><span style="color: #000000;">date_of_birth</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="0a56b687-b0d6-462f-b16c-f8c6b0b5196a"><span style="color: #000000;">"1990-05-10"</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="182829c6-ab00-4d1b-a47c-5ab68fcefbbe"><span style="color: #000000;">Optional</span></p></td></tr></tbody></table>

### 5\. Reply Object (Call Metadata)

✅ This is the most important part of the request.

**Required fields**

<table data-id="7ee90955-c286-43f6-bc4c-05ee41280be0" style="min-width: 75px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="1b2d6daa-8611-4ae4-9334-038b1523dd05" style="text-align: center;"><span style="color: #000000;"><strong>Field</strong></span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="7357b99c-1433-4b3f-af63-3171bd0914cd" style="text-align: center;"><span style="color: #000000;"><strong>Example</strong></span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="972de7df-1b14-4ad0-bc96-870c002d00c5" style="text-align: center;"><span style="color: #000000;"><strong>Description</strong></span></p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="838257cd-4224-4f8a-8891-ef7da602234a"><span style="color: #000000;">message</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="35678215-5420-4188-a387-1b94c36ec65c"><span style="color: #000000;">"Call ended"</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="5f5d12c9-345a-4355-a685-0ff67617aae3"><span style="color: #000000;">Short description of the call. Placeholder allowed.</span></p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="eb63f219-c621-4aba-acf6-86c7c4466858"><span style="color: #000000;">message_type</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="6f191e92-7b28-4c8f-9d82-e7bb35c05e83"><span style="color: #000000;">"phone"</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="1cde441d-160d-4d50-9549-71dd6bc42521"><span style="color: #000000;">Must always be “phone”.</span></p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="c402d708-4864-4e57-8660-ba4546b697f5"><span style="color: #000000;">from_number</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="aaf44a51-98b6-42e5-a529-6b34164fa94c"><span style="color: #000000;">"+447700900123"</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="0bbb253c-1ebf-475a-8b7c-2a1012e80f01"><span style="color: #000000;">Caller number.</span></p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="7950b326-79ba-40b7-871f-254dc39c3248"><span style="color: #000000;">to_number</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="9203e109-5aa2-44ed-bf2e-13e6fa9231ed"><span style="color: #000000;">"+441234567890"</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="7f9a9acc-6e5d-4eef-99e3-dd7152e113bc"><span style="color: #000000;">Receiver number.</span></p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="bc937b2f-1fa2-44d6-9287-355c3b37c362"><span style="color: #000000;">date_time</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="8e33f721-81ea-4570-be29-a95331eee522"><span style="color: #000000;">"2025-10-15T09:45:00Z"</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="e03dc74e-ddd8-4869-b721-2fa28bb09ad5"><span style="color: #000000;">ISO timestamp.</span></p></td></tr></tbody></table>

**Strongly Recommended Fields**

These are needed for call quality, routing, and context.

<table data-id="f45b4637-7383-4a78-b574-cb31e2423bb4" style="min-width: 224px;"><colgroup><col style="width: 37.71%;"><col style="width: 24.58%;"><col style="width: 37.71%;"></colgroup><tbody><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="60a7ceda-b34a-49fd-88dc-1e59ba99a7d9" style="text-align: center;"><span style="color: #000000;"><strong>Field</strong></span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="c04ada9b-8fb2-400b-9b51-4f48c7a14f76" style="text-align: center;"><span style="color: #000000;"><strong>Example</strong></span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="cf0802ca-2f64-43ad-9278-520c400ad45b" style="text-align: center;"><span style="color: #000000;"><strong>Description</strong></span></p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="6d4657bd-f6c8-46a6-b918-d136b46b79aa"><span style="color: #000000;">duration</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="1b31285c-d6f4-4bf0-9671-174a6ad32f03"><span style="color: #000000;">{ "seconds": 120 }</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="b25dbe02-0fa4-4fdb-a745-c24341a93559"><span style="color: #000000;">Length of call.</span></p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="21cd740c-1463-4f3c-b84d-243fc2bcf25b"><span style="color: #000000;">direction</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="45f64ef2-f74f-4a24-8c23-c0cdb8eeb6f5"><span style="color: #000000;">"inbound"</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="778a4da4-c5b0-4505-b058-ab84edbf1738"><span style="color: #000000;">inbound or outbound. Controls left or right placement in the timeline.</span></p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="1bbe78b1-b4d2-4be8-ba6b-c4c2e24f817f"><span style="color: #000000;">call_outcome</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="96555af9-b7ec-4b25-aa64-0b65943b04c4"><span style="color: #000000;">"answered"</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="e97c58ff-95e0-4b82-ae07-c227dda04a66"><span style="color: #000000;">answered, missed, busy, voicemail.</span></p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="4cdcb679-79a8-45ed-8cc7-eba4132f390b"><span style="color: #000000;">summary</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="06338c57-dcdb-4993-aa7e-1dc09750dd5e"><span style="color: #000000;">"Enquired about Invisalign"</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="dbff6418-adab-4214-a87e-a9ecded36487"><span style="color: #000000;">Helps Boxly route the lead correctly.</span></p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="3144113c-92f2-4c87-8c8a-1d58975f6e60"><span style="color: #000000;">recording_link</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="3a890b32-140a-4ce4-a3cf-475e48293dd3"><span style="color: #000000;">"https://audio.com/call123.mp3"</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="278ee126-a969-4886-8d9c-c06b5c36fa59"><span style="color: #000000;">Direct audio file URL.</span></p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="1f5b1793-146e-47ec-8f0a-927f40f3653b"><span style="color: #000000;">recording_link_redirect</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="d62ae413-8160-46c1-b800-dff0e76d16b0"><span style="color: #000000;">"https://view.com/call123"</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="53edb2f9-c4ac-48b3-91f6-3b56a4f1426d"><span style="color: #000000;">Browser view link.</span></p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="b7f4f37c-eef1-46f0-a1aa-2e50d9b2ddba"><span style="color: #000000;">deep_link</span></p></td><td colspan="1" rowspan="1"><p data-id="e94dcdb5-d6e9-4fe4-93fe-3c11cd14bea0"><a target="_blank" rel="noopener noreferrer nofollow" class="linktype-link link" data-linktype="link" href="https://example.com/call/1234567890"><span style="color: #000000;">https://example.com/call/1234567890</span></a></p></td><td colspan="1" rowspan="1"><p data-id="360a8ca2-b6f9-484b-af03-85a5833facfd"><span style="color: #000000;">Opens your configured calling app to initiate a call. Supports HTTP/HTTPS and tel: </span><span style="color: rgb(0, 0, 0);">URLs.</span></p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="5ba1efa3-4a85-4d76-a024-37da2d949a98"><span style="color: #000000;">extension</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="b905915c-1054-4461-9561-30b0e4f45fcc"><span style="color: #000000;">"101"</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="e9789da5-42b9-4768-9dd1-6d3c04dcce07"><span style="color: #000000;">Phone extension used.</span></p></td></tr></tbody></table>

**Optional Fields**

<table data-id="1dd64503-5956-442e-8b6b-6264f6382993" style="min-width: 224px;"><colgroup><col style="width: 37.71%;"><col style="width: 24.58%;"><col style="width: 37.71%;"></colgroup><tbody><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="db56af10-1754-4252-bc47-302ebd07abf8" style="text-align: center;"><strong>Field</strong></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="6e2b4b98-59bd-4cdb-a58c-358d1fea1196" style="text-align: center;"><strong>Example/Type</strong></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="5fd11b7c-35d0-482a-b41f-39f1d2283583" style="text-align: center;"><strong>Description</strong></p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="7bdb03b8-58ce-483e-98ad-d5046151b2e5">call_action</p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="b195e4b0-386e-4b90-88b1-6bfff60ec0e3">"voicemail"</p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="84e594fd-3d0f-417d-a365-3760cb4130aa">Call category.</p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="58316b69-010a-497a-b8dc-2fcf67c235f9">call_outcome_reason</p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="210d76c5-df9b-4bac-bbc3-5005a2e0e604">"busy"</p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="cf24732d-746b-4525-8f71-84d5fb25e6ba">Reason for outcome.</p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="dfe542e2-4f30-48df-a429-e6d774d2fd39">status</p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="5886d52f-cb6f-4e28-8094-94c890f7ced4">"completed"</p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="94086d7f-c475-465b-b2f3-35ccd54cc8ed">Status of the call.</p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="9a4523d9-6892-47c4-a022-e1ccb404018f">sub_data</p></td><td colspan="1" rowspan="1"><p data-id="5e02853e-0239-4789-a937-a5bfecc86510">array</p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="f690fefd-a3c2-4a11-891b-d2fd144ad337">Structured question/answer pairs</p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="fa785c7b-81a7-446f-9b87-10b112863228">submission_link</p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="374cfca8-be52-482a-a84d-275e31b6c841">string</p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="a2e94d8e-223d-44c6-938a-24295b49336f">URL to original submission - including UTMs</p></td></tr></tbody></table>

### 6\. Notes Object (Optional)

<table data-id="dd49b9bd-1111-4cbc-8859-30758dd616cd" style="min-width: 75px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="c1fae894-22ae-4dae-8c71-74c49e596830" style="text-align: center;"><span style="color: #000000;"><strong>Field</strong></span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="f9c90d17-11d2-4a94-be16-b1b40120cd05" style="text-align: center;"><span style="color: #000000;"><strong>Example</strong></span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="3f042e9f-1884-4e85-b590-74769d676b7b" style="text-align: center;"><span style="color: #000000;"><strong>Description</strong></span></p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="9289d668-e5d5-4349-bb89-65313ca225bf"><span style="color: #000000;">description</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="1d3824d5-9012-43c7-b969-caa666e01822"><span style="color: #000000;">"Voicemail left"</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="323ecb72-0050-47fb-95ef-4d2909c766c8"><span style="color: #000000;">Required in each note.</span></p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="622b076f-e0ad-4d4f-8917-99e53809bc88"><span style="color: #000000;">files</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="a72a846e-5211-45fa-b223-18368501aa18"><span style="color: #000000;">["https://cdn.com/file.pdf"]</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="9a866aa4-158c-4d92-ae00-0a39096323a0"><span style="color: #000000;">Optional file URLs.</span></p></td></tr><tr><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="71508a5c-c316-475d-a1d0-9c05d25f1e87"><span style="color: #000000;">links</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="620f253d-74a0-495c-9b03-001290d58c83"><span style="color: #000000;">[{ "url": "...", "label": "..." }]</span></p></td><td colspan="1" rowspan="1" style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word;"><p data-id="f9f8064e-3cac-437d-9c9f-addd461a2815"><span style="color: #000000;">Optional links.</span></p></td></tr></tbody></table>

### 7\. 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](https://recordings.example.com/rec123.mp3)",  
>       "recording\_link\_redirect": "[https://view.example.com/rec123](https://view.example.com/rec123)",  
>       "status": "completed",  
>       "extension": "101"  
>     },  
>     "notes": \[  
>       {  
>         "description": "Invisalign related enquiry"  
>       }  
>     \]  
>   }  
> }

### 8\. Common Developer Errors (Must Avoid)

1.  **Sending multiple POST requests for the same call**
    

Only one request per call is allowed.

2.  **Missing required fields**
    

Boxly cannot process calls without message, message\_type, from\_number, to\_number, or date\_time.

3.  **Not including a summary**
    

Without a summary, Boxly cannot classify or route the call.

4.  **Incorrect phone number formatting**
    

Phone numbers must be in E.164 format.

5.  **Not sending recording links immediately**
    

Recordings cannot be added later.

### 9\. 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
    

> **Info:** 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](mailto:support@boxly.ai) if you need any assistance!
