Payload Reference

Every event notification delivery has the same shape: a JSON body containing an event discriminator, a small set of account fields, and one or more groups of enriched fields (contact, CDR, task, staff) depending on what's relevant to the event.

This page documents the full payload schema, then shows what extra fields each event includes.

Common envelope

Every payload has these top-level fields:

Field	Type	Description
`event`	string	The event name. One of the available events.
`superfone_number`	string	Your account's Superfone number.
`organization_name`	string	Your account's name.
`cdr_phone`	string \| null	The customer phone number from the triggering payload (when applicable).
`updated_key`	string \| null	For `*_CHANGE` events: which field changed.
`updated_value`	any \| null	For `*_CHANGE` events: the new value of `updated_key`.

Contact fields

Included when the event is associated with a CRM contact (most call, lead, and task events).

Field	Type	Description
`contact_id`	number	Internal lead ID.
`contact_first_name`	string \| null	First name.
`contact_last_name`	string \| null	Last name.
`contact_phones`	object[]	All phone numbers on the lead, each `{ phone, customer_id }`.
`contact_source`	string \| null	Free-form source string.
`contact_source_type`	string \| null	Source type enum (e.g. `OTHERS`, `WHATSAPP_INTEGRATION`).
`contact_lead_stage_id`	number \| null	Current lead stage ID.
`contact_lead_stage_name`	string \| null	Current lead stage title.
`contact_lead_group_id`	number \| null	Current lead group ID.
`contact_lead_group_name`	string \| null	Current lead group title.
`contact_labels`	object[]	Labels on the lead, each `{ id, title }`.
`contact_products`	object[]	Products attached to the lead, each `{ id, title }`.
`contact_assignee_user_id`	number \| null	ID of the assigned team member.
`contact_business_name`	string \| null	Business / company name.
`contact_additional_info`	string \| null	Free-form notes on the lead.
`contact_emails`	string[] \| null	Email addresses.
`contact_custom_fields`	object	Custom fields keyed by your account's custom-field labels.

updated_key resolution

When a custom field is renamed by your account's "custom field labels", updated_key in the payload is rewritten to the human-readable label (not the underlying custom_text_1 slot). This makes change-event payloads readable without needing your custom field map.

CDR (call) fields

Included when the event is associated with a call.

Field	Type	Description
`cdr_id`	number	Internal CDR ID.
`cdr_disposition`	string	Outcome — `ANSWER`, `BUSY`, `NOANSWER`, `CANCEL`, `IVR_ANSWERED`, `BLOCKED`, etc. (full list below).
`cdr_duration`	number \| null	Talk duration in seconds.
`cdr_call_type`	string	`INBOUND` or `OUTBOUND`.
`cdr_start`	string \| null	ISO 8601 — when the call leg started.
`cdr_answer`	string \| null	ISO 8601 — when the call was answered. `null` if never answered.
`cdr_end`	string \| null	ISO 8601 — when the call ended.
`cdr_ringing_duration`	number \| null	Time the call was ringing before being answered/missed, in seconds.
`ivr_inputs`	object[]	Optional. IVR menu prompts and what the caller pressed: `{ greetingText, playbackText, userPressedKey }[]`.
`dtmf_digits`	string[]	Optional. Raw DTMF digits captured during the call.

`cdr_disposition` values

ANSWER, BUSY, NOANSWER, CANCEL, CONGESTION, CHANUNAVAIL, DONTCALL, TORTURE, RINGING, ACTIVE, CREATED, UNKNOWN, UNKNOWN_BY_SYSTEM, SENT_TO_BACKUP, BACKUP_ANSWER, BACKUP_FAILED, BACKUP_ENDED, BACKUP_MISSED, BACKUP_BUSY, BACKUP_NOANSWER, DEMO_CALL, BACKUP_RINGING, BACKUP_ACTIVE, OUTBOUND_CHANUNAVAIL, INBOUND_CHANUNAVAIL, BLINDTRANSFER_CHANUNAVAIL, IVR_DROPPED, SUBSCRIPTION_EXPIRED, TRIAL_INTERNATIONAL, OOO_DROP, BLOCKED, DROP_CALL, NORMAL_CALL_FLOW, STICKY_AGENT_DROP, IVR_ANSWERED, BACKUP_CANCEL, NOT_ALLOWED, IVR_INVALID_INPUT, REJECTED, UNALLOCATED, FORWARDED, APP_UNINSTALLED.

Staff fields

Included on call-related events when the call was handled by a Superfone team member.

Field	Type	Description
`staff_first_name`	string \| null	First name of the agent who handled the call.
`staff_last_name`	string \| null	Last name.
`staff_phone`	string \| null	Phone number.

Task fields

Included on task-related events.

Field	Type	Description
`task_id`	number	Internal task ID.
`task_type`	string \| null	`REMINDER`, `FIRST_CALL`, etc.
`task_status`	string \| null	`PENDING`, `COMPLETED`, etc.

Per-event extras

`ALL_CALLS` and `MISSED_CALL`

Common envelope + contact fields + CDR fields + staff fields. MISSED_CALL only fires for calls that ended without being answered — the same payload as ALL_CALLS for those calls.

{
  "event": "ALL_CALLS",
  "superfone_number": "+918000099999",
  "organization_name": "Acme Pvt Ltd",
  "cdr_phone": "+918000000001",
  "contact_id": 12345,
  "contact_first_name": "Asha",
  "contact_last_name": "Kumar",
  "contact_phones": [{ "phone": "+918000000001", "customer_id": 12345 }],
  "contact_source": "website-form",
  "contact_source_type": "OTHERS",
  "contact_lead_stage_id": 9,
  "contact_lead_stage_name": "New Lead",
  "contact_lead_group_id": 3,
  "contact_lead_group_name": "Inbound",
  "contact_labels": [{ "id": 17, "title": "Hot" }],
  "contact_products": [],
  "contact_assignee_user_id": 678,
  "contact_business_name": "Acme Pvt Ltd",
  "contact_additional_info": null,
  "contact_emails": ["asha@example.com"],
  "contact_custom_fields": {},
  "cdr_id": 9876543,
  "cdr_disposition": "ANSWER",
  "cdr_duration": 142,
  "cdr_call_type": "OUTBOUND",
  "cdr_start": "2026-05-15T10:30:00.000Z",
  "cdr_answer": "2026-05-15T10:30:08.000Z",
  "cdr_end": "2026-05-15T10:32:30.000Z",
  "cdr_ringing_duration": 8,
  "staff_first_name": "Ravi",
  "staff_last_name": "Patel",
  "staff_phone": "+919876543210"
}

`CDR_RECORDING_AVAILABLE`

Fires when a call recording is uploaded and ready to download. Adds:

Field	Type	Description
`cdr_recording_url`	string	A pre-signed URL to download the recording. Valid for 7 days from delivery time — download and store it within this window.
`cdr_recording_status`	string	Always `OK` (the notification only fires on successful uploads).

{
  "event": "CDR_RECORDING_AVAILABLE",
  "superfone_number": "+918000099999",
  "organization_name": "Acme Pvt Ltd",
  "cdr_phone": "+918000000001",
  "cdr_recording_url": "https://recordings.s3.amazonaws.com/…?X-Amz-Signature=…",
  "cdr_recording_status": "OK",
  "cdr_id": 9876543,
  "cdr_disposition": "ANSWER",
  "cdr_duration": 142,
  "cdr_call_type": "OUTBOUND",
  "cdr_start": "2026-05-15T10:30:00.000Z",
  "cdr_answer": "2026-05-15T10:30:08.000Z",
  "cdr_end": "2026-05-15T10:32:30.000Z",
  "cdr_ringing_duration": 8,
  "contact_id": 12345,
  "contact_first_name": "Asha",
  "contact_last_name": "Kumar",
  "contact_phones": [{ "phone": "+918000000001", "customer_id": 12345 }],
  "staff_first_name": "Ravi",
  "staff_last_name": "Patel",
  "staff_phone": "+919876543210"
}

Pre-signed URL expiry

cdr_recording_url is valid for 7 days. Download the file (or copy it to your own storage) when you receive the notification — don't store the URL itself for long-term reference.

`CDR_SUMMARY_READY`

Fires when AI processing of a call recording is complete. The payload only carries call-summary data — it does not include contact, task, or staff fields. Use cdr_uuid to correlate with the earlier CDR_RECORDING_AVAILABLE event for the same call.

Field	Type	Description
`cdr_uuid`	string	UUID of the CDR (use this to correlate with `CDR_RECORDING_AVAILABLE`).
`cdr_duration`	number	Talk duration in seconds.
`summary`	object	AI summary object. Present only if summarization is enabled for your account. See Summary object.
`summary_text`	string \| null	Plain-text summary, convenient for direct rendering. `null` when summarization is enabled but produces no text.
`transcription`	object[]	Structured transcription. Present only if transcription is enabled for your account. Empty array when enabled but produces no turns.

Summary object

Field	Type	Description
`insights`	object[]	Structured high-level insights extracted from the conversation. Each item is `{ title: string, value: string }`. Empty array when none are produced.
`summary_text`	string \| null	Same plain-text summary as the top-level `summary_text`. Duplicated here for convenience when consuming only the `summary` object. `null` when no summary text is produced.

Only insights and summary_text are exposed on the summary object — other internal fields produced by the AI pipeline are intentionally stripped before delivery.

{
  "event": "CDR_SUMMARY_READY",
  "superfone_number": "+918000099999",
  "organization_name": "Acme Pvt Ltd",
  "cdr_phone": null,
  "cdr_uuid": "8f4e2a31-2b6d-4c3a-9f1e-7a0b6c2d4e5f",
  "cdr_duration": 142,
  "summary": {
    "insights": [
      { "title": "Callback request", "value": "Customer asked for a callback after 6 PM" },
      { "title": "Main concern", "value": "Pricing for the Pro plan" }
    ],
    "summary_text": "Customer asked for a callback after 6 PM to discuss Pro plan pricing."
  },
  "summary_text": "Customer asked for a callback after 6 PM to discuss Pro plan pricing.",
  "transcription": [
    { "speaker": "agent", "text": "Hi, this is Ravi from Acme.", "start": 0.0, "end": 2.4 },
    { "speaker": "customer", "text": "Hi Ravi, thanks for calling.", "start": 2.5, "end": 4.1 }
  ]
}

`CUSTOMER_CREATE`

Fires when a new lead is created — from any source (manual entry, import, integration webhook, AI agent, etc.). Common envelope + contact fields.

{
  "event": "CUSTOMER_CREATE",
  "superfone_number": "+918000099999",
  "organization_name": "Acme Pvt Ltd",
  "cdr_phone": "+918000000001",
  "contact_id": 12345,
  "contact_first_name": "Asha",
  "contact_last_name": "Kumar",
  "contact_phones": [{ "phone": "+918000000001", "customer_id": 12345 }],
  "contact_source": "website-form",
  "contact_source_type": "OTHERS",
  "contact_lead_stage_id": 9,
  "contact_lead_stage_name": "New Lead",
  "contact_lead_group_id": 3,
  "contact_lead_group_name": "Inbound",
  "contact_labels": [],
  "contact_products": [],
  "contact_assignee_user_id": 678,
  "contact_business_name": "Acme Pvt Ltd",
  "contact_additional_info": null,
  "contact_emails": ["asha@example.com"],
  "contact_custom_fields": {}
}

`CUSTOMER_CHANGE`

Fires when a tracked field on an existing lead changes. Adds updated_key and updated_value describing what changed.

updated_key is one of: first_name, last_name, labels, phones, lead_stage, lead_group, assignee_user, source, source_type, city. For custom fields, updated_key is rewritten to the custom-field's human-readable title.

{
  "event": "CUSTOMER_CHANGE",
  "superfone_number": "+918000099999",
  "organization_name": "Acme Pvt Ltd",
  "updated_key": "lead_stage",
  "updated_value": { "id": 10, "title": "Qualified" },
  "contact_id": 12345,
  "contact_first_name": "Asha",
  "contact_last_name": "Kumar",
  "contact_phones": [{ "phone": "+918000000001", "customer_id": 12345 }],
  "contact_lead_stage_id": 10,
  "contact_lead_stage_name": "Qualified"
}

`TASK_CREATE`

Common envelope + contact fields + task fields.

{
  "event": "TASK_CREATE",
  "superfone_number": "+918000099999",
  "organization_name": "Acme Pvt Ltd",
  "contact_id": 12345,
  "contact_first_name": "Asha",
  "contact_last_name": "Kumar",
  "contact_phones": [{ "phone": "+918000000001", "customer_id": 12345 }],
  "task_id": 4567,
  "task_type": "REMINDER",
  "task_status": "PENDING"
}

`TASK_CHANGE`

Like TASK_CREATE but with updated_key and updated_value. updated_key is one of task_type, task_status, task_due_date.

{
  "event": "TASK_CHANGE",
  "superfone_number": "+918000099999",
  "organization_name": "Acme Pvt Ltd",
  "updated_key": "task_status",
  "updated_value": "COMPLETED",
  "contact_id": 12345,
  "task_id": 4567,
  "task_type": "REMINDER",
  "task_status": "COMPLETED"
}

`TASK_NOTIFY_TIME` and `TASK_DUE_TIME`

Time-driven events that fire when a task's notify or due timestamp is reached. Common envelope + contact fields + task fields.

{
  "event": "TASK_DUE_TIME",
  "superfone_number": "+918000099999",
  "organization_name": "Acme Pvt Ltd",
  "contact_id": 12345,
  "contact_first_name": "Asha",
  "task_id": 4567,
  "task_type": "REMINDER",
  "task_status": "PENDING"
}

Idempotency

Notification deliveries are not idempotency-keyed — Superfone may deliver the same event twice if internal retries / processor restarts occur. Use the IDs in the payload (cdr_id, cdr_uuid, task_id, contact_id) to deduplicate on your side.

Observability

Every notification delivery — including failures — is logged against the action setting in the logs section of Superfone dashboard via our Automations Feature. The activity record contains:

event_payload — The internal event payload that triggered this delivery
body — The exact JSON Superfone sent to your URL
response — Your endpoint's response body (on success) or error (on failure)
group_id_ref — A correlation ID. Quote this when contacting Superfone support about a specific delivery.

Common envelope​

Contact fields​

CDR (call) fields​

cdr_disposition values​

Staff fields​

Task fields​

Per-event extras​

ALL_CALLS and MISSED_CALL​

CDR_RECORDING_AVAILABLE​

CDR_SUMMARY_READY​

Summary object​

CUSTOMER_CREATE​

CUSTOMER_CHANGE​

TASK_CREATE​

TASK_CHANGE​

TASK_NOTIFY_TIME and TASK_DUE_TIME​

Idempotency​

Observability​