Transactional SMS API Request and Response Schema Design

Why schema design matters

An API schema becomes the language shared by application developers and the messaging platform. Poorly chosen fields create ambiguity that becomes difficult to remove after integrations are deployed.

A good schema should be explicit, predictable and designed around the message lifecycle.

Message resource

A message resource commonly needs an immutable message ID, business reference, message type, sender reference, recipient reference or masked destination, template reference, status and timestamps.

Sensitive message content should be returned only where there is a clear need.

Identifier design

Use opaque internal IDs for platform resources. Business references can be supplied separately because they have different ownership and uniqueness rules.

Status model

Statuses should represent meaningful lifecycle states such as accepted, queued, submitted, delivered, failed or expired. Avoid status values that combine multiple unrelated concepts.

Document which transitions are possible and whether statuses are terminal.

Timestamps

Use explicit timestamp fields with timezone information or a consistent UTC representation. Distinguish created time, queued time, submitted time and final status time when these values are operationally useful.

Idempotency metadata

The response can return the message ID associated with the idempotency key. It should not require the client to create a duplicate request to discover whether the original succeeded.

Metadata

Custom metadata can help clients correlate messages with their own systems. Limit size and define whether metadata is returned in webhooks and reports.

Pagination

List endpoints should use predictable pagination. Cursor-based pagination can be useful for large message histories because it avoids some of the instability of offset pagination when new records are inserted.

Filtering

Support filters that match actual operational needs, such as status, message type, business reference and time range. Avoid exposing unrestricted database query semantics.

Response consistency

The same field should have the same type and meaning across endpoints. If message_id is a string in one response, it should not become a number elsewhere.

Schema documentation

Use machine-readable schemas such as OpenAPI where appropriate. Include examples, required fields, nullable behaviour and status descriptions.

Implementation checklist

Define resource identity, status semantics, timestamps, idempotency behaviour, metadata, pagination, filtering, error schema and machine-readable documentation.

Request schema example

A message request can conceptually contain template_id, sender_id, recipient, variables, business_reference, scheduled_at and idempotency_key. Each field should have a documented type, length, required status and authorization rule.

Avoid allowing clients to submit internal status fields or provider IDs in create requests.

Response schema example

A create response can return message_id, status, created_at, scheduled_at and correlation information. Provider credentials and internal worker details should never be returned.

If the request is idempotently repeated, the same logical message ID should be returned.

Nullable fields

Define whether a field can be absent, null or empty. These are not always equivalent to clients.

Inconsistent nullable behaviour is a common source of integration bugs.

Status transitions

Document transitions such as ACCEPTED → QUEUED → SUBMITTED → DELIVERED or FAILED. Explain which transitions are terminal and how late callbacks are handled.

This becomes especially important when clients build dashboards or trigger business workflows from status changes.

Pagination example

A message-history endpoint can return items plus a next_cursor. The cursor should remain opaque to the client. Filtering by tenant, time range and status should be enforced server-side.

Schema evolution

Use additive changes where possible. When a field's meaning must change, introduce a new field or API version rather than silently changing its semantics.

Final developer checklist

Define create and response schemas, identifier types, status transitions, nullable rules, pagination, filtering, idempotency behaviour and machine-readable API documentation.

OpenAPI design

An OpenAPI document can describe endpoints, request bodies, responses, authentication schemes and error objects. It should be generated or maintained close to the implementation so it does not drift.

Examples should reflect realistic payloads while avoiding real customer data.

Resource-oriented endpoints

Design endpoints around stable resources such as messages, templates, senders and schedules rather than exposing internal database operations. This keeps the public contract independent of implementation details.

Create versus update

Creating a message is usually different from updating its lifecycle state. Applications should not be allowed to set DELIVERED or SUBMITTED through a generic update endpoint.

State changes should be controlled by the platform's processing events.

List response design

List endpoints should make total counts optional when calculating them is expensive. Cursor pagination and stable ordering can provide predictable performance for large histories.

Filtering semantics

Document whether filters use exact match, prefix, range or set semantics. Time filters should specify whether endpoints use UTC and whether end timestamps are inclusive or exclusive.

Idempotent create semantics

A create request with an idempotency key should return the same logical resource when repeated. Document how long the key remains valid and what happens when the same key is reused with different payloads.

Webhook schema relationship

Webhook resources should reuse common identifiers and status vocabulary from the REST API where possible. This reduces the number of concepts developers must learn.

Schema linting

Automated schema linting can catch inconsistent field names, missing descriptions, invalid examples and incompatible changes before publication.

Operational scenario

A developer receives a message resource with status DELIVERED and can use message_id to correlate the corresponding delivery webhook. The API and webhook share the same status vocabulary and timestamp semantics, reducing integration ambiguity.

Final production checklist

Verify resource naming, request and response schemas, status control, pagination, filtering, idempotency, webhook consistency, OpenAPI documentation and schema linting.

Schema governance

A schema review should ask whether every field has a clear owner, type, lifecycle and security classification. Fields added for internal convenience should not automatically become public API fields.

Once published, removing a field is harder than adding one, so public schemas should be deliberately minimal.

Example quality

Examples should include realistic values for dates, IDs, variables and status transitions. Include at least one error example and one idempotent-repeat example so developers understand behaviour beyond the happy path.

Schema compatibility checks

Run automated compatibility checks when a schema changes. Detect removed fields, changed required properties, altered types and incompatible enum changes before the new contract is published.

Final decision guide

Design the schema around stable business resources and lifecycle semantics, keep internal implementation fields private, document exact types and nullability, and automate compatibility checks.

Schema and client generation

When OpenAPI is used to generate client libraries, inaccurate schemas become executable integration defects. Review generated clients for dates, nullable fields, enums and error handling rather than assuming the generated code is correct simply because generation succeeded.

Schema review checklist

Before publishing a schema change, verify required fields, field types, examples, enum compatibility, pagination behaviour, error responses, security requirements and backward compatibility against supported clients.

Schema rule

Do not expose provider-specific identifiers as primary public resource IDs. Keep provider references as diagnostic fields so provider migrations do not force client migrations.

Final note

A clean schema should make the normal lifecycle obvious without requiring clients to understand the database or provider implementation.

Implementation scenario

An application creates message M123 with an idempotency key. A timeout occurs, so it repeats the request. The API returns M123 again. A later GET response and delivery webhook both use the same message ID and consistent status vocabulary.

Schema design in multi-tenant systems

Every resource response should remain scoped to the authenticated tenant. A message ID should not become a capability that allows another tenant to retrieve the record.

List endpoints, filters and pagination cursors must also preserve tenant scope. A cursor issued to one tenant should never reveal or retrieve another tenant's records if it is reused or manipulated.

Schema design and privacy

Recipient phone numbers and message bodies should be returned only where the API contract requires them. Masking can be the default for history and reporting endpoints, while privileged operations can expose additional detail under explicit authorization.

Final schema reminder

Keep public fields stable, typed and clearly documented.

Quality control

Before release, run automated schema compatibility checks against all supported client versions.