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_uuid`	string \| null	UUID of the CDR. Use this to correlate `ALL_CALLS`/`MISSED_CALL`/`CDR_RECORDING_AVAILABLE` with the later `CDR_SUMMARY_READY` event for the same call.
`cdr_request_uuid`	string \| null	Correlation ID of the API request that originated the call, when the call was placed via the Calls API. Only present for outbound calls placed that way — `null` for inbound calls and calls placed any other way.
`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.

For a call that went through an IVR menu (inbound, or an outbound IVR campaign call), the CDR fields also include ivr_inputs and dtmf_digits — see the IVR-driven example below.

{
  "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_uuid": "8f4e2a31-2b6d-4c3a-9f1e-7a0b6c2d4e5f",
  "cdr_request_uuid": null,
  "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"
}

Example: IVR-driven call

An inbound IVR call, or an outbound IVR campaign call. ivr_inputs and dtmf_digits are only present when the call actually went through an IVR menu — omitted entirely otherwise (not null, not an empty array).

{
  "event": "ALL_CALLS",
  "superfone_number": "+918000099999",
  "organization_name": "Acme Pvt Ltd",
  "cdr_phone": "+918000000001",
  "cdr_id": 9876544,
  "cdr_uuid": "3af9c210-88e4-4b7a-9d0e-1c2f3a4b5c6d",
  "cdr_request_uuid": "ivr_ob_req_a1b2c3d4e5f6",
  "cdr_disposition": "ANSWER",
  "cdr_duration": 12,
  "cdr_call_type": "OUTBOUND",
  "cdr_start": "2026-09-08T16:09:06.000Z",
  "cdr_answer": "2026-09-08T16:09:33.000Z",
  "cdr_end": "2026-09-08T16:09:45.000Z",
  "cdr_ringing_duration": 27,
  "ivr_inputs": [
    {
      "greetingText": "Thanks for calling! Press 1 to speak with sales, or press 2 for tech",
      "playbackText": "Intro",
      "userPressedKey": "1"
    },
    {
      "greetingText": "You've reached the Sales team. Press 1 for new customer or press 2 for old customers,
      "playbackText": "Sales",
      "userPressedKey": "2"
    }
  ],
  "dtmf_digits": ["1","2"],
  "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"
}

`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.
`cdr_recording_url_expires_at`	string	ISO 8601 timestamp — when `cdr_recording_url` stops working. Always check this field rather than assuming a fixed window (see warning below).
`cdr_recording_status`	string	Always `OK` (the notification only fires on successful uploads).
`cdr_recording_expire_at`	string \| null	ISO 8601 timestamp — when the recording itself is permanently deleted from Superfone. Distinct from `cdr_recording_url_expires_at` (see warning below). `null` if not set.

{
  "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_url_expires_at": "2026-05-22T10:32:30.000Z",
  "cdr_recording_status": "OK",
  "cdr_recording_expire_at": "2026-06-14T10:32:30.000Z",
  "cdr_id": 9876543,
  "cdr_uuid": "8f4e2a31-2b6d-4c3a-9f1e-7a0b6c2d4e5f",
  "cdr_request_uuid": null,
  "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"
}

cdr_recording_url_expires_at vs. cdr_recording_expire_at

These are two different deadlines — don't confuse them:

cdr_recording_url_expires_at — when this specific pre-signed link stops working. Usually 7 days out, but capped earlier if the recording itself expires sooner.
cdr_recording_expire_at — when the recording itself is permanently deleted from Superfone (30 days from the call by default, configurable per number). This is the real deadline; cdr_recording_url_expires_at is never later than it.

If cdr_request_uuid is populated (the call was placed via the SFVoPI outbound calling API), you can re-fetch a fresh link any time before cdr_recording_expire_at by calling Get Call Info with that value. For calls without a cdr_request_uuid (the common case for regular inbound/outbound calls not placed through that API), there's currently no public endpoint to re-fetch the link once it expires — so treat cdr_recording_url_expires_at as your real deadline in that case.

Either way, don't rely on re-fetching: download the file (or copy it to your own storage) as soon as you receive the notification rather than storing the URL for later use. If you need a longer retention window for your account, contact Superfone support to ask whether that's possible.

cdr_disposition, cdr_duration, and cdr_end are not guaranteed on this event

A recording finishing upload and a call finishing its hangup processing are two independent, asynchronous operations. CDR_RECORDING_AVAILABLE can, in rare cases, be delivered before the call's hangup processing has completed. When that happens:

cdr_disposition may read ACTIVE (the in-progress state) instead of the eventual terminal outcome (ANSWER, BUSY, NOANSWER, etc.)
cdr_duration may read 0 instead of the real talk duration
cdr_end may be null instead of the call's actual end time

Every other field on this event — cdr_recording_url, cdr_recording_status, cdr_answer, cdr_start, cdr_call_type, cdr_ringing_duration, and all contact_*/staff_* fields — is unaffected and always reliable here.

If your integration needs the confirmed outcome or duration, don't read it off CDR_RECORDING_AVAILABLE. Correlate by cdr_uuid with the ALL_CALLS (or MISSED_CALL) event for the same call — those always carry the finalized values, since they only ever fire once hangup processing is complete.

`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_request_uuid`	string \| null	Correlation ID of the API request that originated the call, when the call was placed via the Calls API. Only present for outbound calls placed that way — `null` for inbound calls and calls placed any other way.
`cdr_duration`	number	Talk duration in seconds.
`summary`	object	AI summary object. Present only if summarization is enabled for your account and has completed for this call. See Summary object.
`summary_text`	string \| null	Plain-text summary, convenient for direct rendering. `null` when summarization is enabled but produces no text.

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_request_uuid": null,
  "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."
}

`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​

Example: IVR-driven 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​