Data Models

Every Sent API v3 response uses the same JSON envelope. This page documents the shared structures: the response envelope, its error and metadata objects, and the pagination metadata returned by list endpoints. Request and response schemas for individual resources are generated from the OpenAPI specification and rendered on each endpoint page. See Resource schemas.

Response Envelope

All v3 endpoints return the standard ApiResponse envelope:

Example Success Response

{
  "success": true,
  "data": {
    "id": "0b9df168-9917-4b1e-bc5d-9cee5d2ce2d2",
    "phone_number": "+15551234567",
    "created_at": "2026-01-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-01-15T10:30:00Z",
    "version": "v3"
  }
}

Example Error Response

{
  "success": false,
  "status": 404,
  "error": {
    "code": "RESOURCE_001",
    "message": "Contact not found",
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_def456",
    "timestamp": "2026-01-15T10:30:00Z",
    "version": "v3"
  }
}

Error Handling documents HTTP status codes and error response semantics; the Error Catalog enumerates every error code with causes and remediation.

ApiError

ApiMeta

Paginated List Responses

Paginated list endpoints return the items array and a pagination object inside data. The array property is named after the resource:

Paginated endpoints accept the page query parameter (1-indexed, default 1) and the page_size query parameter (default 20, range 1–100).

Example Paginated Response

{
  "success": true,
  "data": {
    "contacts": [
      {
        "id": "0b9df168-9917-4b1e-bc5d-9cee5d2ce2d2",
        "phone_number": "+15551234567"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_count": 42,
      "total_pages": 3,
      "has_more": true,
      "cursors": null
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-01-15T10:30:00Z",
    "version": "v3"
  }
}

PaginationMeta

PaginationCursors

Resource Schemas

Request and response schemas for each resource are generated from the OpenAPI specification and rendered on the endpoint pages. Each mutation endpoint page documents its own request body; the pages below document the full response model for each resource:

Message Status Values

The generated schema types the status field on MessageResponse as a plain string, so the endpoint page does not enumerate its values.

QUEUED, ROUTED, SENT, DELIVERED, READ, and FAILED cover the outbound lifecycle, and RECEIVED marks an inbound message from a contact. Four more statuses describe a send that was held, called off, or suppressed:

• SCHEDULED: the send is held for a future instant, either a scheduled_at you set or the end of the recipient's quiet hours. Sent releases the message automatically once that instant arrives and it continues through the normal send path, so SCHEDULED is not terminal.
• CANCELLED: you called a held send off with POST /v3/messages/{id}/cancel before it was released. Reachable only from SCHEDULED, terminal, and never sent. See Cancelling scheduled messages.
• FILTERED: a policy gate suppressed the send before any provider call, either because the recipient opted out or is on your phone-channel suppression list, or because your routing rules denied it.
• BLOCKED: an account-level precondition stopped the send before policy evaluation, for example an insufficient balance, an unmet onboarding entitlement, or a template that is not approved for sending.

FILTERED, BLOCKED, and CANCELLED are policy or customer outcomes rather than delivery failures, so all three are excluded from your deliverability rate. Only FAILED counts against it.

A message that is or was held reports its instant in scheduled_at, which GET /v3/messages/{id} returns alongside the base MessageResponse fields, and which message.scheduled and message.cancelled also carry. On a CANCELLED message it is the instant that was called off.

Each of the preceding statuses has a matching webhook sub-type. PROCESSED, which a message reports for the short interval between acceptance and routing, is the one status without a sub-type, so status webhooks never carry it. See Event Types for the full status catalog and the payload shape of each event.