Developer docs: API reference

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: Bearer with your key. Bodies are JSON, sent with Content-Type: application/json.
  • Times are in UTC, in ISO 8601 with a Z at the end, such as 2026-10-19T09:42:17Z. Ids are strings.
  • Lists come back as {"data": [...], "next_cursor": "..."}. Pass next_cursor as cursor to get the next page. It is null on the last page. limit goes 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

Request
curl "https://listenfox.com/api/public/v1/me" \
  -H "Authorization: Bearer $LISTENFOX_API_KEY"
Response 200
{
  "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

Request
curl "https://listenfox.com/api/public/v1/meta" \
  -H "Authorization: Bearer $LISTENFOX_API_KEY"
Response 200
{
  "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

NameTypeWhat it is
sincestring or nullStarted at or after (ISO-8601).
untilstring or nullStarted before (ISO-8601).
updated_sincestring or nullChanged at or after: poll with the last updated_at.
statuspending | processing | analyzed | failed or null-
categorystring or nullSee GET /meta categories.
outcomeopen | won | lost or null-
source_idstring or null-
campaignstring or null-
lead_bandhot | warm | cold | not_lead or null-
phonestring or nullAny part of the caller's number, 3 digits or more.
qstring or nullSearch summaries and transcripts; best match first.
orderedboolean or nullOnly calls followed by an order (true) or not (false).
cursorstring or null-
limitinteger-
Request
curl "https://listenfox.com/api/public/v1/calls" \
  -H "Authorization: Bearer $LISTENFOX_API_KEY"
Response 200
{
  "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)

NameTypeWhat it is
recording_urlrequiredstringA public https link to the audio.
phonestring or nullThe caller's number.
started_atstring or null-
directioninbound | outbound or null-
duration_sinteger or null-
caller_namestring or null-
campaignstring or null-
notesstring or null-
external_idstring or nullYour id for the call: sending it again returns the same call.
analyzebooleanAnalyze it (uses credits; needs the analyze scope).
Request
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
}'
Response 202
{
  "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

NameTypeWhat it is
call_idrequiredstring-
Request
curl "https://listenfox.com/api/public/v1/calls/CALL_ID" \
  -H "Authorization: Bearer $LISTENFOX_API_KEY"
Response 200
{
  "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

NameTypeWhat it is
call_idrequiredstring-
Request
curl -X POST "https://listenfox.com/api/public/v1/calls/CALL_ID/analyze" \
  -H "Authorization: Bearer $LISTENFOX_API_KEY"
Response 202
{
  "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

NameTypeWhat it is
call_idrequiredstring-

Body (JSON)

NameTypeWhat it is
addarray of string-
removearray of string-
Request
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"
  ]
}'
Response 200
{
  "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

NameTypeWhat it is
phonestring or nullAny part of the number, e.g. +15125550143.
emailstring or null-
qstring or nullName or number.
cursorstring or null-
limitinteger-
Request
curl "https://listenfox.com/api/public/v1/contacts" \
  -H "Authorization: Bearer $LISTENFOX_API_KEY"
Response 200
{
  "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

NameTypeWhat it is
contact_idrequiredstring-
Request
curl "https://listenfox.com/api/public/v1/contacts/CONTACT_ID" \
  -H "Authorization: Bearer $LISTENFOX_API_KEY"
Response 200
{
  "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

NameTypeWhat it is
contact_idrequiredstring-

Body (JSON)

NameTypeWhat it is
namestring or null-
emailstring or null-
statusstring or null-
custom_fieldsobject or nullMerged in; null removes a field.
Request
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"
  }
}'
Response 200
{
  "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

NameTypeWhat it is
statusopen | done | all-
due_beforestring or nullDue before this day (workspace calendar).
contact_idstring or null-
cursorstring or null-
limitinteger-
Request
curl "https://listenfox.com/api/public/v1/followups" \
  -H "Authorization: Bearer $LISTENFOX_API_KEY"
Response 200
{
  "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)

NameTypeWhat it is
titlerequiredstring-
call_idstring or null-
contact_idstring or null-
due_atstring or nullA date, or a time (its local day).
assignee_emailstring or nullA workspace member; default the key's owner.
Request
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"
}'
Response 201
{
  "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

NameTypeWhat it is
followup_idrequiredstring-
Request
curl -X POST "https://listenfox.com/api/public/v1/followups/FOLLOWUP_ID/complete" \
  -H "Authorization: Bearer $LISTENFOX_API_KEY"
Response 200
{
  "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)

NameTypeWhat it is
questionrequiredstring-
chat_idstring or nullContinue an earlier answer.
Request
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
}'
Response 200
{
  "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

NameTypeWhat it is
period7d | 30d | 90d-
fromstring or nullFirst day (overrides period).
tostring or nullLast day, included.
group_bynone | source | campaign | agent-
Request
curl "https://listenfox.com/api/public/v1/insights/metrics" \
  -H "Authorization: Bearer $LISTENFOX_API_KEY"
Response 200
{
  "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

NameTypeWhat it is
period7d | 30d | 90d-
Request
curl "https://listenfox.com/api/public/v1/insights/objections" \
  -H "Authorization: Bearer $LISTENFOX_API_KEY"
Response 200
{
  "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

Request
curl "https://listenfox.com/api/public/v1/insights/demand" \
  -H "Authorization: Bearer $LISTENFOX_API_KEY"
Response 200
{
  "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

NameTypeWhat it is
period7d | 30d | 90d-
Request
curl "https://listenfox.com/api/public/v1/insights/agents" \
  -H "Authorization: Bearer $LISTENFOX_API_KEY"
Response 200
{
  "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

Request
curl "https://listenfox.com/api/public/v1/webhooks" \
  -H "Authorization: Bearer $LISTENFOX_API_KEY"
Response 200
{
  "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)

NameTypeWhat it is
urlrequiredstring-
eventsrequiredarray of stringEvent types, or ["*"] for every event.
descriptionstring-
Request
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": ""
}'
Response 201
{
  "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

NameTypeWhat it is
webhook_idrequiredstring-
Request
curl -X DELETE "https://listenfox.com/api/public/v1/webhooks/WEBHOOK_ID" \
  -H "Authorization: Bearer $LISTENFOX_API_KEY"
Response 204
(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

NameTypeWhat it is
typecall.created | call.analyzed | call.failed | lead.hot | followup.created | followup.due | trigger.fired | order.matched | brief.ready or null-
since_idstring or null-
limitinteger-
Request
curl "https://listenfox.com/api/public/v1/events" \
  -H "Authorization: Bearer $LISTENFOX_API_KEY"
Response 200
{
  "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

NameTypeWhat it is
typecall.created | call.analyzed | call.failed | lead.hot | followup.created | followup.due | trigger.fired | order.matched | brief.ready-
Request
curl "https://listenfox.com/api/public/v1/events/sample" \
  -H "Authorization: Bearer $LISTENFOX_API_KEY"
Response 200
{
  "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).