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 |
messageBody | Object | No | Template variable values |
webhookUrl | String | No | URL for status updates |
*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 |