Legacy API Notice: This documentation covers the Legacy Sent API (v2). For new integrations, please refer to the latest Sent API v3 Data Models.
Data Models
Complete reference for the data structures used in the legacy Sent API v2.
Contact Models
Contact Object
The contact object represents a phone number with its various formats and available messaging channels.
| Field | Type | Description |
|---|---|---|
id | UUID | Unique contact identifier |
phoneNumber | String | Phone number as originally provided |
formatE164 | String | E.164 international format |
formatInternational | String | Human-readable international format |
formatNational | String | National format for the country |
formatRfc | String | RFC 3966 tel: URI format |
countryCode | String | Country calling code |
regionCode | String | ISO 3166-1 alpha-2 country code |
availableChannels | String | Comma-separated available channels |
defaultChannel | String | Recommended messaging channel |
Contact List Response
GET /v2/contacts returns the pagination wrapper with each entry in items being a Contact object:
{
"items": [
{
"id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"phoneNumber": "+1234567890",
"formatE164": "+1234567890",
"formatInternational": "+1 234-567-890",
"formatNational": "(234) 567-890",
"formatRfc": "tel:+1-234-567-890",
"countryCode": "1",
"regionCode": "US",
"availableChannels": "sms,whatsapp",
"defaultChannel": "sms"
}
],
"totalCount": 150,
"page": 0,
"pageSize": 20,
"totalPages": 8
}Template Models
Template Object
Message templates for multi-channel messaging (SMS, WhatsApp).
| Field | Type | Description |
|---|---|---|
id | UUID | Unique template identifier |
displayName | String | Human-readable template name |
category | Enum | Template category (see below) |
language | ISO Code | Language/locale (for example, en_US) |
definition | Object | Template Definition object (see below) |
status | Enum | Template status (see below) |
isPublished | Boolean | Whether template is published for use |
whatsappTemplateId | String | WhatsApp internal template ID (when applicable) |
whatsappTemplateName | String | WhatsApp internal template name (when applicable) |
createdAt | DateTime | ISO 8601 creation timestamp |
updatedAt | DateTime | ISO 8601 last update timestamp |
Template Definition Object
Defines the content and components of a template, including channel-specific bodies and interactive elements.
| Field | Type | Description |
|---|---|---|
header | Object? | Optional header; supports type and template, with variables |
body | Object | Message body definitions: supports multiChannel, sms, and whatsapp |
footer | Object? | Optional footer with type and template |
buttons | Array<Button> | Optional interactive buttons (max 10, WhatsApp limit; per type: 1 COPY_CODE, 1 PHONE_NUMBER, 2 URL, 10 QUICK_REPLY) |
definitionVersion | String | Definition schema version (for example, 1.0) |
Body fields (multiChannel, sms, whatsapp) share the same shape:
| Field | Type | Description |
|---|---|---|
template | String | Message text with variable placeholders (for example, Hello {{1:name}}) |
variables | Array<Variable> | Variables referenced in the template |
Variable Object
Represents a dynamic placeholder used in headers and bodies.
| Field | Type | Description |
|---|---|---|
id | Integer | Sequential variable ID starting from 1 |
name | String | Readable variable name |
type | Enum | One of variable, link, media |
props.variableType | Enum | One of text, link, image, file |
props.sample | String | Sample value for approval and previews |
props.url | String? | Full URL (for link/media) |
props.shortUrl | String? | Shortened URL (optional) |
props.alt | String? | Alternative text (media) |
props.mediaType | Enum? | One of image, video, document (media only) |
Button Object
Interactive button used primarily for WhatsApp templates.
| Field | Type | Description |
|---|---|---|
id | Integer | Button identifier |
type | Enum | One of URL, PHONE_NUMBER, QUICK_REPLY, VOICE_CALL, COPY_CODE |
props.text | String | Button label |
props.urlType | Enum? | One of static, dynamic (URL buttons) |
props.url | String? | Destination URL (URL buttons) |
props.countryCode | String? | For example, +1 (phone buttons) |
props.phoneNumber | String? | Local number (phone buttons) |
props.quickReplyType | String? | One of custom, pre-configured (quick reply) |
props.activeFor | Integer? | Active window in seconds (voice call) |
props.offerCode | String? | Code to copy (copy code) |
Template Categories
| Category | Description | Use Cases |
|---|---|---|
AUTHENTICATION | OTP and verification | 2FA, login codes |
MARKETING | Promotional content | Campaigns, offers |
UTILITY | Transactional messages | Confirmations, updates |
Template Status Values
| Status | Description |
|---|---|
DRAFT | Not submitted for review |
PENDING | Under review |
APPROVED | Approved for use |
REJECTED | Rejected and cannot be used |
PAUSED | Temporarily disabled |
ARCHIVED | Archived and not in active use |
Template List Response
GET /v2/templates returns the pagination wrapper with each entry in items being a Template object.
Message Models
Send Message Request
Request payload for sending messages via contact ID or phone number.
| Field | Type | Required | Description |
|---|---|---|---|
contactId | UUID | Yes* | Contact ID (for contact endpoint) |
phoneNumber | String | Yes* | Phone number (for phone endpoint) |
templateId | UUID | Yes | Template to use |
templateVariables | Object | No | Template variable values |
*One of contactId or phoneNumber is required depending on endpoint
Message Response
POST /v2/messages/phone and POST /v2/messages/contact return 202 Accepted with the ID of the queued message:
{
"messageId": "8ba7b830-9dad-11d1-80b4-00c04fd430c8"
}POST /v2/messages/quick-message returns 200 OK with one message ID per channel; whatsappMessageId is null when the number is not WhatsApp-capable:
{
"smsMessageId": "8ba7b830-9dad-11d1-80b4-00c04fd430c8",
"whatsappMessageId": "8ba7b830-9dad-11d1-80b4-00c04fd430c9"
}Pagination Model
Standard pagination structure used by list endpoints.
| Field | Type | Description |
|---|---|---|
items | Array | List of objects |
totalCount | Integer | Total items available |
page | Integer | Current page (0-based) |
pageSize | Integer | Items per page |
totalPages | Integer | Total pages available |
Channel Types
| Channel | Description |
|---|---|
sms | Traditional SMS messaging |
whatsapp | WhatsApp Business messaging |
Phone Number Formats
The API accepts various phone number formats and normalizes them:
| Format | Example | Description |
|---|---|---|
| E.164 | +1234567890 | International format (recommended) |
| International | +1 234-567-890 | With formatting |
| National | (234) 567-890 | Country-specific format |
| IDD Prefix | 0011234567890 | International dialing |
| Raw | 1234567890 | Digits only (requires context) |
Webhook Payload
Delivery status updates are not returned by v2 endpoints. They are delivered as events to the webhook endpoints registered for your account, using the platform-wide envelope:
| Field | Type | Description |
|---|---|---|
field | String | Parent event type; message for status updates |
event | String | Granular sub-type, for example message.delivered |
timestamp | String | ISO 8601 timestamp of event creation |
payload | Object | Event-specific data (see below) |
For message status events, payload contains:
| Field | Type | Description |
|---|---|---|
updated_at | String | ISO 8601 timestamp of the status change |
account_id | UUID | Your account identifier |
message_id | UUID | The message ID returned by the send endpoint |
template_id | UUID | Template used for the message |
template_name | String | Template display name |
outbound_number | String | Sending phone number |
message_status | String | Message status (see below) |
channel | String | sms or whatsapp |
Example event:
{
"field": "message",
"event": "message.delivered",
"timestamp": "2025-10-31T10:10:42Z",
"payload": {
"updated_at": "2025-10-31T10:10:41Z",
"account_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
"message_id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8",
"template_id": "9ba7b840-9dad-11d1-80b4-00c04fd430c8",
"template_name": "order_confirmation",
"outbound_number": "+1987654321",
"message_status": "DELIVERED",
"channel": "sms"
}
}Webhook Status Values
| Status | Event | Description |
|---|---|---|
QUEUED | message.queued | Message accepted and waiting to be dispatched |
ROUTED | message.routed | Message assigned to a carrier or provider |
SENT | message.sent | Message sent to carrier or WhatsApp |
DELIVERED | message.delivered | Message delivered to recipient's device |
READ | message.read | Message read by recipient (WhatsApp and RCS) |
FAILED | message.failed | Message delivery failed permanently |
SCHEDULED | message.scheduled | Message deferred until the recipient's quiet hours end |
FILTERED | message.filtered | Message suppressed by a policy gate; not dispatched |
BLOCKED | message.blocked | Message gated by an account-level precondition; not dispatched |
The full event catalog, including inbound message and template events, signature verification, and retry behavior, is documented in the webhook events reference.
Authentication
How to authenticate Legacy Sent API (v2) requests with the x-sender-id and x-api-key headers, plus credential setup, 401 error responses, and key management.
Error Reference
HTTP status codes and the problem-details error response format returned by the legacy Sent API v2, with example JSON error payloads for each status code.