Zernio
Zernio
OverviewWebhooksPost webhooksInbox webhooksAccount webhooksAnalytics webhooksAds webhooksCall webhooksWhatsApp webhooksPhone number webhooksSMS registration webhooksBranded Calling webhooks
Dashboard
llms.txtOpenAPI
OverviewPlatformsAPI ReferenceResources
Webhooks

Branded Calling webhooks

Follow a caller identity from Zernio review through the authorizer's code and carrier vetting to verified, and each attached number's own vetting.

Branded Calling events follow a caller identity and its numbers. Subscribe with POST /v1/webhooks/settings and the event names below (first event); delivery, retries and signatures are the same for every event (how webhooks behave).

Events

EventDescription
branded_calling.identity.status_updatedThe identity changed status: review, filing, carrier vetting, verified, or a rejection, suspension or expiry.
branded_calling.identity.action_requiredThe identity waits on you: answer a change request, confirm the authorizer's code, fix a rejection, or read an open claim.
branded_calling.number.status_updatedA number attached to the identity changed vetting status.

How it behaves

Events fire on status transitions

status_updated fires once per transition of the identity's status (the same value GET /v1/branded-calling/identities/{id} returns), never on a re-check that found nothing new. Zernio polls the carrier every 15 minutes while an identity or a batch of numbers is being vetted, so a carrier decision reaches you within that window.

action_required is the subset that needs you

Every action_required is paired with a status_updated. Its reason says what to do: changes_requested (answer the review points with PATCH), email_code (confirm the code the carrier emailed to the authorizer), rejected (fix the fields and PATCH to resubmit), infringement_claim (a trademark or impersonation claim paused the identity; nothing to do on your side while it is open), expired (the yearly renewal failed; edit and resubmit).

Numbers are vetted after the identity

Number events only start once the identity is verified and you attached numbers. A batch is vetted as a unit, and each number reports its own status: submitted, in_review, verified, unsuccessful, suspended, expired or permanently_rejected.

branded_calling.identity.status_updated


Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

Example Requests

POST/branded_calling.identity.status_updated

branded_calling.identity.action_required


Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

Example Requests

POST/branded_calling.identity.action_required

branded_calling.number.status_updated


Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

Example Requests

POST/branded_calling.number.status_updated

Related

  • Branded Calling: the whole flow, with every status.
  • Call webhooks: the calls that carry the identity.
  • Phone number webhooks: the number's own lifecycle.
Was this page helpful?

SMS registration webhooks

Receive an event when a US SMS registration changes status or starts waiting on you, instead of polling it.

Workflows

Create and activate a workflow with POST /v1/workflows so inbound DMs on one account run a graph of messages, waits, conditions and handoffs.

On this page

EventsHow it behavesEvents fire on status transitionsaction_required is the subset that needs youNumbers are vetted after the identitybranded_calling.identity.status_updatedbranded_calling.identity.action_requiredbranded_calling.number.status_updatedRelated
id?string

Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource.

event?"branded_calling.identity.status_updated"

Value in

  • "branded_calling.identity.status_updated"
timestamp?string

UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.

Formatdate-time
identity?
status?string

Value in

  • "requested"
  • "changes_requested"
  • "rejected"
  • "pending_email_verification"
  • "in_review"
  • "verified"
  • "suspended"
  • "expired"
  • "permanently_rejected"
reason?string

Our review note, or the carrier's rejection reasons, when there is one.

id?string

Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource.

event?"branded_calling.identity.action_required"

Value in

  • "branded_calling.identity.action_required"
timestamp?string

UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.

Formatdate-time
identity?
reason?string

Value in

  • "changes_requested"
  • "email_code"
  • "rejected"
  • "infringement_claim"
  • "expired"
message?string

What to do, in words.

id?string

Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource.

event?"branded_calling.number.status_updated"

Value in

  • "branded_calling.number.status_updated"
timestamp?string

UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.

Formatdate-time
identity?
number?
reason?string

The carrier's rejection detail, when the number was refused.