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 all data structures used in the Sent API.
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
Paginated response containing an array of contact objects.
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 (e.g., 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 3) |
definitionVersion | String | Definition schema version (e.g., 1.0) |
Body fields (multiChannel, sms, whatsapp) share the same shape:
| Field | Type | Description |
|---|---|---|
template | String | Message text with variable placeholders (e.g., 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 | variable |
props.variableType | Enum | text |
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? | image |
Button Object
Interactive button used primarily for WhatsApp templates.
| Field | Type | Description |
|---|---|---|
id | Integer | Button identifier |
type | Enum | URL |
props.text | String | Button label |
props.urlType | Enum? | static |
props.url | String? | Destination URL (URL buttons) |
props.countryCode | String? | E.g., +1 (phone buttons) |
props.phoneNumber | String? | Local number (phone buttons) |
props.quickReplyType | String? | custom |
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
Paginated response containing an array of template objects.
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
Message endpoints return 200 OK with a JSON response containing the message ID:
{
"messageId": "8ba7b830-9dad-11d1-80b4-00c04fd430c8"
}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
Status updates sent to the webhook URL when provided.
Webhook Status Values
| Status | Description |
|---|---|
sent | Message accepted by provider |
delivered | Confirmed delivery to device |
read | Message read (WhatsApp only) |
failed | Delivery failed |