API docs by Redocly

Handset API (2026-08-11)

Download OpenAPI specification:

URL: https://docs.handset.dev

Embedded business communications for your platform.

Handset lets your SaaS product provision phone numbers, send compliant two-way SMS, and handle inbound calls (routing, voicemail-to-text, recording) for each of your customers — via API, under your brand.

Object hierarchy

  • Account — you, the platform. Implicit in your API key.
  • Tenant — one of your customers (e.g. "Bob's Plumbing"). Almost every resource belongs to a tenant.
  • Numbers, campaigns, conversations, calls, and usage all hang off tenants.

Conventions

  • IDs are prefixed and opaque: tnt_…, num_…, msg_…, call_….
  • All timestamps are RFC 3339 UTC.
  • List endpoints use cursor pagination (limit, after → next_cursor).
  • Mutating requests accept an Idempotency-Key header; retries with the same key return the original result.
  • Errors carry a machine code, a human message, and a docs_url.

Tenants

Your customers — the businesses whose communications you embed.

Create a tenant

Authorizations:
apiKey
header Parameters
Idempotency-Key
string <= 255 characters

Retries with the same key within 24 h return the original response instead of repeating the action.

Request Body schema: application/json
required
name
required
string

Display name, e.g. the business name.

external_ref
string or null

Your own identifier for this customer.

timezone
string
Default: "America/Phoenix"

IANA timezone; used for business-hours routing.

object (Metadata) <= 20 properties

Your own key–value data, returned unchanged on the object and its events.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "external_ref": "string",
  • "timezone": "America/Phoenix",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "external_ref": "string",
  • "timezone": "America/Phoenix",
  • "metadata": {
    },
  • "id": "tnt_01j8x2z",
  • "created_at": "2019-08-24T14:15:22Z"
}

List tenants

Authorizations:
apiKey
query Parameters
limit
integer [ 1 .. 100 ]
Default: 25
after
string

Cursor from a previous page's next_cursor.

external_ref
string

Filter by your own identifier for the tenant.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "string"
}

Retrieve a tenant

Authorizations:
apiKey
path Parameters
tenant_id
required
string

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "external_ref": "string",
  • "timezone": "America/Phoenix",
  • "metadata": {
    },
  • "id": "tnt_01j8x2z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Update a tenant

Authorizations:
apiKey
path Parameters
tenant_id
required
string
Request Body schema: application/json
required
name
string
external_ref
string or null
timezone
string
object (Metadata) <= 20 properties

Your own key–value data, returned unchanged on the object and its events.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "external_ref": "string",
  • "timezone": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "external_ref": "string",
  • "timezone": "America/Phoenix",
  • "metadata": {
    },
  • "id": "tnt_01j8x2z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Delete a tenant

Releases the tenant's phone numbers and deactivates its campaigns. Message and call history is retained per your data-retention settings.

Authorizations:
apiKey
path Parameters
tenant_id
required
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Phone Numbers

Search, purchase, configure, and release numbers per tenant.

Search purchasable numbers

Authorizations:
apiKey
query Parameters
area_code
string^[0-9]{3}$
locality
string

City name, e.g. Phoenix.

contains
string

Digit pattern the number should contain.

limit
integer [ 1 .. 100 ]
Default: 25

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Purchase a number for a tenant

Authorizations:
apiKey
header Parameters
Idempotency-Key
string <= 255 characters

Retries with the same key within 24 h return the original response instead of repeating the action.

Request Body schema: application/json
required
tenant_id
required
string (TenantIdField)

The tenant this resource belongs to.

phone_number
required
string

E.164 number from a search result.

routing_config_id
string or null

Routing to apply to inbound calls on this number.

campaign_id
string or null

10DLC campaign to attach. Outbound SMS is blocked until the number is attached to an approved campaign.

Responses

Request samples

Content type
application/json
{
  • "tenant_id": "tnt_01j8x2z",
  • "phone_number": "+16025550134",
  • "routing_config_id": "string",
  • "campaign_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "num_01j8x31",
  • "tenant_id": "tnt_01j8x2z",
  • "phone_number": "string",
  • "status": "active",
  • "capabilities": [
    ],
  • "routing_config_id": "string",
  • "campaign_id": "string",
  • "e911_address_id": "string",
  • "messaging_ready": true,
  • "created_at": "2019-08-24T14:15:22Z"
}

List phone numbers

Authorizations:
apiKey
query Parameters
tenant_id
string

Scope results to one tenant.

limit
integer [ 1 .. 100 ]
Default: 25
after
string

Cursor from a previous page's next_cursor.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "string"
}

Retrieve a phone number

Authorizations:
apiKey
path Parameters
number_id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "num_01j8x31",
  • "tenant_id": "tnt_01j8x2z",
  • "phone_number": "string",
  • "status": "active",
  • "capabilities": [
    ],
  • "routing_config_id": "string",
  • "campaign_id": "string",
  • "e911_address_id": "string",
  • "messaging_ready": true,
  • "created_at": "2019-08-24T14:15:22Z"
}

Update routing, campaign, or E911 for a number

Authorizations:
apiKey
path Parameters
number_id
required
string
Request Body schema: application/json
required
routing_config_id
string or null
campaign_id
string or null
e911_address_id
string or null

Responses

Request samples

Content type
application/json
{
  • "routing_config_id": "string",
  • "campaign_id": "string",
  • "e911_address_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "num_01j8x31",
  • "tenant_id": "tnt_01j8x2z",
  • "phone_number": "string",
  • "status": "active",
  • "capabilities": [
    ],
  • "routing_config_id": "string",
  • "campaign_id": "string",
  • "e911_address_id": "string",
  • "messaging_ready": true,
  • "created_at": "2019-08-24T14:15:22Z"
}

Release a phone number

Releases the number back to inventory. Irreversible.

Authorizations:
apiKey
path Parameters
number_id
required
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Messaging

Two-way SMS/MMS with conversation threading and opt-out enforcement.

Send an SMS/MMS

Sends from a tenant-owned number. Fails with campaign_not_approved if the number lacks an approved 10DLC campaign, and with recipient_opted_out if the recipient previously sent STOP.

Authorizations:
apiKey
header Parameters
Idempotency-Key
string <= 255 characters

Retries with the same key within 24 h return the original response instead of repeating the action.

Request Body schema: application/json
required
from
required
string

A tenant number ID (num_…) or its E.164.

to
required
string

Destination in E.164.

body
string <= 1600 characters
media_urls
Array of strings <uri> <= 10 items [ items <uri > ]
object (Metadata) <= 20 properties

Your own key–value data, returned unchanged on the object and its events.

Responses

Request samples

Content type
application/json
{
  • "from": "string",
  • "to": "+14805550199",
  • "body": "string",
  • "media_urls": [],
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "msg_01j8x3a",
  • "tenant_id": "tnt_01j8x2z",
  • "conversation_id": "string",
  • "direction": "inbound",
  • "from": "string",
  • "to": "string",
  • "body": "string",
  • "media_urls": [],
  • "status": "queued",
  • "error_code": "string",
  • "segments": 0,
  • "metadata": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "status_history": [
    ]
}

List messages

Authorizations:
apiKey
query Parameters
tenant_id
string

Scope results to one tenant.

conversation_id
string
direction
string
Enum: "inbound" "outbound"
limit
integer [ 1 .. 100 ]
Default: 25
after
string

Cursor from a previous page's next_cursor.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "string"
}

Retrieve a message

Authorizations:
apiKey
path Parameters
message_id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "msg_01j8x3a",
  • "tenant_id": "tnt_01j8x2z",
  • "conversation_id": "string",
  • "direction": "inbound",
  • "from": "string",
  • "to": "string",
  • "body": "string",
  • "media_urls": [],
  • "status": "queued",
  • "error_code": "string",
  • "segments": 0,
  • "metadata": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "status_history": [
    ]
}

List conversations

A conversation is the thread between one tenant number and one external number, ordered by most recent activity.

Authorizations:
apiKey
query Parameters
tenant_id
string

Scope results to one tenant.

phone_number_id
string
limit
integer [ 1 .. 100 ]
Default: 25
after
string

Cursor from a previous page's next_cursor.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "string"
}

Retrieve a conversation

Authorizations:
apiKey
path Parameters
conversation_id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "cnv_01j8x3f",
  • "tenant_id": "tnt_01j8x2z",
  • "phone_number_id": "string",
  • "external_number": "string",
  • "last_activity_at": "2019-08-24T14:15:22Z",
  • "last_message_preview": "string",
  • "opted_out": true
}

List opted-out recipients

Recipients who sent STOP to a tenant's numbers. Handset blocks sends to them automatically; this endpoint exists so your UI can show why.

Authorizations:
apiKey
query Parameters
tenant_id
string

Scope results to one tenant.

limit
integer [ 1 .. 100 ]
Default: 25
after
string

Cursor from a previous page's next_cursor.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "string"
}

Compliance

10DLC brands and campaigns, E911 addresses.

Register a 10DLC brand

Registers your platform (or a tenant, for tenants with their own EIN) with The Campaign Registry. Vetting typically takes minutes to days; track via brand.status_changed.

Authorizations:
apiKey
header Parameters
Idempotency-Key
string <= 255 characters

Retries with the same key within 24 h return the original response instead of repeating the action.

Request Body schema: application/json
required
legal_name
required
string
dba
string or null
ein
required
string

US tax ID.

entity_type
required
string
Enum: "private_company" "public_company" "non_profit" "sole_proprietor"
website
string or null <uri>
contact_email
required
string <email>
tenant_id
string or null

Set when the brand belongs to a tenant with its own EIN; omit for your platform-level brand.

Responses

Request samples

Content type
application/json
{
  • "legal_name": "string",
  • "dba": "string",
  • "ein": "string",
  • "entity_type": "private_company",
  • "website": "http://example.com",
  • "contact_email": "user@example.com",
  • "tenant_id": "string"
}

Response samples

Content type
application/json
{
  • "legal_name": "string",
  • "dba": "string",
  • "ein": "string",
  • "entity_type": "private_company",
  • "website": "http://example.com",
  • "contact_email": "user@example.com",
  • "tenant_id": "string",
  • "id": "brd_01j8x3k",
  • "status": "pending_vetting",
  • "rejection_reason": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

List brands

Authorizations:
apiKey
query Parameters
limit
integer [ 1 .. 100 ]
Default: 25
after
string

Cursor from a previous page's next_cursor.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "string"
}

Retrieve a brand

Authorizations:
apiKey
path Parameters
brand_id
required
string

Responses

Response samples

Content type
application/json
{
  • "legal_name": "string",
  • "dba": "string",
  • "ein": "string",
  • "entity_type": "private_company",
  • "website": "http://example.com",
  • "contact_email": "user@example.com",
  • "tenant_id": "string",
  • "id": "brd_01j8x3k",
  • "status": "pending_vetting",
  • "rejection_reason": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Register a 10DLC campaign

Registers a messaging use case under an approved brand for a tenant. Carrier review typically takes 1–3 business days; sending is blocked until status is approved. Track via campaign.status_changed.

Authorizations:
apiKey
header Parameters
Idempotency-Key
string <= 255 characters

Retries with the same key within 24 h return the original response instead of repeating the action.

Request Body schema: application/json
required
tenant_id
required
string (TenantIdField)

The tenant this resource belongs to.

brand_id
required
string
use_case
required
string
Enum: "customer_care" "appointment_reminders" "marketing" "two_factor" "mixed"
description
required
string

What the tenant sends and why recipients expect it.

sample_messages
required
Array of strings [ 2 .. 5 ] items
opt_in_description
string

How recipients consent to receive these messages.

Responses

Request samples

Content type
application/json
{
  • "tenant_id": "tnt_01j8x2z",
  • "brand_id": "string",
  • "use_case": "customer_care",
  • "description": "string",
  • "sample_messages": [
    ],
  • "opt_in_description": "string"
}

Response samples

Content type
application/json
{
  • "tenant_id": "tnt_01j8x2z",
  • "brand_id": "string",
  • "use_case": "customer_care",
  • "description": "string",
  • "sample_messages": [
    ],
  • "opt_in_description": "string",
  • "id": "cmp_01j8x3p",
  • "status": "draft",
  • "rejection_reason": "string",
  • "throughput": {
    },
  • "created_at": "2019-08-24T14:15:22Z"
}

List campaigns

Authorizations:
apiKey
query Parameters
tenant_id
string

Scope results to one tenant.

status
string (CampaignStatus)
Enum: "draft" "pending_review" "approved" "rejected" "suspended"
limit
integer [ 1 .. 100 ]
Default: 25
after
string

Cursor from a previous page's next_cursor.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "string"
}

Retrieve a campaign

Authorizations:
apiKey
path Parameters
campaign_id
required
string

Responses

Response samples

Content type
application/json
{
  • "tenant_id": "tnt_01j8x2z",
  • "brand_id": "string",
  • "use_case": "customer_care",
  • "description": "string",
  • "sample_messages": [
    ],
  • "opt_in_description": "string",
  • "id": "cmp_01j8x3p",
  • "status": "draft",
  • "rejection_reason": "string",
  • "throughput": {
    },
  • "created_at": "2019-08-24T14:15:22Z"
}

Validate and register an E911 address

Validates a dispatchable location and registers it for use with a tenant's numbers. Returns e911_address_invalid with correction suggestions when validation fails.

Authorizations:
apiKey
header Parameters
Idempotency-Key
string <= 255 characters

Retries with the same key within 24 h return the original response instead of repeating the action.

Request Body schema: application/json
required
tenant_id
required
string (TenantIdField)

The tenant this resource belongs to.

street
required
string
unit
string or null
city
required
string
state
required
string = 2 characters
postal_code
required
string

Responses

Request samples

Content type
application/json
{
  • "tenant_id": "tnt_01j8x2z",
  • "street": "123 N Central Ave",
  • "unit": "Suite 400",
  • "city": "string",
  • "state": "st",
  • "postal_code": "string"
}

Response samples

Content type
application/json
{
  • "tenant_id": "tnt_01j8x2z",
  • "street": "123 N Central Ave",
  • "unit": "Suite 400",
  • "city": "string",
  • "state": "st",
  • "postal_code": "string",
  • "id": "e911_01j8x3t",
  • "status": "validated",
  • "created_at": "2019-08-24T14:15:22Z"
}

List E911 addresses

Authorizations:
apiKey
query Parameters
tenant_id
string

Scope results to one tenant.

limit
integer [ 1 .. 100 ]
Default: 25
after
string

Cursor from a previous page's next_cursor.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "string"
}

Voice

Inbound call records, routing configuration, voicemail, recordings.

Create a routing config

Authorizations:
apiKey
header Parameters
Idempotency-Key
string <= 255 characters

Retries with the same key within 24 h return the original response instead of repeating the action.

Request Body schema: application/json
required
tenant_id
required
string (TenantIdField)

The tenant this resource belongs to.

name
required
string
object or null

Weekly schedule in the tenant's timezone. Omit for 24/7 open_behavior.

required
object (RingBehavior)
VoicemailBehavior (object) or RingBehavior (object)

Applied outside business hours. Defaults to voicemail.

object

Responses

Request samples

Content type
application/json
{
  • "tenant_id": "tnt_01j8x2z",
  • "name": "Main line",
  • "business_hours": {
    },
  • "open_behavior": {
    },
  • "closed_behavior": {
    },
  • "recording": {
    }
}

Response samples

Content type
application/json
{
  • "tenant_id": "tnt_01j8x2z",
  • "name": "Main line",
  • "business_hours": {
    },
  • "open_behavior": {
    },
  • "closed_behavior": {
    },
  • "recording": {
    },
  • "id": "rtc_01j8x3w",
  • "created_at": "2019-08-24T14:15:22Z"
}

List routing configs

Authorizations:
apiKey
query Parameters
tenant_id
string

Scope results to one tenant.

limit
integer [ 1 .. 100 ]
Default: 25
after
string

Cursor from a previous page's next_cursor.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "string"
}

Retrieve a routing config

Authorizations:
apiKey
path Parameters
routing_config_id
required
string

Responses

Response samples

Content type
application/json
{
  • "tenant_id": "tnt_01j8x2z",
  • "name": "Main line",
  • "business_hours": {
    },
  • "open_behavior": {
    },
  • "closed_behavior": {
    },
  • "recording": {
    },
  • "id": "rtc_01j8x3w",
  • "created_at": "2019-08-24T14:15:22Z"
}

Update a routing config

Changes apply to new calls immediately.

Authorizations:
apiKey
path Parameters
routing_config_id
required
string
Request Body schema: application/json
required
tenant_id
required
string (TenantIdField)

The tenant this resource belongs to.

name
required
string
object or null

Weekly schedule in the tenant's timezone. Omit for 24/7 open_behavior.

required
object (RingBehavior)
VoicemailBehavior (object) or RingBehavior (object)

Applied outside business hours. Defaults to voicemail.

object

Responses

Request samples

Content type
application/json
{
  • "tenant_id": "tnt_01j8x2z",
  • "name": "Main line",
  • "business_hours": {
    },
  • "open_behavior": {
    },
  • "closed_behavior": {
    },
  • "recording": {
    }
}

Response samples

Content type
application/json
{
  • "tenant_id": "tnt_01j8x2z",
  • "name": "Main line",
  • "business_hours": {
    },
  • "open_behavior": {
    },
  • "closed_behavior": {
    },
  • "recording": {
    },
  • "id": "rtc_01j8x3w",
  • "created_at": "2019-08-24T14:15:22Z"
}

Delete a routing config

Fails with routing_config_in_use if any number references it.

Authorizations:
apiKey
path Parameters
routing_config_id
required
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

List calls

Authorizations:
apiKey
query Parameters
tenant_id
string

Scope results to one tenant.

phone_number_id
string
limit
integer [ 1 .. 100 ]
Default: 25
after
string

Cursor from a previous page's next_cursor.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "string"
}

Retrieve a call

Authorizations:
apiKey
path Parameters
call_id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "call_01j8x42",
  • "tenant_id": "tnt_01j8x2z",
  • "phone_number_id": "string",
  • "direction": "inbound",
  • "from": "string",
  • "to": "string",
  • "status": "ringing",
  • "answered_by": "string",
  • "duration_seconds": 0,
  • "recording_id": "string",
  • "voicemail_id": "string",
  • "started_at": "2019-08-24T14:15:22Z",
  • "ended_at": "2019-08-24T14:15:22Z",
  • "events": [
    ]
}

List voicemails

Authorizations:
apiKey
query Parameters
tenant_id
string

Scope results to one tenant.

limit
integer [ 1 .. 100 ]
Default: 25
after
string

Cursor from a previous page's next_cursor.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "string"
}

Retrieve a voicemail

Authorizations:
apiKey
path Parameters
voicemail_id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "vm_01j8x45",
  • "tenant_id": "tnt_01j8x2z",
  • "call_id": "string",
  • "from": "string",
  • "duration_seconds": 0,
  • "transcript": "string",
  • "audio_url": "http://example.com",
  • "created_at": "2019-08-24T14:15:22Z"
}

Retrieve a call recording

Authorizations:
apiKey
path Parameters
recording_id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "rec_01j8x48",
  • "tenant_id": "tnt_01j8x2z",
  • "call_id": "string",
  • "duration_seconds": 0,
  • "consent_announced": true,
  • "audio_url": "http://example.com",
  • "created_at": "2019-08-24T14:15:22Z"
}

Webhooks

Manage endpoints that receive signed Handset events.

Create a webhook endpoint

Authorizations:
apiKey
header Parameters
Idempotency-Key
string <= 255 characters

Retries with the same key within 24 h return the original response instead of repeating the action.

Request Body schema: application/json
required
url
required
string <uri>
enabled_events
Array of strings

Event types to deliver; omit for all.

description
string or null

Responses

Request samples

Content type
application/json
{
  • "url": "http://example.com",
  • "enabled_events": [
    ],
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "url": "http://example.com",
  • "enabled_events": [
    ],
  • "description": "string",
  • "id": "whe_01j8x4b",
  • "status": "active",
  • "created_at": "2019-08-24T14:15:22Z",
  • "secret": "string"
}

List webhook endpoints

Authorizations:
apiKey
query Parameters
limit
integer [ 1 .. 100 ]
Default: 25
after
string

Cursor from a previous page's next_cursor.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "string"
}

Update a webhook endpoint

Authorizations:
apiKey
path Parameters
endpoint_id
required
string
Request Body schema: application/json
required
url
required
string <uri>
enabled_events
Array of strings

Event types to deliver; omit for all.

description
string or null

Responses

Request samples

Content type
application/json
{
  • "url": "http://example.com",
  • "enabled_events": [
    ],
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "url": "http://example.com",
  • "enabled_events": [
    ],
  • "description": "string",
  • "id": "whe_01j8x4b",
  • "status": "active",
  • "created_at": "2019-08-24T14:15:22Z"
}

Delete a webhook endpoint

Authorizations:
apiKey
path Parameters
endpoint_id
required
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Send a test event

Authorizations:
apiKey
path Parameters
endpoint_id
required
string
Request Body schema: application/json
event_type
string
Default: "message.received"

Responses

Request samples

Content type
application/json
{
  • "event_type": "message.received"
}

Response samples

Content type
application/json
{
  • "delivered": true,
  • "response_status": 0,
  • "error": "string"
}

An inbound SMS/MMS arrived at a tenant number. Webhook

Authorizations:
apiKey
Request Body schema: application/json
id
required
string
type
required
string
event_version
required
string
created_at
required
string <date-time>
tenant_id
string (TenantIdField)

The tenant this resource belongs to.

data
required
object

The full affected resource (Message, Call, Voicemail, …).

Responses

Request samples

Content type
application/json
{
  • "id": "evt_01j8x4e",
  • "type": "message.received",
  • "event_version": "2026-08-11",
  • "created_at": "2019-08-24T14:15:22Z",
  • "tenant_id": "tnt_01j8x2z",
  • "data": { }
}

An outbound message reached the recipient's carrier as delivered. Webhook

Authorizations:
apiKey
Request Body schema: application/json
id
required
string
type
required
string
event_version
required
string
created_at
required
string <date-time>
tenant_id
string (TenantIdField)

The tenant this resource belongs to.

data
required
object

The full affected resource (Message, Call, Voicemail, …).

Responses

Request samples

Content type
application/json
{
  • "id": "evt_01j8x4e",
  • "type": "message.received",
  • "event_version": "2026-08-11",
  • "created_at": "2019-08-24T14:15:22Z",
  • "tenant_id": "tnt_01j8x2z",
  • "data": { }
}

An outbound message failed (carrier rejection, filtering, etc.). Webhook

Authorizations:
apiKey
Request Body schema: application/json
id
required
string
type
required
string
event_version
required
string
created_at
required
string <date-time>
tenant_id
string (TenantIdField)

The tenant this resource belongs to.

data
required
object

The full affected resource (Message, Call, Voicemail, …).

Responses

Request samples

Content type
application/json
{
  • "id": "evt_01j8x4e",
  • "type": "message.received",
  • "event_version": "2026-08-11",
  • "created_at": "2019-08-24T14:15:22Z",
  • "tenant_id": "tnt_01j8x2z",
  • "data": { }
}

An inbound call began on a tenant number. Webhook

Authorizations:
apiKey
Request Body schema: application/json
id
required
string
type
required
string
event_version
required
string
created_at
required
string <date-time>
tenant_id
string (TenantIdField)

The tenant this resource belongs to.

data
required
object

The full affected resource (Message, Call, Voicemail, …).

Responses

Request samples

Content type
application/json
{
  • "id": "evt_01j8x4e",
  • "type": "message.received",
  • "event_version": "2026-08-11",
  • "created_at": "2019-08-24T14:15:22Z",
  • "tenant_id": "tnt_01j8x2z",
  • "data": { }
}

A call ended; includes outcome and duration. Webhook

Authorizations:
apiKey
Request Body schema: application/json
id
required
string
type
required
string
event_version
required
string
created_at
required
string <date-time>
tenant_id
string (TenantIdField)

The tenant this resource belongs to.

data
required
object

The full affected resource (Message, Call, Voicemail, …).

Responses

Request samples

Content type
application/json
{
  • "id": "evt_01j8x4e",
  • "type": "message.received",
  • "event_version": "2026-08-11",
  • "created_at": "2019-08-24T14:15:22Z",
  • "tenant_id": "tnt_01j8x2z",
  • "data": { }
}

A voicemail was recorded; transcript follows when ready. Webhook

Authorizations:
apiKey
Request Body schema: application/json
id
required
string
type
required
string
event_version
required
string
created_at
required
string <date-time>
tenant_id
string (TenantIdField)

The tenant this resource belongs to.

data
required
object

The full affected resource (Message, Call, Voicemail, …).

Responses

Request samples

Content type
application/json
{
  • "id": "evt_01j8x4e",
  • "type": "message.received",
  • "event_version": "2026-08-11",
  • "created_at": "2019-08-24T14:15:22Z",
  • "tenant_id": "tnt_01j8x2z",
  • "data": { }
}

A call recording is stored and available. Webhook

Authorizations:
apiKey
Request Body schema: application/json
id
required
string
type
required
string
event_version
required
string
created_at
required
string <date-time>
tenant_id
string (TenantIdField)

The tenant this resource belongs to.

data
required
object

The full affected resource (Message, Call, Voicemail, …).

Responses

Request samples

Content type
application/json
{
  • "id": "evt_01j8x4e",
  • "type": "message.received",
  • "event_version": "2026-08-11",
  • "created_at": "2019-08-24T14:15:22Z",
  • "tenant_id": "tnt_01j8x2z",
  • "data": { }
}

A 10DLC brand moved through vetting. Webhook

Authorizations:
apiKey
Request Body schema: application/json
id
required
string
type
required
string
event_version
required
string
created_at
required
string <date-time>
tenant_id
string (TenantIdField)

The tenant this resource belongs to.

data
required
object

The full affected resource (Message, Call, Voicemail, …).

Responses

Request samples

Content type
application/json
{
  • "id": "evt_01j8x4e",
  • "type": "message.received",
  • "event_version": "2026-08-11",
  • "created_at": "2019-08-24T14:15:22Z",
  • "tenant_id": "tnt_01j8x2z",
  • "data": { }
}

A 10DLC campaign moved through carrier review. Webhook

Authorizations:
apiKey
Request Body schema: application/json
id
required
string
type
required
string
event_version
required
string
created_at
required
string <date-time>
tenant_id
string (TenantIdField)

The tenant this resource belongs to.

data
required
object

The full affected resource (Message, Call, Voicemail, …).

Responses

Request samples

Content type
application/json
{
  • "id": "evt_01j8x4e",
  • "type": "message.received",
  • "event_version": "2026-08-11",
  • "created_at": "2019-08-24T14:15:22Z",
  • "tenant_id": "tnt_01j8x2z",
  • "data": { }
}

Usage

Usage summary

Totals the account's billable usage by kind over [start, end) for the key's mode. Live and test ledgers are separate; only live usage is invoiced.

Authorizations:
apiKey
query Parameters
start
string

RFC 3339 timestamp or YYYY-MM-DD. Defaults to the first instant of the current month.

end
string

RFC 3339 timestamp or YYYY-MM-DD. Defaults to now.

tenant_id
string

Scope results to one tenant.

Responses

Response samples

Content type
application/json
{
  • "object": "usage_summary",
  • "mode": "live",
  • "start": "2019-08-24T14:15:22Z",
  • "end": "2019-08-24T14:15:22Z",
  • "data": [
    ]
}