REST API conventions

Base URL

The production base URL is https://app.message.com/api/v1. Use HTTPS. There is no universal test-key prefix or separate sandbox host for all products. A Stripe test payment does not make a carrier message or call free.

Authentication and JSON

Use the credential supported by the specific endpoint: an agent session JWT, scoped integration key or Verify key. They are not interchangeable. Send Authorization: Bearer, Accept: application/json, and Content-Type: application/json when sending JSON. Keep credentials on your server.

Pagination is resource-specific

Some endpoints use cursors, others use page and pageSize, and some return an unpaginated list. For cursor endpoints, pass the returned cursor unchanged and stop when nextCursor is null or the resource’s hasMore flag is false. Do not decode a cursor or assume its format is shared between resources.

The audit log accepts limit (default 50, maximum 200) and cursor, returning entries and nextCursor. Phone-number search/listing and messaging polling have different contracts. Keep filters fixed while paging, and start again if they change.

curl 'https://app.message.com/api/v1/workspace/audit-log?limit=50' \
  -H 'Authorization: Bearer YOUR_AGENT_JWT'

Retries and duplicate prevention

There is no universal Idempotency-Key header across the API. Use the explicit request ID or idempotencyKey field only where the endpoint documents it. For example, the connector SMS send API uses a UUID idempotencyKey in the body. Reuse that key only for the same intended send and payload.

A timeout does not prove a mutation failed. Read the saved result or reconcile the operation before retrying a payment, message, invitation or purchase. Retry safe reads with bounded backoff; do not blindly retry every POST or every 5xx response.

Concurrency

Some conversation-assignment endpoints accept or require expectedVersion. Read the resource, send its current version, and on a stale-version response fetch again and reconcile before retrying. Most settings resources do not expose version locking. Follow the exact resource contract instead of adding expectedVersion everywhere.

Resource IDs

Treat IDs as opaque strings. Most workspace records use UUIDs, while provider identifiers can use different formats. Do not generate or infer another resource’s ID from a displayed name or phone number.

Dates and times

Many application timestamps use ISO 8601, but individual provider and reporting fields may use dates, epoch values or local-time schedules. Follow the documented field type and timezone; do not assume every numeric value is milliseconds.

Interpret the response

Read both HTTP status and the response body. A 2xx response can represent accepted, pending or a negative verification result rather than completed delivery. A 4xx response usually needs corrected input, permissions, credit or configuration. A 5xx response needs reconciliation and a controlled retry. Respect Retry-After on rate limits.

Build against the resource contract

Unknown fields can be rejected or ignored. Use documented fields and check results rather than relying on a successful HTTP response alone. Store workspace-scoped identifiers together, and never reuse one customer’s token for another customer.