Webhooks and API reference

Want your phone system to talk to your own tools? Webhooks and our API make that possible. This page gives you the short version. The full reference lives in our developer docs.

Don't want to code? Let your AI assistant do it. Connect it to us and just ask, like "Show me today's missed calls" or "Add a webhook that sends ended calls to our CRM". See the MCP guide. Prefer to build it yourself? Here's how.

What you can do

• Webhooks: get a message sent to your system the moment something happens, like a call ending or a transcription being ready. Good for filling your CRM, logging calls or alerting your team.
• API: read and change your data from your own code, for example calls, voicemails, contacts, employees and call routing.
• Custom Caller Context: show your own customer info to your team when a call comes in.

Webhook events

You choose which events each webhook gets. Here are the ones people use most:

Event	Sent when
call.answered	A call is answered. employees shows who took it.
call.ended	A call ends.
call.lost	A call ends without being answered and without a spoken voicemail. A voicemail with only silence or noise counts as lost.
call.transcription_done	The transcription of a call is ready.
call.summary_done	The AI summary of a call is ready, with summary filled in. It's sent after the transcription, but deliveries can arrive out of order. Not sent when there's nothing meaningful to summarise.
voicemail.new	A new voicemail arrives.
voicemail.transcription_done	A voicemail has been turned into text.
employee.status.changed	An employee's status changes, for example to ringing or on a call. Includes call_id while ringing or on a call.
contact.created, contact.updated, contact.deleted	A contact is added, changed or removed.

There are more, like call.initiated, call.queued and call.outside_business_hours. You'll find the full list and payloads in the webhooks docs.

How to add a webhook

1. Set up a URL on your side that can receive POST requests.
2. Go to Webhooks in the app and add a new webhook.
3. Give it a name, paste your URL and pick the events you want.
4. Save, then make a quick test call to check that events arrive.

Your URL should answer with a 2xx status. If it can't be reached or answers with a server error, a timeout (408) or a rate limit (429), we try again with a longer wait each time, up to 5 tries in total.

Every delivery is signed, so you can check that it really came from us. See Verify delivery signatures.

You can also create and manage webhooks through the API, or ask your AI assistant to do it through MCP.

Custom Caller Context (Custom Endpoint)

With a Custom Endpoint, your team sees your own customer info when a call comes in. You give us a JSON endpoint, and we call it with the caller's number on every incoming call.

1. Build an endpoint that looks up a phone number in your system and returns JSON. Follow the endpoint contract.
2. Make sure it accepts numbers in international format (E.164), like +4512345678. The + arrives URL-encoded as %2B.
3. In the app, go to Integrations and add Custom Endpoint.
4. Use the built-in test to check that your endpoint answers as expected, then save.

Tip: if nothing shows on incoming calls, the most common cause is an endpoint that doesn't handle the + or %2B.

Prefer a ready-made integration? We also connect to Shopify, Dinero and Attio.

Authentication

How you get access depends on what you're building:

• Your own scripts and integrations: use an API key. Create one under API keys in the app and send it with every request. See Authentication.
• A product other customers connect to (multi-tenant): register it as an application, and your customers connect their accounts with OAuth. Applications are switched on per company, so write to support@phone.inc first, and we'll turn them on for you. Then add yours under Applications in the app. See Applications and the OAuth docs.

Related