API reference
Every route of the API, with what it needs and what it returns. The examples are made up, but shaped exactly like real answers.
Conventions
- Every path below starts with
https://listenfox.com/api/public/v1. - Send
Authorization: Bearerwith your key. Bodies are JSON, sent withContent-Type: application/json. - Times are in UTC, in ISO 8601 with a
Zat the end, such as2026-10-19T09:42:17Z. Ids are strings. - Lists come back as
{"data": [...], "next_cursor": "..."}. Passnext_cursorascursorto get the next page. It isnullon the last page.limitgoes up to 100, and the default is 25. - A field we have no value for is
null, never left out. New fields may be added at any time, so ignore the ones you don’t know.
Account
Check a key
GET/me
The workspace this key belongs to and what it may do. Any key. Use it to test a connection.
Any key
curl "https://listenfox.com/api/public/v1/me" \
-H "Authorization: Bearer $LISTENFOX_API_KEY"{
"workspace": {
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"name": "Acme Plumbing",
"industry": "general"
},
"key": {
"name": "Zapier",
"scopes": [
"calls:read",
"contacts:read"
],
"kind": "key"
}
}Errors: 401 Missing, revoked or expired key (unauthorized). · 403 The key lacks a scope, or its owner's role can't do this (insufficient_scope). · 429 Over this key's rate limit (rate_limited); wait Retry-After seconds.
List dropdown values
GET/meta
Categories, outcomes, labels, sources, campaigns, your custom fields and webhook events, each as [{key, label}]. Any key.
Any key
curl "https://listenfox.com/api/public/v1/meta" \
-H "Authorization: Bearer $LISTENFOX_API_KEY"{
"categories": [
{
"key": "booked",
"label": "Booked"
}
],
"outcomes": [
{
"key": "booked",
"label": "Booked"
}
],
"labels": [
{
"key": "booked",
"label": "Booked"
}
],
"sources": [
{
"key": "booked",
"label": "Booked"
}
],
"campaigns": [
{
"key": "booked",
"label": "Booked"
}
],
"custom_fields": [
{
"key": "booked",
"label": "Booked"
}
],
"events": [
{
"key": "booked",
"label": "Booked"
}
]
}Errors: 401 Missing, revoked or expired key (unauthorized). · 403 The key lacks a scope, or its owner's role can't do this (insufficient_scope). · 429 Over this key's rate limit (rate_limited); wait Retry-After seconds.
Calls
List calls
GET/calls
Newest first (best match first with q). Requires calls:read.
calls:read
Query
| Name | Type | What it is |
|---|---|---|
since | string or null | Started at or after (ISO-8601). |
until | string or null | Started before (ISO-8601). |
updated_since | string or null | Changed at or after: poll with the last updated_at. |
status | pending | processing | analyzed | failed or null | - |
category | string or null | See GET /meta categories. |
outcome | open | won | lost or null | - |
source_id | string or null | - |
campaign | string or null | - |
lead_band | hot | warm | cold | not_lead or null | - |
phone | string or null | Any part of the caller's number, 3 digits or more. |
q | string or null | Search summaries and transcripts; best match first. |
ordered | boolean or null | Only calls followed by an order (true) or not (false). |
cursor | string or null | - |
limit | integer | - |
curl "https://listenfox.com/api/public/v1/calls" \
-H "Authorization: Bearer $LISTENFOX_API_KEY"{
"data": [
{
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"started_at": "2026-10-19T08:12:03Z",
"duration_s": 312,
"direction": "inbound",
"caller_phone": "+15125550143",
"caller_name": "Maria Lopez",
"contact_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"source": {
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"type": "ringba",
"name": "Ringba main"
},
"campaign": "Google Ads - Water heaters",
"status": "analyzed",
"category": "booked",
"outcome": "open",
"lead_score": 86,
"lead_band": "hot",
"summary": "Wants a 50-gallon water heater installed this week; booked Thursday.",
"labels": [
"vip"
],
"followup_due": "2026-10-21T00:00:00Z",
"ordered": {
"total": 1650,
"currency": "USD",
"at": "2026-10-19T09:41:00Z"
},
"app_url": "https://listenfox.com/w/acme/calls/3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"created_at": "2026-10-19T08:15:40Z",
"updated_at": "2026-10-19T08:16:02Z"
}
],
"next_cursor": "bzoyNQ"
}Errors: 401 Missing, revoked or expired key (unauthorized). · 403 The key lacks a scope, or its owner's role can't do this (insufficient_scope). · 422 A field is missing or not valid (invalid_request, with fields). · 429 Over this key's rate limit (rate_limited); wait Retry-After seconds.
Add a call
POST/calls
Add a call from a recording link. Requires calls:write, plus analyze when analyze is true (the default; uses 1 credit per call, more on Precise). Returns at once; the analysis follows (status pending). Sending the same external_id again returns the first call.
calls:writeanalyzeUses credits
Body (JSON)
| Name | Type | What it is |
|---|---|---|
recording_urlrequired | string | A public https link to the audio. |
phone | string or null | The caller's number. |
started_at | string or null | - |
direction | inbound | outbound or null | - |
duration_s | integer or null | - |
caller_name | string or null | - |
campaign | string or null | - |
notes | string or null | - |
external_id | string or null | Your id for the call: sending it again returns the same call. |
analyze | boolean | Analyze it (uses credits; needs the analyze scope). |
curl -X POST "https://listenfox.com/api/public/v1/calls" \
-H "Authorization: Bearer $LISTENFOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"recording_url": "https://example.com/recordings/0193.mp3",
"phone": "+15125550143",
"started_at": "2026-10-19T08:12:03Z",
"direction": null,
"duration_s": 312,
"caller_name": "Maria Lopez",
"campaign": "Google Ads - Water heaters",
"notes": "Imported from our dialer.",
"external_id": "dialer-0193",
"analyze": true
}'{
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"status": "pending",
"app_url": "https://listenfox.com/w/acme/calls/3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"credits_used": 1
}Errors: 401 Missing, revoked or expired key (unauthorized). · 402 Out of credits (credits_exhausted). · 403 The key lacks a scope, or its owner's role can't do this (insufficient_scope). · 422 A field is missing or not valid (invalid_request, with fields). · 429 Over this key's rate limit (rate_limited); wait Retry-After seconds.
Get a call
GET/calls/{call_id}
One call with its transcript, key moments, answers, objections, follow-ups and orders. Requires calls:read.
calls:read
Path
| Name | Type | What it is |
|---|---|---|
call_idrequired | string | - |
curl "https://listenfox.com/api/public/v1/calls/CALL_ID" \
-H "Authorization: Bearer $LISTENFOX_API_KEY"{
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"started_at": "2026-10-19T08:12:03Z",
"duration_s": 312,
"direction": "inbound",
"caller_phone": "+15125550143",
"caller_name": "Maria Lopez",
"contact_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"source": {
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"type": "ringba",
"name": "Ringba main"
},
"campaign": "Google Ads - Water heaters",
"status": "analyzed",
"category": "booked",
"outcome": "open",
"lead_score": 86,
"lead_band": "hot",
"summary": "Wants a 50-gallon water heater installed this week; booked Thursday.",
"labels": [
"vip"
],
"followup_due": "2026-10-21T00:00:00Z",
"ordered": {
"total": 1650,
"currency": "USD",
"at": "2026-10-19T09:41:00Z"
},
"app_url": "https://listenfox.com/w/acme/calls/3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"created_at": "2026-10-19T08:15:40Z",
"updated_at": "2026-10-19T08:16:02Z",
"transcript": [
{
"speaker": "caller",
"start_s": 3.4,
"end_s": 9.8,
"text": "Hi, my water heater died."
}
],
"transcript_truncated": false,
"key_moments": [
{
"label": "Booked a visit",
"start_s": 10.1,
"quote": "We can do Thursday at 10."
}
],
"answers": {
"service": "Water heater install"
},
"objections": [
"Price higher than a competitor"
],
"questions": [],
"followups": [
{
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"title": "Send Maria the water heater quote",
"due_at": "2026-10-21T00:00:00Z",
"status": "open",
"call_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"contact_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"assignee": {
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"name": "Sam Reed"
},
"app_url": "https://listenfox.com/w/acme/calls/3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"created_at": "2026-10-19T08:16:02Z"
}
],
"orders": [
{
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"number": "#1042",
"total": 1650,
"currency": "USD",
"created_at": "2026-10-19T09:41:00Z",
"status": "paid",
"email": "m***@example.com",
"matched_on": "phone",
"after_call": true
}
]
}Errors: 401 Missing, revoked or expired key (unauthorized). · 403 The key lacks a scope, or its owner's role can't do this (insufficient_scope). · 404 Not found in this key's workspace (not_found). · 422 A field is missing or not valid (invalid_request). · 429 Over this key's rate limit (rate_limited); wait Retry-After seconds.
Analyze a call
POST/calls/{call_id}/analyze
Queue the analysis of a call that has none. Uses 1 credit (more on Precise). Requires analyze.
analyzeUses credits
Path
| Name | Type | What it is |
|---|---|---|
call_idrequired | string | - |
curl -X POST "https://listenfox.com/api/public/v1/calls/CALL_ID/analyze" \
-H "Authorization: Bearer $LISTENFOX_API_KEY"{
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"status": "pending",
"app_url": "https://listenfox.com/w/acme/calls/3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"credits_used": 1
}Errors: 401 Missing, revoked or expired key (unauthorized). · 402 Out of credits (credits_exhausted). · 403 The key lacks a scope, or its owner's role can't do this (insufficient_scope). · 404 Not found in this key's workspace (not_found). · 409 The call can't be analyzed now (conflict), for example it already is. · 422 A field is missing or not valid (invalid_request). · 429 Over this key's rate limit (rate_limited); wait Retry-After seconds.
Label a call
POST/calls/{call_id}/labels
Add and remove labels (case-insensitive, up to 20, each up to 40 characters). Requires calls:write.
calls:write
Path
| Name | Type | What it is |
|---|---|---|
call_idrequired | string | - |
Body (JSON)
| Name | Type | What it is |
|---|---|---|
add | array of string | - |
remove | array of string | - |
curl -X POST "https://listenfox.com/api/public/v1/calls/CALL_ID/labels" \
-H "Authorization: Bearer $LISTENFOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"add": [
"vip"
],
"remove": [
"dispute"
]
}'{
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"started_at": "2026-10-19T08:12:03Z",
"duration_s": 312,
"direction": "inbound",
"caller_phone": "+15125550143",
"caller_name": "Maria Lopez",
"contact_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"source": {
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"type": "ringba",
"name": "Ringba main"
},
"campaign": "Google Ads - Water heaters",
"status": "analyzed",
"category": "booked",
"outcome": "open",
"lead_score": 86,
"lead_band": "hot",
"summary": "Wants a 50-gallon water heater installed this week; booked Thursday.",
"labels": [
"vip"
],
"followup_due": "2026-10-21T00:00:00Z",
"ordered": {
"total": 1650,
"currency": "USD",
"at": "2026-10-19T09:41:00Z"
},
"app_url": "https://listenfox.com/w/acme/calls/3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"created_at": "2026-10-19T08:15:40Z",
"updated_at": "2026-10-19T08:16:02Z"
}Errors: 401 Missing, revoked or expired key (unauthorized). · 403 The key lacks a scope, or its owner's role can't do this (insufficient_scope). · 404 Not found in this key's workspace (not_found). · 422 A field is missing or not valid (invalid_request, with fields). · 429 Over this key's rate limit (rate_limited); wait Retry-After seconds.
Contacts
List contacts
GET/contacts
Most recently called first. Requires contacts:read.
contacts:read
Query
| Name | Type | What it is |
|---|---|---|
phone | string or null | Any part of the number, e.g. +15125550143. |
email | string or null | - |
q | string or null | Name or number. |
cursor | string or null | - |
limit | integer | - |
curl "https://listenfox.com/api/public/v1/contacts" \
-H "Authorization: Bearer $LISTENFOX_API_KEY"{
"data": [
{
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"name": "Maria Lopez",
"phone": "+15125550143",
"email": "maria@example.com",
"status": "new",
"lead_score": 86,
"lead_band": "hot",
"last_call_at": "2026-10-19T08:12:03Z",
"calls_count": 2,
"custom_fields": {
"plan": "gold"
},
"app_url": "https://listenfox.com/w/acme/contacts/3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90"
}
],
"next_cursor": null
}Errors: 401 Missing, revoked or expired key (unauthorized). · 403 The key lacks a scope, or its owner's role can't do this (insufficient_scope). · 422 A field is missing or not valid (invalid_request, with fields). · 429 Over this key's rate limit (rate_limited); wait Retry-After seconds.
Get a contact
GET/contacts/{contact_id}
A contact with a lead card read from their calls and their 5 latest calls. Requires contacts:read.
contacts:read
Path
| Name | Type | What it is |
|---|---|---|
contact_idrequired | string | - |
curl "https://listenfox.com/api/public/v1/contacts/CONTACT_ID" \
-H "Authorization: Bearer $LISTENFOX_API_KEY"{
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"name": "Maria Lopez",
"phone": "+15125550143",
"email": "maria@example.com",
"status": "new",
"lead_score": 86,
"lead_band": "hot",
"last_call_at": "2026-10-19T08:12:03Z",
"calls_count": 2,
"custom_fields": {
"plan": "gold"
},
"app_url": "https://listenfox.com/w/acme/contacts/3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"lead_card": {
"summary": "Wants a 50-gallon water heater installed this week.",
"needs": [
"Water heater install"
],
"objections": [
"Price higher than a competitor"
],
"next_step": "Send the quote by email"
},
"recent_calls": [
{
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"started_at": "2026-10-19T08:12:03Z",
"duration_s": 312,
"direction": "inbound",
"caller_phone": "+15125550143",
"caller_name": "Maria Lopez",
"contact_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"source": {
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"type": "ringba",
"name": "Ringba main"
},
"campaign": "Google Ads - Water heaters",
"status": "analyzed",
"category": "booked",
"outcome": "open",
"lead_score": 86,
"lead_band": "hot",
"summary": "Wants a 50-gallon water heater installed this week; booked Thursday.",
"labels": [
"vip"
],
"followup_due": "2026-10-21T00:00:00Z",
"ordered": {
"total": 1650,
"currency": "USD",
"at": "2026-10-19T09:41:00Z"
},
"app_url": "https://listenfox.com/w/acme/calls/3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"created_at": "2026-10-19T08:15:40Z",
"updated_at": "2026-10-19T08:16:02Z"
}
]
}Errors: 401 Missing, revoked or expired key (unauthorized). · 403 The key lacks a scope, or its owner's role can't do this (insufficient_scope). · 404 Not found in this key's workspace (not_found). · 422 A field is missing or not valid (invalid_request). · 429 Over this key's rate limit (rate_limited); wait Retry-After seconds.
Update a contact
PATCH/contacts/{contact_id}
Change only the fields you send. Requires contacts:write.
contacts:write
Path
| Name | Type | What it is |
|---|---|---|
contact_idrequired | string | - |
Body (JSON)
| Name | Type | What it is |
|---|---|---|
name | string or null | - |
email | string or null | - |
status | string or null | - |
custom_fields | object or null | Merged in; null removes a field. |
curl -X PATCH "https://listenfox.com/api/public/v1/contacts/CONTACT_ID" \
-H "Authorization: Bearer $LISTENFOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Maria Lopez",
"email": "maria@example.com",
"status": "customer",
"custom_fields": {
"plan": "gold"
}
}'{
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"name": "Maria Lopez",
"phone": "+15125550143",
"email": "maria@example.com",
"status": "new",
"lead_score": 86,
"lead_band": "hot",
"last_call_at": "2026-10-19T08:12:03Z",
"calls_count": 2,
"custom_fields": {
"plan": "gold"
},
"app_url": "https://listenfox.com/w/acme/contacts/3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"lead_card": {
"summary": "Wants a 50-gallon water heater installed this week.",
"needs": [
"Water heater install"
],
"objections": [
"Price higher than a competitor"
],
"next_step": "Send the quote by email"
},
"recent_calls": [
{
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"started_at": "2026-10-19T08:12:03Z",
"duration_s": 312,
"direction": "inbound",
"caller_phone": "+15125550143",
"caller_name": "Maria Lopez",
"contact_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"source": {
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"type": "ringba",
"name": "Ringba main"
},
"campaign": "Google Ads - Water heaters",
"status": "analyzed",
"category": "booked",
"outcome": "open",
"lead_score": 86,
"lead_band": "hot",
"summary": "Wants a 50-gallon water heater installed this week; booked Thursday.",
"labels": [
"vip"
],
"followup_due": "2026-10-21T00:00:00Z",
"ordered": {
"total": 1650,
"currency": "USD",
"at": "2026-10-19T09:41:00Z"
},
"app_url": "https://listenfox.com/w/acme/calls/3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"created_at": "2026-10-19T08:15:40Z",
"updated_at": "2026-10-19T08:16:02Z"
}
]
}Errors: 401 Missing, revoked or expired key (unauthorized). · 403 The key lacks a scope, or its owner's role can't do this (insufficient_scope). · 404 Not found in this key's workspace (not_found). · 422 A field is missing or not valid (invalid_request, with fields). · 429 Over this key's rate limit (rate_limited); wait Retry-After seconds.
Follow-ups
List follow-ups
GET/followups
Soonest due first. Requires followups:read.
followups:read
Query
| Name | Type | What it is |
|---|---|---|
status | open | done | all | - |
due_before | string or null | Due before this day (workspace calendar). |
contact_id | string or null | - |
cursor | string or null | - |
limit | integer | - |
curl "https://listenfox.com/api/public/v1/followups" \
-H "Authorization: Bearer $LISTENFOX_API_KEY"{
"data": [
{
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"title": "Send Maria the water heater quote",
"due_at": "2026-10-21T00:00:00Z",
"status": "open",
"call_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"contact_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"assignee": {
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"name": "Sam Reed"
},
"app_url": "https://listenfox.com/w/acme/calls/3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"created_at": "2026-10-19T08:16:02Z"
}
],
"next_cursor": null
}Errors: 401 Missing, revoked or expired key (unauthorized). · 403 The key lacks a scope, or its owner's role can't do this (insufficient_scope). · 422 A field is missing or not valid (invalid_request, with fields). · 429 Over this key's rate limit (rate_limited); wait Retry-After seconds.
Create a follow-up
POST/followups
A follow-up on a call or a contact. Requires followups:write.
followups:write
Body (JSON)
| Name | Type | What it is |
|---|---|---|
titlerequired | string | - |
call_id | string or null | - |
contact_id | string or null | - |
due_at | string or null | A date, or a time (its local day). |
assignee_email | string or null | A workspace member; default the key's owner. |
curl -X POST "https://listenfox.com/api/public/v1/followups" \
-H "Authorization: Bearer $LISTENFOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Call Maria back about the quote",
"call_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"contact_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"due_at": "2026-10-21",
"assignee_email": "sam@acme.com"
}'{
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"title": "Send Maria the water heater quote",
"due_at": "2026-10-21T00:00:00Z",
"status": "open",
"call_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"contact_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"assignee": {
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"name": "Sam Reed"
},
"app_url": "https://listenfox.com/w/acme/calls/3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"created_at": "2026-10-19T08:16:02Z"
}Errors: 401 Missing, revoked or expired key (unauthorized). · 403 The key lacks a scope, or its owner's role can't do this (insufficient_scope). · 404 Not found in this key's workspace (not_found). · 422 A field is missing or not valid (invalid_request, with fields). · 429 Over this key's rate limit (rate_limited); wait Retry-After seconds.
Complete a follow-up
POST/followups/{followup_id}/complete
Mark it done. Completing a done follow-up changes nothing. Requires followups:write.
followups:write
Path
| Name | Type | What it is |
|---|---|---|
followup_idrequired | string | - |
curl -X POST "https://listenfox.com/api/public/v1/followups/FOLLOWUP_ID/complete" \
-H "Authorization: Bearer $LISTENFOX_API_KEY"{
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"title": "Send Maria the water heater quote",
"due_at": "2026-10-21T00:00:00Z",
"status": "open",
"call_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"contact_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"assignee": {
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"name": "Sam Reed"
},
"app_url": "https://listenfox.com/w/acme/calls/3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"created_at": "2026-10-19T08:16:02Z"
}Errors: 401 Missing, revoked or expired key (unauthorized). · 403 The key lacks a scope, or its owner's role can't do this (insufficient_scope). · 404 Not found in this key's workspace (not_found). · 422 A field is missing or not valid (invalid_request). · 429 Over this key's rate limit (rate_limited); wait Retry-After seconds.
Ask
Ask about your calls
POST/ask
An answer from your calls, with the quotes it rests on. Uses 1 Ask credit (2 on Precise), or AI credits once the Ask credits run out. Saved in the key owner's Ask history. Requires ask.
askUses credits
Body (JSON)
| Name | Type | What it is |
|---|---|---|
questionrequired | string | - |
chat_id | string or null | Continue an earlier answer. |
curl -X POST "https://listenfox.com/api/public/v1/ask" \
-H "Authorization: Bearer $LISTENFOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"question": "Why did fewer callers book this week?",
"chat_id": null
}'{
"answer": "Price came up on 4 of 31 calls this week, mostly about water heaters.",
"citations": [
{
"call_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"quote": "The other company quoted me $1,500 though.",
"start_s": 14.2,
"app_url": "https://listenfox.com/w/acme/calls/3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90?t=14.2"
}
],
"chat_id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90",
"credits_used": 1,
"table": {}
}Errors: 401 Missing, revoked or expired key (unauthorized). · 402 Out of credits (credits_exhausted). · 403 The key lacks a scope, or its owner's role can't do this (insufficient_scope). · 422 A field is missing or not valid (invalid_request, with fields). · 429 Over this key's rate limit (rate_limited); wait Retry-After seconds.
Insights
Get call metrics
GET/insights/metrics
Totals for the period and the one before it, optionally per source, campaign or team member (group_by=agent). Requires insights:read.
insights:read
Query
| Name | Type | What it is |
|---|---|---|
period | 7d | 30d | 90d | - |
from | string or null | First day (overrides period). |
to | string or null | Last day, included. |
group_by | none | source | campaign | agent | - |
curl "https://listenfox.com/api/public/v1/insights/metrics" \
-H "Authorization: Bearer $LISTENFOX_API_KEY"{
"period": {
"from": "2026-09-19T00:00:00Z",
"to": "2026-10-19T10:00:00Z"
},
"totals": {
"calls": 42,
"connected": 32,
"analyzed": 30,
"hot_leads": 6,
"ordered": 4,
"conversion_rate": 0.3125
},
"previous": {
"calls": 42,
"connected": 32,
"analyzed": 30,
"hot_leads": 6,
"ordered": 4,
"conversion_rate": 0.3125
},
"groups": [
{
"key": "Google Ads - Water heaters",
"label": "Google Ads - Water heaters",
"totals": {
"calls": 42,
"connected": 32,
"analyzed": 30,
"hot_leads": 6,
"ordered": 4,
"conversion_rate": 0.3125
}
}
]
}Errors: 401 Missing, revoked or expired key (unauthorized). · 403 The key lacks a scope, or its owner's role can't do this (insufficient_scope). · 422 A field is missing or not valid (invalid_request, with fields). · 429 Over this key's rate limit (rate_limited); wait Retry-After seconds.
List objections
GET/insights/objections
What held callers back, grouped, most calls first. Requires insights:read.
insights:read
Query
| Name | Type | What it is |
|---|---|---|
period | 7d | 30d | 90d | - |
curl "https://listenfox.com/api/public/v1/insights/objections" \
-H "Authorization: Bearer $LISTENFOX_API_KEY"{
"period": {
"from": "2026-09-19T00:00:00Z",
"to": "2026-10-19T10:00:00Z"
},
"analyzed_calls": 31,
"calls_with_objections": 11,
"data": [
{
"key": "price",
"label": "Price",
"calls": 7,
"previous_calls": 4,
"won": 2,
"lost": 3,
"lost_rate": 0.6,
"phrases": [
"too expensive",
"cheaper elsewhere"
],
"example_call_ids": [
"3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90"
]
}
]
}Errors: 401 Missing, revoked or expired key (unauthorized). · 403 The key lacks a scope, or its owner's role can't do this (insufficient_scope). · 422 A field is missing or not valid (invalid_request, with fields). · 429 Over this key's rate limit (rate_limited); wait Retry-After seconds.
List unmet demand
GET/insights/demand
What callers asked for that you don't offer (last 90 days). Requires insights:read.
insights:read
curl "https://listenfox.com/api/public/v1/insights/demand" \
-H "Authorization: Bearer $LISTENFOX_API_KEY"{
"window_days": 90,
"generated_at": "2026-10-19T03:00:00Z",
"data": [
{
"key": "tankless",
"label": "Tankless water heaters",
"calls": 5,
"unmet_calls": 4,
"opportunity": "Callers ask for it; you don't list it.",
"first_seen": "2026-10-07",
"phrases": [
"tankless",
"on-demand heater"
],
"example_call_ids": [
"3f6c2a9e-8b1d-4c7a-9e2f-5a1b0c7d8e90"
]
}
]
}Errors: 401 Missing, revoked or expired key (unauthorized). · 403 The key lacks a scope, or its owner's role can't do this (insufficient_scope). · 429 Over this key's rate limit (rate_limited); wait Retry-After seconds.
List team member scorecards
GET/insights/agents
Per-person scorecards. Requires insights:read.
insights:read
Query
| Name | Type | What it is |
|---|---|---|
period | 7d | 30d | 90d | - |
curl "https://listenfox.com/api/public/v1/insights/agents" \
-H "Authorization: Bearer $LISTENFOX_API_KEY"{
"period": {
"from": "2026-09-19T00:00:00Z",
"to": "2026-10-19T10:00:00Z"
},
"data": [
{
"agent": "Sam Reed",
"analyzed": 22,
"avg_duration_seconds": 214,
"calls": 25,
"qa_avg": 78
}
]
}Errors: 401 Missing, revoked or expired key (unauthorized). · 403 The key lacks a scope, or its owner's role can't do this (insufficient_scope). · 422 A field is missing or not valid (invalid_request, with fields). · 429 Over this key's rate limit (rate_limited); wait Retry-After seconds.
Webhooks
List endpoints
GET/webhooks
Every endpoint of this workspace, oldest first, without secrets. Requires webhooks.
webhooks
curl "https://listenfox.com/api/public/v1/webhooks" \
-H "Authorization: Bearer $LISTENFOX_API_KEY"{
"data": [
{
"id": "5f0a3c2e-8b1d-4e6f-9a7c-2d4b6e8f0a1c",
"url": "https://hooks.example.com/listenfox",
"events": [
"call.analyzed",
"lead.hot"
],
"description": "n8n: new calls to the CRM",
"active": true,
"created_at": "2026-10-19T12:00:00Z"
}
],
"next_cursor": null
}Add an endpoint
POST/webhooks
Every matching event is POSTed to url, signed with the returned secret (shown once). n8n, Zapier and Make call this when a workflow is turned on. Requires webhooks.
webhooks
Body (JSON)
| Name | Type | What it is |
|---|---|---|
urlrequired | string | - |
eventsrequired | array of string | Event types, or ["*"] for every event. |
description | string | - |
curl -X POST "https://listenfox.com/api/public/v1/webhooks" \
-H "Authorization: Bearer $LISTENFOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.example.com/listenfox",
"events": [
"call.analyzed",
"lead.hot"
],
"description": ""
}'{
"id": "5f0a3c2e-8b1d-4e6f-9a7c-2d4b6e8f0a1c",
"url": "https://hooks.example.com/listenfox",
"events": [
"call.analyzed",
"lead.hot"
],
"description": "n8n: new calls to the CRM",
"active": true,
"created_at": "2026-10-19T12:00:00Z",
"secret": "whsec_3q2-v8K0bX7t9nQeF1yZc4LmR6sWdHjA"
}Errors: 422 A field is missing or not valid (invalid_request).
Delete an endpoint
DELETE/webhooks/{webhook_id}
Stop sending events to this endpoint and delete it. Requires webhooks.
webhooks
Path
| Name | Type | What it is |
|---|---|---|
webhook_idrequired | string | - |
curl -X DELETE "https://listenfox.com/api/public/v1/webhooks/WEBHOOK_ID" \
-H "Authorization: Bearer $LISTENFOX_API_KEY"(no body)Errors: 422 A field is missing or not valid (invalid_request).
List recent events
GET/events
The last 30 days, newest first. since_id returns only events newer than that one. Requires webhooks.
webhooks
Query
| Name | Type | What it is |
|---|---|---|
type | call.created | call.analyzed | call.failed | lead.hot | followup.created | followup.due | trigger.fired | order.matched | brief.ready or null | - |
since_id | string or null | - |
limit | integer | - |
curl "https://listenfox.com/api/public/v1/events" \
-H "Authorization: Bearer $LISTENFOX_API_KEY"{
"data": [
{
"id": "evt_186f9a1c2b3d4e5fa1b2c3d4e5f6",
"type": "call.analyzed",
"created_at": "2026-10-19T12:00:00Z",
"workspace_id": "7d0c8b1e-2f4a-4c55-9d3e-0b6a1f2e3c4d",
"data": {}
}
],
"next_cursor": null
}Errors: 422 A field is missing or not valid (invalid_request).
Get a sample event
GET/events/sample
The latest real event of this type, or a made-up one with the same shape. Requires webhooks.
webhooks
Query
| Name | Type | What it is |
|---|---|---|
type | call.created | call.analyzed | call.failed | lead.hot | followup.created | followup.due | trigger.fired | order.matched | brief.ready | - |
curl "https://listenfox.com/api/public/v1/events/sample" \
-H "Authorization: Bearer $LISTENFOX_API_KEY"{
"id": "evt_186f9a1c2b3d4e5fa1b2c3d4e5f6",
"type": "call.analyzed",
"created_at": "2026-10-19T12:00:00Z",
"workspace_id": "7d0c8b1e-2f4a-4c55-9d3e-0b6a1f2e3c4d",
"data": {}
}Errors: 422 A field is missing or not valid (invalid_request).