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

SMS registration webhooks

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

SMS registration events follow a US SMS registration (10DLC or toll-free) from submission through carrier review. 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
sms.registration.status_updatedA registration changed status; status is the new one.
sms.registration.action_requiredA registration is waiting on its owner; reason says what for.

How it behaves

Every status change fires status_updated

Zernio sends sms.registration.status_updated on each transition: changes_requested (answers are needed), requested (a new submission or resubmission, or your answers are back in review), pending (with the carriers, including after Zernio fixed and resent a rejection), approved (live: attach numbers and send), rejected (the carriers declined it; reason is their words) and deactivated. A carrier rejection needs nothing from you: Zernio handles the fix.

action_required fires only when you must act

reason is changes_requested (answer the points in message with Respond to registration review), otp_required (a sole-proprietor brand must submit the code texted to its mobile with Verify registration OTP) or carrier_info_required (the toll-free carrier asked for more information; the request expires after 7 days). It fires once per new request and once per OTP or carrier request, not on follow-up messages.

The registration is the key, not an account

These events belong to no connected account. registration.id is the registration id and registration.profileId its profile, which is what profile-scoped endpoints filter on.

sms.registration.status_updated

A registration changed status. status is the new status and reason carries the carriers' decline reason on rejected.


Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

Example Requests

POST/sms.registration.status_updated

sms.registration.action_required

A registration is waiting on its owner. message says what to do in words and is absent for otp_required.


Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

Example Requests

POST/sms.registration.action_required

Related

  • Webhooks: create an endpoint, retries, signatures.
  • SMS registration: register a US number for 10DLC or toll-free.
  • Get SMS registration: read status on demand.
  • Phone number webhooks: number provisioning events.
Was this page helpful?

Phone number webhooks

Receive an event at each step of a provisioned number's life, from KYC submission and review to activation, suspension and release.

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 behavesEvery status change fires status_updatedaction_required fires only when you must actThe registration is the key, not an accountsms.registration.status_updatedsms.registration.action_requiredRelated
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?"sms.registration.status_updated"

Value in

  • "sms.registration.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
registration?
status?string

Value in

  • "changes_requested"
  • "requested"
  • "pending"
  • "approved"
  • "rejected"
  • "deactivated"
reason?string

The carriers' decline reason, on rejected.

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?"sms.registration.action_required"

Value in

  • "sms.registration.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
registration?
reason?string

Value in

  • "changes_requested"
  • "otp_required"
  • "carrier_info_required"
message?string

What to do, in words: our request or the carrier's note. Absent for otp_required.