API Reference v1
REST + Webhooks integration reference (version 2026-06-15)
CRM Integration Quickstart
The fastest path to connect a CRM to Heilo. The full API reference is below.
Integrate webhook-first: the call.completed event is the primary data source (it carries the recording link and the processed transcript). REST /calls is a supplement — introspection and reading selected metadata.
- Expose a webhook endpoint in your CRM or middleware (no code: use Zapier/Make — see the guide below).
- Add an endpoint in Heilo (Settings → Integrations) for call.completed (optionally also call.outbound.attempted).
- Receive call.completed and verify the signature (Heilo-Signature header — see below).
- Deduplicate by event_id (heilo-event-id header); data.call_id groups events of the same call.
- Map the fields to your CRM: find/create a contact by phone, create a lead/deal, and attach an activity/note (summary + recording link).
No code? The no-code connection guide (Zapier/Make) walks through it step by step.
Authentication
Public API uses Bearer tokens. Generate an API key from the "API keys" card on the Integrations page and send it in the header:
Authorization: Bearer hk_live_AbC1MnPq...
Heilo has three auth modes:
- Bearer (API keys hk_live_…) — for Public API. No CSRF, no cookies.
- Session cookies — for the web app (heilo.io). Do NOT use for Public API.
- Signature — for webhooks Heilo sends to YOUR endpoint (you verify signature header).
| Scope | Meaning |
|---|---|
| read.calls | Read calls: GET /api/v1/calls, GET /api/v1/calls/:id |
| read.recordings | Mints a link to a call’s audio through `GET /calls/:id/recording-url`. Separate from `read.calls` because audio is a different consent from metadata — an existing key does not gain it, you create a new key with explicit recording access. |
| read.transcripts | Adds the transcript text to `GET /calls/:id`: `transcript_original`, `transcript_edited` and `transcript_edited_at`. Separate from `read.calls` because the words of a conversation are a different consent from metadata — an existing key does not gain it, you create a new key with explicit transcript access. Without it those fields are absent and the call still answers 200. It also requires `read.calls`: a key with `read.transcripts` alone gets 403, and creating one is refused with 400. |
| write.calls, read.contacts, write.contacts, manage.webhooks, manage.api_keys | Reserved for planned API endpoints. A new key cannot be created with them (400 BAD_REQUEST). An older key may still hold one, and it grants nothing. |
The environment field in the /me response is always live today. Test keys are planned.
Base URL and version
All public endpoints live under /api/v1/. Production:
https://www.heilo.io/api/v1
Current version
v1 · 2026-06-15
The date is the API version identifier (date-stamped), not today's date.
Status
Beta
Heilo API uses a date-stamped version. Only breaking changes bump the major version (v1 → v2). Adding fields or endpoints is non-breaking, and so is adding fields to webhook payloads.
Backwards-compatible: new response fields, new webhook payload fields, new event_types, new endpoints. Breaking change = new major (v2). Old version supported min. 12 months after v2 announcement.
Rate limits
Hourly limits per-key and per-user (sum of all keys). Reset on the UTC hour. Every request counts, regardless of response status.
Per key
1000 req/h
Per account (sum of keys)
5000 req/h
Every successful response carries X-RateLimit-Limit (the key's hourly limit), X-RateLimit-Remaining (requests the key has left this hour) and X-RateLimit-Reset (when the counter resets, ISO 8601). When exceeded we return 429 with Retry-After header (seconds until reset):
HTTP/1.1 429 Too Many Requests Retry-After: 1842 X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 2026-06-03T13:00:00Z
Errors
All errors return a uniform JSON shape with error.code (stable) and error.message (human-readable, may change). Log the code, not the message.
{
"success": false,
"error": { "code": "RATE_LIMITED", "message": "Per-key rate limit 1000/h exceeded" },
"meta": { "timestamp": "2026-06-03T12:34:56Z" }
}{
"success": false,
"error": { "code": "BAD_REQUEST", "message": "Validation failed", "details": { "errors": [{ "path": "scopes", "message": "Required" }] } },
"meta": { "timestamp": "2026-06-03T12:34:56Z" }
}| HTTP | code | Meaning |
|---|---|---|
| 400 | BAD_REQUEST | Malformed query or body parameters (generic validation) |
| 401 | UNAUTHORIZED | Missing / invalid Bearer token |
| 402 | SUBSCRIPTION_INACTIVE | Subscription inactive — renew billing to re-enable the key |
| 403 | FORBIDDEN | Key does not have the required scope |
| 404 | NOT_FOUND | The resource does not exist or is outside the API key’s organization. |
| 400 | VALIDATION_ERROR | A parameter failed a check (e.g. phone is not a phone number) |
| 429 | RATE_LIMITED | Hourly limit exceeded (check Retry-After) |
| 500 | DATABASE_ERROR | Server / database error — safe to retry with backoff |
| 503 | MAINTENANCE | Public API temporarily disabled (kill switch) |
| 503 | SERVICE_UNAVAILABLE | A part of the service the call needs is unavailable (for example recording links cannot be minted right now) — retry with backoff |
| 503 | WEBHOOK_ACTIVATION_LOCKED | Turning webhook subscriptions on is paused for a migration; existing subscriptions keep working — retry later |
| 422 | SUBSCRIPTION_LIMIT | The organization reached its limit of webhook subscriptions (HTTP 422) — delete an unused one first |
The SUBSCRIPTION_INACTIVE code appears in two situations: HTTP 402 — your Heilo subscription has lapsed (billing), and HTTP 409 — the webhook endpoint is paused (e.g. on the Test action); in that case click "Reverify" first.
An error may also carry error.details with specifics, for example the failed fields of a validation error; the field can be absent. The code is the stable part.
Every /api/v1 endpoint requires Bearer. /me below is for key introspection; reading calls is in the "Calls" section. When integrating a CRM, treat webhooks as the primary data source — REST is for introspection and reading selected metadata.
API key introspection — returns the key id, user_id, scopes, rate limit. Useful for Zapier/Make "connection test".
Use case: Zapier connection test during custom integration setup. A 200 response proves the key + network work.
curl https://www.heilo.io/api/v1/me \ -H "Authorization: Bearer hk_live_AbC1MnPq..."
{
"success": true,
"data": {
"api_key_id": "a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809",
"user_id": "5f4e3d2c-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
"organization_id": "7a8b9c0d-1e2f-4a3b-9c8d-7e6f5a4b3c2d",
"scopes": ["read.calls", "read.recordings"],
"rate_limit_per_hour": 1000,
"environment": "live"
},
"meta": { "timestamp": "2026-06-03T12:34:56Z" }
}Read endpoints for calls. Require the read.calls scope.
List the organization's calls. Pagination (page/limit≤100), filters: direction, status, date range (dateFrom/dateTo). Returns has_more.
The list is newest first (created_at descending) and paginated by page number, so a call that arrives while you page moves the rows. Deduplicate by call_id, and read the first page again to catch up. This is not a full history export.
Query parameters
| Parameter | Type | Values |
|---|---|---|
| page | int | from 1 (default 1) |
| limit | int | 1–100 (default 20) |
| direction | enum | inbound | outbound |
| status | enum | new | to_call | contacted | qualified |
| dateFrom / dateTo | string | date YYYY-MM-DD or a UTC date-time, e.g. 2026-06-03T12:34:56Z (an offset such as +02:00 returns 400). A date alone in dateTo covers that whole UTC day, so dateTo=2026-06-03 includes calls made on 3 June; a date-time is an exact instant, inclusive |
| phone | string | the customer number on the call, with the country code; spaces, hyphens and the leading + are optional, e.g. +48 600 100 200 |
curl "https://www.heilo.io/api/v1/calls?limit=20&direction=inbound" \ -H "Authorization: Bearer hk_live_AbC1MnPq..."
{
"success": true,
"data": {
"items": [
{
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"direction": "inbound",
"caller_phone": "+48600100200",
"customer_phone_e164": "+48600100200",
"customer_phone_national": "600 100 200",
"company_phone_e164": "+48222630000",
"app_url": "https://www.heilo.io/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6",
"caller_name": "Jan Kowalski",
"duration": 87,
"crm_status": "new",
"review_status": null,
"outcome": "quote_to_send",
"outcome_source": "ai",
"outbound_lifecycle": null,
"transcript_processed": { "caller_name": "Jan Kowalski", "summary": "...", "service_needed": "...", "followup_email": null },
"created_at": "2026-06-03T12:34:56Z"
}
],
"has_more": false,
"page": 1,
"limit": 20
},
"meta": { "timestamp": "2026-06-03T12:34:56Z" }
}Fetch a single call by id. 404 if it doesn't belong to the key's organization or was deleted.
On this endpoint the analysis object transcript_processed carries summary, service_needed, caller_name and followup_email, and also subject, lead_score (1–10, the model's estimate), detected_language and client_city: the same values the call.completed webhook sends. A field the analysis did not produce is null. has_recording says whether audio is stored; the audio itself comes from GET /calls/:id/recording-url with the read.recordings scope.
With the read.transcripts scope the response also carries transcript_original (null when the call has no usable transcript: still processing, failed or no speech), transcript_edited and transcript_edited_at (null when nobody edited it). Without the scope these three fields are absent, not null, and the answer is still 200.
The response also carries user_notes: the entries people wrote about the call in Heilo (“Call notes”), oldest first, at most 200, an empty array when there are none. The list endpoint GET /calls does not carry them. The example is shortened; the other fields are the same as in the list. To be told when entries change, subscribe to call.user_notes.changed.
curl https://www.heilo.io/api/v1/calls/<id> \ -H "Authorization: Bearer hk_live_AbC1MnPq..."
{
"success": true,
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"direction": "inbound",
"duration": 87,
"outcome": "quote_to_send",
"outcome_source": "ai",
"created_at": "2026-06-03T12:34:56Z",
"transcript_processed": {
"caller_name": "Anna Nowak",
"summary": "Asks for a quote for a bathroom renovation.",
"service_needed": "bathroom renovation",
"followup_email": null,
"subject": "Bathroom renovation quote",
"lead_score": 7,
"detected_language": "en",
"client_city": "Gdańsk"
},
"has_recording": true,
"user_notes": [
{
"id": "f3b0c1d2-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"body": "Klient prosi o telefon po 10:00.",
"source": "live",
"author": {
"id": "2ce127a0-c621-483d-b576-e68f69d95e84",
"name": "Anna Nowak"
},
"noted_at": "2026-09-08T10:01:12Z",
"recording_offset_seconds": 72,
"created_at": "2026-09-08T10:01:12Z",
"updated_at": "2026-09-08T10:01:12Z"
}
]
},
"meta": {
"timestamp": "2026-06-03T12:34:56Z"
}
}A freshly signed link to the call audio, valid for 15 minutes. It is a download permission with a deadline rather than a durable reference: store the `call_id` and ask again, because a link saved in a CRM field is dead within the hour. The link inside a `call.recording.ready` webhook is signed for seven days — this endpoint is how you reach the audio after that.
- 200 — the link and the moment it stops working.
- 409 `RECORDING_NOT_READY` — the call is yours and the audio has not arrived yet. Ask again shortly.
- 409 `RECORDING_WITHHELD` — the call is in the trash or scheduled for deletion. The customer can restore a trashed call for 30 days, so keep asking rather than writing the recording off on your side; a call with a recording is erased 30 days after it was moved to the trash. A scheduled deletion cannot be undone: stop using the recording. Either way you get 410 once it is erased.
- 410 `RECORDING_DELETED` — the recording was erased (retention, the trash after 30 days, or an erasure request) and it cannot be recovered. Stop asking and stop re-queueing.
- 410 `RECORDING_NOT_CAPTURED` — this outbound call was never recorded and no recording will ever exist for it: the capture gate refused it when it started, it ran in no_recording mode, or it ended without a conversation. Stop asking; there is no reason to retry. An inbound call whose recording was refused keeps answering 409, because a recording can still follow.
The response is served with `Cache-Control: no-store`, because the body carries a credential. Permission is re-checked when the file is fetched, not only when the link is minted, so a call deleted in between stops being readable immediately.
curl https://www.heilo.io/api/v1/calls/<id>/recording-url \ -H "Authorization: Bearer hk_live_AbC1MnPq..."
{
"success": true,
"data": {
"url": "https://www.heilo.io/api/v1/calls/<id>/recording.mp3?token=...&exp=...",
"expires_at": "2026-09-15T12:15:00.000Z"
}
}Neither the calls list nor the detail returns a recording file or link; the detail only says whether one exists (has_recording). You receive the recording link in a webhook, and after it expires from `GET /calls/:id/recording-url`. Recordings may be deleted under retention and GDPR rules.
What REST carries and what only a webhook carries
The two channels do not carry the same thing, and the difference decides which you pick. REST is durable: you can read a call from it at any time. A webhook is richer, but it arrives once and part of what it carries expires.
| Data | REST | Webhook |
|---|---|---|
| Call metadata: direction, numbers, duration, date | yes | yes |
| CRM status and review status | yes | no |
| Call outcome and who set it | yes | yes |
| Call notes (REST: only in GET /calls/:id) | yes | yes |
| Summary, caller name, what the customer needs | yes | yes |
| The rest of the analysis: city, address, lead score, preferred date, language | partly: GET /calls/:id carries city, lead score and language; address and preferred date come only from the webhook | yes |
| The word-for-word transcript | yes, GET /calls/:id with read.transcripts | yes |
| Recording link | yes, via /calls/:id/recording-url | yes, valid 7 days |
Hence the practical rule: the webhook carries everything at the moment the call is processed, while REST gives the single-call detail afterwards, including the wider analysis and, with read.transcripts, the transcript. The recording is recovered separately — ask /calls/:id/recording-url for a fresh 15-minute link instead of storing the seven-day one from the payload.
Specification and a live request
The same four operations, written for machines: OpenAPI 3.1. Import it into Postman or Insomnia, or generate a client in your own language.
Specification and a live request
Send one request from here to check that your key works, before you write any code.
This calls the real API with your real key and returns your own data. The key stays in this browser tab — we never store it.
Outbound Webhooks
Heilo sends signed JSON events to your endpoint. Add endpoints in the “Webhook endpoints” card. Activation uses a separate, unsigned webhook.subscription.verify handshake; it must never create business records.
The endpoint address must be https, publicly reachable, and must not point to a private or internal address (localhost, 10.x, 192.168.x and the like). To test from your own machine, expose it through a public tunnel. Endpoints are created only in Settings → Integrations; no API call creates one.
POST <your URL>
content-type: application/json
heilo-signature: t=1717423396,v1=4f3a...
heilo-event-id: 1bf3a5e2-...
heilo-event-type: call.completed
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-...",
"event_type": "call.completed",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-06-03T12:34:56Z",
"data": { /* see the setup guide for the full schema */ }
}Retry and pause policy:
- Transient errors retry up to 5 total attempts: after 2 min, 5 min, 30 min and 2 h, with jitter on later retries. After the fifth failure the delivery is dead-lettered.
- Permanent errors (HTTP 401/403/422) pause the endpoint immediately — no retries.
- 50 consecutive transient failures, or 2 consecutive HTTP 410 Gone (e.g. deleted Make scenario), also pause the endpoint.
- Resume a paused endpoint with "Reverify" — a fresh handshake switches sending back on. It does not send the events that were already waiting in the queue when the endpoint paused: those are dead-lettered and need "Resend" in the Delivery log.
When Heilo pauses an endpoint automatically because your address keeps failing, we e-mail the person who looks after it — usually the one who created it. If that account no longer exists, the organization’s owners get the e-mail. You can resend dead-lettered events with the "Resend" button in the Delivery log — once the endpoint passes reverification.
A 2xx response acknowledges HTTP receipt, not completion of an automation or a CRM write. Deliveries may repeat or arrive out of order. Heilo reconciles recent gaps within a bounded window; this is not unlimited historical recovery. Monitor the Delivery log and your CRM separately.
Verification modes
The unsigned handshake contains only event_type = webhook.subscription.verify and challenge. Reply only to confirm the endpoint; do not enqueue business work. Both modes use this same request:
{
"event_type": "webhook.subscription.verify",
"challenge": "example-verification-token"
}Mode permissive (default)
Any 2xx response activates the endpoint; the response body is ignored. This is the default mode for a no-code receiver.
Mode strict (opt-in)
Reply with 2xx and JSON containing exactly the challenge value received from Heilo:
{"challenge":"<echo of the challenge field from Heilo's POST>"}Choose the mode in the creation form. Changing it requires deleting and recreating the endpoint. Endpoint-management routes require a logged-in session and CSRF protection; they are not endpoints available with an API key.
Limits: max 20 active endpoints per organization (env-overridable). An endpoint is auto-paused after 50 consecutive transient failures or 2 consecutive HTTP 410, and immediately on HTTP 401/403/422.
Signature verification (signing_secret)
Signed events, including the manual webhook.test, use Heilo-Signature with HMAC-SHA256 over timestamp + dot + the original request bytes. Verify the signature before parsing business JSON. Only the endpoint-verification handshake is unsigned.
signed_string = "<unix_timestamp>.<raw_request_body>" signature = HMAC-SHA256(signing_secret, signed_string).hex() header = "t=<unix_timestamp>,v1=<signature>"
import { createHmac, timingSafeEqual } from 'node:crypto';
// Pass the exact received Buffer (e.g. Express raw parser), never JSON.stringify(req.body).
// signingSecrets: every secret you currently trust, tried in constant time each.
// During a secret rotation pass [newSecret, oldSecret]; remove the old one once
// Heilo's grace window ends. Heilo itself always sends exactly ONE v1 signature —
// this list is what lets your receiver accept it under either secret while both
// are live, never a second signature to parse.
function verifyHeiloSignature(rawBody, header, signingSecrets) {
const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header || '');
if (!match) return false;
const timestamp = Number(match[1]);
const now = Math.floor(Date.now() / 1000);
// Receiver policy: at most 10 minutes old or 5 minutes ahead (clock skew).
if (!Number.isSafeInteger(timestamp) || now - timestamp > 600 || timestamp - now > 300) return false;
// One string is accepted too. Empty entries are dropped: an HMAC key of ''
// is valid, so a blanked env var (OLD_SECRET=) would let anyone sign events.
const secrets = [].concat(signingSecrets).filter((s) => typeof s === 'string' && s.length > 0);
if (secrets.length === 0) return false;
const actual = Buffer.from(match[2], 'hex');
return secrets.some((signingSecret) => {
const expected = createHmac('sha256', signingSecret)
.update(match[1] + '.')
.update(rawBody)
.digest();
return actual.length === expected.length && timingSafeEqual(actual, expected);
});
}
function receiveHeiloWebhook(rawBody, signatureHeader, signingSecrets) {
if (!signatureHeader) {
// The ONLY unsigned exception confirms the endpoint; never enqueue it for CRM writes.
const probe = JSON.parse(rawBody.toString('utf8'));
if (probe && typeof probe === 'object' && !Array.isArray(probe)
&& Object.keys(probe).length === 2
&& probe.event_type === 'webhook.subscription.verify'
&& typeof probe.challenge === 'string') {
return { kind: 'verification', response: { challenge: probe.challenge } };
}
throw new Error('Missing Heilo-Signature');
}
if (!verifyHeiloSignature(rawBody, signatureHeader, signingSecrets)) throw new Error('Invalid Heilo-Signature');
return { kind: 'event', event: JSON.parse(rawBody.toString('utf8')) };
}
// HTTP adapter: limit body size; map verification to 200 JSON response.
// Signature errors -> 401 (pauses delivery; fix the secret, then Reverify). JSON errors -> 400.
// For kind=event: validate the envelope and chosen event_type, ignore webhook.test
// in business flows, then durably deduplicate/enqueue by event_id BEFORE returning 2xx.
// Enqueue failure: return 503. An HTTP acknowledgement is not proof of a CRM write.These examples accept signatures up to 600 seconds (10 minutes) old and 300 seconds (5 minutes) ahead, matching the existing Heilo verifier. Synchronize server clocks. Timestamp checks limit the replay window; deduplication by event_id is still required.
The signing secret is shown only once — when the endpoint is added. Lost it, or think it leaked? Open the endpoint under Settings → Integrations → Webhooks and rotate it there — see "Secret rotation" below. There is no need to delete and recreate the endpoint.
Secret rotation
Heilo always sends exactly one v1 signature, never two at once. So a rotation is about order: your receiver learns the new secret first, and only then does Heilo start signing with it.
- Prepare a new secret in the endpoint's settings. It is shown once, and waits up to 24 hours for activation.
- Install the new secret NEXT TO the current one — your receiver must accept a signature made with either.
- Optionally send a test signed with the new secret. It carries the Heilo-Secret-Rotation-Id header and an ordinary webhook.test body; a 2xx response does not prove your receiver checked the signature, so confirm that in your own log.
- Activate the rotation.
- Keep the old secret installed for 1 hour after activation, then remove it.
Heilo changes nothing on your receiver. During that window it is your receiver that must accept a signature made with either of the two secrets.
Emergency: the secret leaked
An emergency rotation pauses sending immediately. Install ONLY the new secret — treat the old one as compromised — then activate; there is no grace window. Resume sending afterwards with Reverify. Deliveries already queued when sending paused are skipped; resend them from the delivery log.
Lost the secret but it did not leak? A standard rotation is enough — no need to delete the endpoint.
Event types
Pick event_types when adding an endpoint. Each event has a unique event_id (UUID v5) and deduplicates per endpoint.
webhook.test is sent by the manual Test action and has data._test = true. It goes through the same delivery queue as real events, so it can arrive a moment after the click, and its result appears as a status in the Delivery log. Use it to map fields, then exclude it from business processing. The separate activation handshake is webhook.subscription.verify.
| event_type | Description |
|---|---|
| call.completed | Call completed, transcript ready |
| call.missed | Incoming call ended without a transcript (missed, no message, or not recorded) |
| call.outbound.attempted | Outbound attempt reached a final state (connected or failed) |
| call.recording.ready | Recording file available for download |
| call.transcribed | Transcript ready (separate from call.completed) |
| call.failed | Call failed (busy/no-answer/error) |
| call.outbound.lifecycle_repaired | Outbound lifecycle correction — call state repaired |
| call.deletion_scheduled | Call scheduled for deletion (GDPR Art. 17, retention) |
| call.recording.deleted | Recording deleted (GDPR) |
| call.followup_email.drafted | Follow-up email draft ready |
| call.outcome.changed | Call outcome set or changed |
| call.user_notes.changed | Call notes added, edited or deleted |
| call.tracker.matched | Tracker matched |
| contact.created | New contact created |
| contact.updated | Contact updated |
Below is the data object of every event. Field names, types and enum values are part of the API contract and do not change meaning within v1; new optional fields may be added over time.
call.completed
Sent after the recording and transcript of a completed call are processed. The primary data source for a CRM — full payload (including recording_url and the processed transcript).
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.completed",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"direction": "inbound",
"caller_phone": "+447700900123",
"customer_phone_e164": "+447700900123",
"customer_phone_national": "07700 900123",
"company_phone_e164": "+48222630000",
"call_created_at": "2026-09-08T10:00:00Z",
"app_url": "https://www.heilo.io/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6",
"duration": 87,
"recording_url": "https://www.heilo.io/api/v1/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6/recording.mp3?token=EXAMPLE&exp=1789466400",
"transcript_processed": {
"caller_name": "Alicja Testowa",
"counterparty_name": null,
"counterparty_email": null,
"caller_location": "Warszawa, Mokotów",
"client_address": "ul. Przykładowa 10",
"client_city": "Warszawa",
"client_country": "Poland",
"service_needed": "Tynki gipsowe w mieszkaniu 65m²",
"services_match": true,
"preferred_date": "w przyszłym tygodniu",
"additional_details": "Klient wspomniał o terminie do końca czerwca. Druga rozmowa po wycenie.",
"lead_score": 7,
"summary": "Prośba o wycenę tynków gipsowych w mieszkaniu 65 m² na Mokotowie.",
"subject": "Wycena tynków — Warszawa, 65 m²",
"detected_language": "pl"
},
"transcript_original": "Proszę o ofertę w przyszłym tygodniu.",
"outcome": "quote_to_send",
"outcome_source": "ai"
}
}| Field | Type | Description |
|---|---|---|
| call_id | string (uuid) | Call ID in Heilo. For business call events it equals resource_id; in webhook.test it is a synthetic call ID. |
| direction | 'inbound' | 'outbound' | Call direction. |
| caller_phone | string | null | Stored caller number; null if unavailable in call.completed. |
| customer_phone_e164 | string | null | Customer number for matching a CRM contact; null if unavailable in call.completed. |
| customer_phone_national | string | null | The same customer number in national format, ready to paste into a CRM phone field; null when the stored value is not a usable number, as with a withheld caller ID. |
| company_phone_e164 | string | null | The number this call came in on, or went out from. Usually your Heilo number; on a forwarded call it is your own number that forwarded it. Use it to route notes when you run more than one number; null when not recorded. |
| call_created_at | string (ISO 8601) | null | When the call was recorded in Heilo (ISO 8601). Not the same as the envelope created_at, which is the moment the event was sent and can be days later for a repaired event. |
| app_url | string | null | Permanent link to the call in Heilo. Unlike recording_url it does not expire, so it is safe to store in a CRM record. Opening it requires a Heilo login. |
| duration | number | Recording length in seconds. |
| recording_url | string | null | Link to the recording, valid for 7 days; null when the recording was not yet stored at processing time. Once it expires, get a fresh link from GET /calls/:id/recording-url. |
| transcript_processed | object | Processed call analysis — see the transcript_processed field reference in this section. |
| transcript_original | string | null | Raw verbatim transcript; null when unavailable. |
| outcome | string | null | Outcome code at the moment the event was built (see the outcome codes below); null when nobody has set one. The key is absent on a replay of an older event or when Heilo could not read it. A later call.outcome.changed supersedes it. |
| outcome_source | 'ai' | 'user' | null | Who set the outcome: ai (picked by the analysis), user (picked or confirmed by a person) or null (nobody). Absent whenever outcome is absent. |
Delivery is at-least-once and not order-guaranteed — persist idempotently. Dedup key: event_id. data.call_id links events of the same call (e.g. call.completed after call.recording.ready).
Call outcome
outcome is one of the codes below, or null when nobody has set one. outcome_source says who set it: ai or user. REST returns both on every call; call.completed and call.transcribed carry them at the top level of data; call.outcome.changed reports every later change. New codes may be added, so treat an unknown value as optional information rather than an error.
| Code | Meaning |
|---|---|
| booking | A booking, visit or appointment was agreed. |
| cancellation_or_reschedule | The caller cancelled or asked for a new date. |
| information_request | The caller asked for information. |
| quote_to_send | The caller is waiting for a quote or offer. |
| awaiting_customer_decision | The customer is thinking it over and will decide. |
| deal_won | The customer agreed in the call to buy or order, or accepted the offer. Only run a "deal won" automation in your CRM when outcome_source is user. |
| callback_scheduled | A follow-up contact was agreed. |
| not_interested | The caller is not interested. |
| spam_wrong_number | Empty message, spam or a wrong number. |
| new_opportunity | A new sales opportunity.legacy: no longer offered, can still appear on older calls |
| existing_deal_update | An update on an existing project.legacy: no longer offered, can still appear on older calls |
| follow_up | A follow-up after an earlier contact.legacy: no longer offered, can still appear on older calls |
| no_answer | Nobody answered.legacy: no longer offered, can still appear on older calls |
| voicemail | The caller left a voicemail.legacy: no longer offered, can still appear on older calls |
| support | A support request.legacy: no longer offered, can still appear on older calls |
| complaint | A complaint.legacy: no longer offered, can still appear on older calls |
Which value wins
A call.outcome.changed event supersedes the outcome in call.completed and call.transcribed, in whatever order they arrive. Order change events by data.changed_at, never by arrival time or the envelope created_at. REST always returns the current value, so use it to recover from a missed event.
data.outcome is a code from the table above. It is not the same as transcript_processed.call_outcome, which is a free-text sentence from the analysis.
Zapier and Make: the Test button sends the call.completed shape. To get a call.outcome.changed sample, pick an outcome on any call in Heilo.
Call notes (user_notes)
user_notes is the list of entries people wrote about a call in Heilo (“Call notes”). REST returns it only in GET /calls/:id; call.user_notes.changed sends the whole current list about five minutes after the last change. The author is the full name from the Heilo profile, never an e-mail address.
Which list wins
Every list carries a revision that grows with each change. Replace your copy with a list only when its revision is higher than the one you hold, and drop any other: a manual resend delivers an older list again. REST always returns the current list, so use it to recover from a missed event.
source tells where an entry came from: live (typed on the call screen during the call), after (added afterwards) or legacy (the single call note from before 2026-10-28). New values may be added, so treat an unknown value as optional information rather than an error. recording_offset_seconds is set only for a live entry typed inside the recording.
Zapier and Make: the Test button sends the call.completed shape. To get a call.user_notes.changed sample, add an entry to any call in Heilo and wait five minutes.
call.missedUsually sent about two hours after an incoming call that ended without a transcript, and up to about 4 h 15 min later when the call's end was not reported. data.reason says why and data.answered says whether anyone picked up. The cases are: nobody answered and no message was left, the caller hung up before recording started, recording was switched off for the number at that time, Heilo did not record the call on purpose, the recording was too short, or no transcript could be made. A call that was answered but has no transcript is sent too, with answered set to true, so create a callback only when answered is false. Off by default — add call.missed to an endpoint’s events to receive it; an endpoint that adds it later may also receive such calls from up to the last 7 days, so check call_created_at. Sent at most once per call. Order is not guaranteed: if a call.completed exists for the same call_id (a recording that arrived late, or a call that lasted over two hours), call.completed describes the call, whichever arrived first; subscribe to both to see such calls. A deletion in Heilo is announced with call.deletion_scheduled or call.recording.deleted only for a call that had a recording; a call without one gets no deletion event, so remove your copy yourself if you need to. Calls you added Heilo to are not included. Zapier and Make: the Test button sends the call.completed shape; for a call.missed sample, call your Heilo number, hang up before anyone answers and wait about two hours.
| Field | Type | Description |
|---|---|---|
| call_id | string (uuid) | Call ID in Heilo. For business call events it equals resource_id; in webhook.test it is a synthetic call ID. |
| direction | 'inbound' | Call direction. |
| customer_phone_e164 | string | null | Customer number for matching a CRM contact; null if unavailable in call.completed. |
| customer_phone_national | string | null | The same customer number in national format, ready to paste into a CRM phone field; null when the stored value is not a usable number, as with a withheld caller ID. |
| company_phone_e164 | string | null | The number this call came in on, or went out from. Usually your Heilo number; on a forwarded call it is your own number that forwarded it. Use it to route notes when you run more than one number; null when not recorded. |
| call_created_at | string (ISO 8601) | null | When the call was recorded in Heilo (ISO 8601). Not the same as the envelope created_at, which is the moment the event was sent and can be days later for a repaired event. |
| app_url | string | null | Permanent link to the call in Heilo. Unlike recording_url it does not expire, so it is safe to store in a CRM record. Opening it requires a Heilo login. |
| reason | 'no_recording' | 'capture_refused' | 'no_speech' | 'not_transcribed' | Why there is no transcript: no_recording — nothing was recorded (nobody answered and no message was left, the caller hung up before recording started, or recording was switched off for this number at that time); capture_refused — Heilo did not record the call on purpose (your plan or trial does not cover recording, or the number is on the “Do not record” list); no_speech — the recording was too short to hold a message (three seconds or less); not_transcribed — a recording exists but no usable transcript could be made. Read answered to know whether anyone picked up. New values may be added. |
| has_recording | boolean | true when a recording of this call exists; an API key with the read.recordings scope gets a link to it from GET /calls/:id/recording-url. |
| answered | boolean | true when the call was put through and answered, for example a conversation Heilo did not record; false when nobody answered. Create a callback only when it is false. |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.missed",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"direction": "inbound",
"customer_phone_e164": "+447700900123",
"customer_phone_national": "07700 900123",
"company_phone_e164": "+48222630000",
"call_created_at": "2026-09-08T10:00:00Z",
"app_url": "https://www.heilo.io/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6",
"reason": "no_recording",
"has_recording": false,
"answered": false
}
}call.outbound.attemptedSent when an outbound dial reaches a final state — including failures. completed means the call connected and ended normally; the recording and transcript follow as separate events.
| Field | Type | Description |
|---|---|---|
| call_id | string (uuid) | Call ID in Heilo. For business call events it equals resource_id; in webhook.test it is a synthetic call ID. |
| agent_user_id | string (uuid) | ID of the Heilo user who placed the call. |
| customer_phone | string | The dialled customer number. |
| customer_phone_e164 | string | Customer number for matching a CRM contact; null if unavailable in call.completed. |
| outbound_lifecycle | 'completed' | 'agent_only' | 'agent_no_answer' | 'customer_no_answer' | 'failed_to_initiate' | Final state that triggered the event; completed means the call connected and ended normally. |
| duration | number | null | Call duration in seconds; null when the call failed at initiation or the duration is not known yet. |
| attempted_at | string (ISO 8601) | When the event was emitted (ISO 8601). |
| has_recording | boolean | true only when outbound_lifecycle is completed and the call was not in no_recording mode — the recording then follows as call.recording.ready. |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.outbound.attempted",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"agent_user_id": "2ce127a0-c621-483d-b576-e68f69d95e84",
"customer_phone": "+447700900123",
"customer_phone_e164": "+447700900123",
"outbound_lifecycle": "completed",
"duration": 95,
"attempted_at": "2026-09-08T10:00:00Z",
"has_recording": true
}
}call.recording.readySent when the recording file is available. Use it to fetch or archive the audio.
| Field | Type | Description |
|---|---|---|
| call_id | string (uuid) | Call ID in Heilo. For business call events it equals resource_id; in webhook.test it is a synthetic call ID. |
| recording_url | string | null | Link to the recording, valid for 7 days; in rare cases null when the link could not be generated. Once it expires, get a fresh link from GET /calls/:id/recording-url. |
| duration | number | null | Duration in seconds; null when not reported yet. |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.recording.ready",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"recording_url": "https://www.heilo.io/api/v1/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6/recording.mp3?token=EXAMPLE&exp=1789466400",
"duration": 87
}
}call.transcribedSent in the same processing run as call.completed — it carries only the transcript, without call metadata or the recording link.
| Field | Type | Description |
|---|---|---|
| call_id | string (uuid) | Call ID in Heilo. For business call events it equals resource_id; in webhook.test it is a synthetic call ID. |
| transcript_original | string | null | Raw verbatim transcript; null when unavailable. |
| transcript_processed | object | Processed call analysis — see the transcript_processed field reference in this section. |
| outcome | string | null | Outcome code at the moment the event was built (see the outcome codes below); null when nobody has set one. The key is absent on a replay of an older event or when Heilo could not read it. A later call.outcome.changed supersedes it. |
| outcome_source | 'ai' | 'user' | null | Who set the outcome: ai (picked by the analysis), user (picked or confirmed by a person) or null (nobody). Absent whenever outcome is absent. |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.transcribed",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"transcript_original": "Proszę o ofertę w przyszłym tygodniu.",
"transcript_processed": {
"caller_name": "Alicja Testowa",
"counterparty_name": null,
"counterparty_email": null,
"caller_location": "Warszawa, Mokotów",
"client_address": "ul. Przykładowa 10",
"client_city": "Warszawa",
"client_country": "Poland",
"service_needed": "Tynki gipsowe w mieszkaniu 65m²",
"services_match": true,
"preferred_date": "w przyszłym tygodniu",
"additional_details": "Klient wspomniał o terminie do końca czerwca. Druga rozmowa po wycenie.",
"lead_score": 7,
"summary": "Prośba o wycenę tynków gipsowych w mieszkaniu 65 m² na Mokotowie.",
"subject": "Wycena tynków — Warszawa, 65 m²",
"detected_language": "pl"
},
"outcome": "quote_to_send",
"outcome_source": "ai"
}
}call.failedSent when an outbound call did not complete (no answer, busy, initiation error). Emitted for outbound calls only. Usually not worth creating a lead — log a contact attempt instead.
| Field | Type | Description |
|---|---|---|
| call_id | string (uuid) | Call ID in Heilo. For business call events it equals resource_id; in webhook.test it is a synthetic call ID. |
| outbound_lifecycle | 'agent_only' | 'agent_no_answer' | 'customer_no_answer' | 'failed_to_initiate' | Which stage of the outbound call failed. |
| failure_reason | string | null | Machine-readable failure code (e.g. customer_busy, agent_no_confirmation, or carrier_rejected when the carrier refused the call to the salesperson's phone); can be null. |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.failed",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"outbound_lifecycle": "customer_no_answer",
"failure_reason": "customer_busy"
}
}call.outbound.lifecycle_repairedSent when Heilo retroactively corrects the state of an outbound call (a late carrier callback proved the call did connect). Update the call state on your side.
| Field | Type | Description |
|---|---|---|
| call_id | string (uuid) | Call ID in Heilo. For business call events it equals resource_id; in webhook.test it is a synthetic call ID. |
| previous_lifecycle | 'agent_only' | State before the correction; currently always agent_only. |
| new_lifecycle | 'completed' | State after the correction; currently always completed. |
| repaired_at | string (ISO 8601) | When the correction happened (ISO 8601). |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.outbound.lifecycle_repaired",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"previous_lifecycle": "agent_only",
"new_lifecycle": "completed",
"repaired_at": "2026-09-08T10:00:00Z"
}
}call.deletion_scheduledGDPR Art. 17: the call is scheduled for deletion. Your CRM should stop using the recording and prepare to delete the data. You are told about a call only if Heilo has a record that its content could have reached your endpoint. Subscribing to the deletion events alone does not make you a recipient — there is nothing to delete if you never received anything.
| Field | Type | Description |
|---|---|---|
| call_id | string (uuid) | Call ID in Heilo. For business call events it equals resource_id; in webhook.test it is a synthetic call ID. |
| pending_deletion_at | string (ISO 8601) | When the data will be permanently deleted (ISO 8601). |
| reason | 'consent_not_asked' | 'consent_withdrawn' | 'retention_expired' | 'user_erasure' | Why the deletion was scheduled. |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.deletion_scheduled",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"pending_deletion_at": "2026-09-09T10:00:00Z",
"reason": "retention_expired"
}
}call.recording.deletedGDPR: the recording was deleted — recording_url returns 410. Remove or disable the recording link on your side. When `reason` is anything other than `retention_expired`, the transcript, the summary, the details extracted from the call and the call notes were erased too — delete them on your side as well. Calls moved to the trash arrive as this event with reason `user_erasure` 30 days after they were trashed. You are told about a call only if Heilo has a record that its content could have reached your endpoint, so this is not a complete feed of every deletion in your organization. A 2xx from you means the instruction arrived, never that the copy is gone.
| Field | Type | Description |
|---|---|---|
| call_id | string (uuid) | Call ID in Heilo. For business call events it equals resource_id; in webhook.test it is a synthetic call ID. |
| reason | string | null | Reason recorded when the deletion was scheduled; can be null. |
| recording_sid | string | null | Twilio recording ID; null when it could not be resolved. |
| deletion_kind | 'hard_deleted' | 'twilio_404' | hard_deleted = deleted by Heilo; twilio_404 = the file was already gone on Twilio's side. |
| deleted_at | string (ISO 8601) | When the recording was deleted (ISO 8601). |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.recording.deleted",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"reason": "user_erasure",
"recording_sid": null,
"deletion_kind": "twilio_404",
"deleted_at": "2026-09-08T10:00:00Z"
}
}call.followup_email.draftedSent after a two-sided call is processed and Heilo has composed a follow-up email draft from what was agreed. Not sent for voicemail, nor when no draft could be composed. Heilo NEVER sends this email to the caller — the draft is for your rep to review and send.
| Field | Type | Description |
|---|---|---|
| call_id | string (uuid) | Call ID in Heilo. For business call events it equals resource_id; in webhook.test it is a synthetic call ID. |
| subject | string | Email subject, ready to paste. |
| body | string | Email body as plain text, WITHOUT a signature — the rep adds their own when sending. |
| language | string | Draft language: the detected call language, falling back to the account language configured in Heilo (not a per-number setting). |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.followup_email.drafted",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"subject": "Oferta po rozmowie",
"body": "Dzień dobry, przesyłam ustalenia naszej rozmowy.",
"language": "pl"
}
}call.outcome.changedSent whenever the outcome of a call changes: a person picks, changes, confirms or clears it in Heilo, or a re-analysis changes the outcome Heilo picked earlier. The outcome Heilo picks when it first analyses a recording does not get its own event; it arrives in call.completed and call.transcribed. An outcome picked for the first time only during a later re-analysis does send call.outcome.changed. Not sent for calls in the trash or scheduled for deletion. Change events supersede the outcome in call.completed and call.transcribed; order them by data.changed_at.
| Field | Type | Description |
|---|---|---|
| call_id | string (uuid) | Call ID in Heilo. For business call events it equals resource_id; in webhook.test it is a synthetic call ID. |
| outcome | string | null | The outcome after the change; null when it was cleared or withdrawn. |
| outcome_source | 'ai' | 'user' | null | Who set it after the change: ai, user or null. A null outcome with user means a person cleared it; a null outcome with null means the analysis withdrew its pick. |
| previous_outcome | string | null | The outcome before the change; null when there was none. |
| previous_outcome_source | 'ai' | 'user' | null | Who had set the previous outcome: ai, user or null. |
| changed_at | string (ISO 8601) | When the change was stored (ISO 8601). Use it to order change events: the one with the latest changed_at is current. It is not the envelope created_at. |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.outcome.changed",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"outcome": "booking",
"outcome_source": "user",
"previous_outcome": "quote_to_send",
"previous_outcome_source": "ai",
"changed_at": "2026-09-08T10:05:00Z"
}
}call.user_notes.changedSent when the entries people wrote about a call in Heilo (“Call notes”) change: someone adds, edits or deletes an entry. data.notes is the WHOLE current list, not a diff, so your CRM replaces its copy instead of merging. The event goes out about five minutes after the last change (for entries typed during a call: about five minutes after the call) and never more often than once every five minutes per call. data.revision grows with every change; drop a list whose revision is not higher than the one you already hold (a manual resend sends an older list again). Not sent for calls in the trash or scheduled for deletion.
| Field | Type | Description |
|---|---|---|
| call_id | string (uuid) | Call ID in Heilo. For business call events it equals resource_id; in webhook.test it is a synthetic call ID. |
| revision | integer | Counter that grows with every change to the call’s entries. Keep the highest revision you have seen for the call and drop any list whose revision is not higher; a manual resend or a replay delivers an older list. |
| changed_at | string (ISO 8601) | When Heilo built this list (ISO 8601). It is not the envelope created_at, and not the moment a person edited an entry. |
| notes | object[] | The whole current list of entries, oldest first, at most 200; empty when the last entry was deleted. Replace your copy with it. |
| notes[].id | string (uuid) | Entry identifier; it stays the same when the text is edited. |
| notes[].body | string | The entry text, 1 to 2000 characters. |
| notes[].source | 'live' | 'after' | 'legacy' | live: typed on the call screen during the call. after: added afterwards in Heilo. legacy: the single call note from before 2026-10-28, moved into the entries. New values may be added. |
| notes[].author.id | string (uuid) | null | The Heilo user who wrote the entry. Null for a legacy entry or when that account was deleted. |
| notes[].author.name | string | null | The author’s full name from their Heilo profile; null when the profile has none. Never an e-mail address. A later name change shows up in the next list, without an event of its own. |
| notes[].noted_at | string (ISO 8601) | When the person wrote it (ISO 8601); for a live entry, the moment during the call. |
| notes[].recording_offset_seconds | integer | null | Seconds from the start of the recording, only for an entry typed during the call inside the recording; null otherwise. |
| notes[].created_at | string (ISO 8601) | When the entry was stored (ISO 8601). |
| notes[].updated_at | string (ISO 8601) | Last edit of the text (ISO 8601). |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.user_notes.changed",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"revision": 3,
"changed_at": "2026-09-08T10:12:00Z",
"notes": [
{
"id": "f3b0c1d2-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"body": "Klient prosi o telefon po 10:00.",
"source": "live",
"author": {
"id": "2ce127a0-c621-483d-b576-e68f69d95e84",
"name": "Anna Nowak"
},
"noted_at": "2026-09-08T10:01:12Z",
"recording_offset_seconds": 72,
"created_at": "2026-09-08T10:01:12Z",
"updated_at": "2026-09-08T10:01:12Z"
}
]
}
}call.tracker.matchedSent when at least one configured keyword tracker matches the processed transcript. Each match includes terms and excerpts; an absent excerpt is represented by an empty array.
| Field | Type | Description |
|---|---|---|
| call_id | string (uuid) | Call ID in Heilo. For business call events it equals resource_id; in webhook.test it is a synthetic call ID. |
| matches | object[] | The trackers matched in this call. |
| matches[].tracker_id | string (uuid) | Identifier of the configured tracker. |
| matches[].name | string | Tracker name. |
| matches[].matched_terms | string[] | Matched terms. |
| matches[].excerpts | string[] | Transcript excerpts; may be empty. |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.tracker.matched",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"matches": [
{
"tracker_id": "cd794362-6117-44d1-b487-c5e7e1ea9082",
"name": "Oferta",
"matched_terms": [
"ofertę"
],
"excerpts": [
"Proszę o ofertę w przyszłym tygodniu."
]
}
]
}
}contact.createdSent when a new contact is created in Heilo. data.contact is a full snapshot of the new contact; notes and tags are not included.
| Field | Type | Description |
|---|---|---|
| contact | object | Full snapshot of the new contact (fields below). |
| contact.id | string (uuid) | Contact ID in Heilo. |
| contact.phone | string | The contact's phone number. |
| contact.first_name | string | null | null when not provided. |
| contact.last_name | string | null | null when not provided. |
| contact.email | string | null | null when not provided. |
| contact.company | string | null | null when not provided. |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "contact.created",
"resource_id": "86c68698-d54c-43e7-bbbc-328499b98d12",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"contact": {
"id": "86c68698-d54c-43e7-bbbc-328499b98d12",
"phone": "+447700900123",
"first_name": "Alicja",
"last_name": "Testowa",
"email": "alicja@example.com",
"company": null
}
}
}contact.updatedSent when a contact is edited. Unlike contact.created, this is not a snapshot: data.diff contains only the changed fields.
| Field | Type | Description |
|---|---|---|
| contact_id | string (uuid) | ID of the updated contact. |
| diff | object (partial) | Only the fields that changed — keys absent from diff were not modified. |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "contact.updated",
"resource_id": "86c68698-d54c-43e7-bbbc-328499b98d12",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"contact_id": "86c68698-d54c-43e7-bbbc-328499b98d12",
"diff": {
"company": "Example",
"notes": "Oddzwonić",
"tags": [
"oferta"
]
}
}
}Possible keys in diff: first_name, last_name, email, phone, company, notes, tags
webhook.testSent only when you press Test on an endpoint. resource_id is the endpoint ID, not a call ID. The data contains a synthetic call.completed payload and the three test markers below. It does not prove that real audio is available.
| Field | Type | Description |
|---|---|---|
| call_id | string (uuid) | Call ID in Heilo. For business call events it equals resource_id; in webhook.test it is a synthetic call ID. |
| direction | 'inbound' | 'outbound' | Call direction. |
| caller_phone | string | null | Stored caller number; null if unavailable in call.completed. |
| customer_phone_e164 | string | null | Customer number for matching a CRM contact; null if unavailable in call.completed. |
| customer_phone_national | string | null | The same customer number in national format, ready to paste into a CRM phone field; null when the stored value is not a usable number, as with a withheld caller ID. |
| company_phone_e164 | string | null | The number this call came in on, or went out from. Usually your Heilo number; on a forwarded call it is your own number that forwarded it. Use it to route notes when you run more than one number; null when not recorded. |
| call_created_at | string (ISO 8601) | null | When the call was recorded in Heilo (ISO 8601). Not the same as the envelope created_at, which is the moment the event was sent and can be days later for a repaired event. |
| app_url | string | null | Permanent link to the call in Heilo. Unlike recording_url it does not expire, so it is safe to store in a CRM record. Opening it requires a Heilo login. |
| duration | number | Recording length in seconds. |
| recording_url | string | null | Link to the recording, valid for 7 days; null when the recording was not yet stored at processing time. Once it expires, get a fresh link from GET /calls/:id/recording-url. |
| transcript_processed | object | Processed call analysis — see the transcript_processed field reference in this section. |
| transcript_original | string | null | Raw verbatim transcript; null when unavailable. |
| outcome | string | null | Outcome code at the moment the event was built (see the outcome codes below); null when nobody has set one. The key is absent on a replay of an older event or when Heilo could not read it. A later call.outcome.changed supersedes it. |
| outcome_source | 'ai' | 'user' | null | Who set the outcome: ai (picked by the analysis), user (picked or confirmed by a person) or null (nobody). Absent whenever outcome is absent. |
| _test | true | Always true — tells the test message apart from real events. |
| _message | string | Human-readable note that this is a test. |
| _sent_at | string (ISO 8601) | When the test was sent (ISO 8601). |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "webhook.test",
"resource_id": "c2d38cc8-bc1d-4336-91ea-51b8a549a882",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"direction": "inbound",
"caller_phone": "+447700900123",
"customer_phone_e164": "+447700900123",
"customer_phone_national": "07700 900123",
"company_phone_e164": "+48222630000",
"call_created_at": "2026-09-08T10:00:00Z",
"app_url": "https://www.heilo.io/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6",
"duration": 87,
"recording_url": "https://www.heilo.io/api/v1/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6/recording.mp3?token=EXAMPLE&exp=1789466400",
"transcript_processed": {
"caller_name": "Alicja Testowa",
"counterparty_name": null,
"counterparty_email": null,
"caller_location": "Warszawa, Mokotów",
"client_address": "ul. Przykładowa 10",
"client_city": "Warszawa",
"client_country": "Poland",
"service_needed": "Tynki gipsowe w mieszkaniu 65m²",
"services_match": true,
"preferred_date": "w przyszłym tygodniu",
"additional_details": "Klient wspomniał o terminie do końca czerwca. Druga rozmowa po wycenie.",
"lead_score": 7,
"summary": "Prośba o wycenę tynków gipsowych w mieszkaniu 65 m² na Mokotowie.",
"subject": "Wycena tynków — Warszawa, 65 m²",
"detected_language": "pl"
},
"transcript_original": "Proszę o ofertę w przyszłym tygodniu.",
"outcome": "quote_to_send",
"outcome_source": "ai",
"_test": true,
"_message": "Synthetic webhook test; do not create CRM records.",
"_sent_at": "2026-09-08T10:00:00Z"
}
}transcript_processed — field reference
The stable subset you can rely on when mapping to a CRM. Every field is optional — it is null when the call did not contain that information.
| Field | Type | Description |
|---|---|---|
| caller_name | string | null | The caller's name, if they gave one. |
| summary | string | null | Short paragraph summarising the call. |
| subject | string | null | One-line title of the call (up to 80 characters). |
| service_needed | string | null | What the caller asked for. |
| services_match | boolean | null | Whether the request matches the services you offer. |
| lead_score | number | null (1–10) | Lead quality estimate from 1 to 10, or null when the AI gave none. |
| preferred_date | string | null | Date or time the caller mentioned, if any. |
| client_city | string | null | City, if mentioned. |
| client_address | string | null | Street address, if mentioned. |
| additional_details | string | null | Extra context from the call. |
Fields that may appear
| Field | Type | Description |
|---|---|---|
| caller_location | string | null | Geographic reference detected in the conversation. |
| client_country | string | null | Country, if mentioned. |
| counterparty_name | string | null | Name of the other party — only on outbound calls and on live calls Heilo was added to. |
| counterparty_email | string | null | The client's e-mail address as said in the call and matched against the transcript — only on live calls Heilo was added to. |
| detected_language | string | Language code of the conversation (e.g. pl); the key may be absent entirely. |
| proposal_items | object[] | null | Suggested follow-ups and decisions extracted from the call. |
The analysis may include additional fields — treat unknown fields as optional and never assume they are present.
Roadmap (v1.1+)
Endpoints planned for upcoming v1.X releases. Not a hard commitment — direction depends on feedback.
- GET /contacts — list contacts
- POST /contacts — create contact (sync from CRM into Heilo)
- POST /calls — initiate an outbound call through your Heilo number; it is recorded, transcribed and delivered to your CRM like any other call
Need an endpoint? Email support@heilo.io with your use-case — we prioritize the roadmap based on real demand.
Roadmap (v1.1+)
Need an endpoint? Email support@heilo.io with your use-case — we prioritize the roadmap based on real demand.
Manage keys and webhooks in the panel
Generate API keys, add webhook endpoints and watch the delivery log after signing in.