Text Messaging API overview

OpenAPI Spec

Machine-readable spec for the Text Messaging API: beta/categories/text_messaging.json

Before you begin

Check out our general API overview to make sure you're ready to get started with specific endpoints.

🚧

The Text Messaging API is in beta. You must pin a beta revision (for example, revision: 2026-07-15.pre) to call these endpoints. Beta endpoints may change before they reach general availability.

The Text Messaging API lets you set up and manage an account's SMS sending capability programmatically: create the account's text messaging configuration, provision toll-free senders, and track each sender's carrier registration. It exposes the same records the dashboard uses under Settings > Text messages, so you can stand up SMS sending for an account end to end without the UI.

These endpoints configure SMS sending — they do not send messages. You cannot send an SMS through the Text Messaging API. Once a configuration and an approved sender are in place, the account sends SMS through Klaviyo campaigns and flows.

Use cases

Here are example use cases supported by the Text Messaging API:

• Set up an account's text messaging configuration to enable SMS sending.
• Provision a toll-free sender for an account and submit its carrier registration in a single call.
• Poll a sender's registration status and surface the carrier's decision (approved or rejected) in your own tooling.
• Resubmit a corrected registration after a rejection, using the failure reasons returned by the API.
• List an account's senders and their registration status to build an internal SMS-readiness dashboard.

Required scopes

To use Text Messaging API endpoints, your API key or OAuth app needs the following scopes:

• sender-config:read — required to retrieve configurations, senders, and registrations.
• sender-config:write — required to create a configuration, provision a sender, or resubmit a registration.

A key without the required scope receives a 403 response. See Troubleshooting.

Data model

The API has three resources.

Text messaging configuration

The text-messaging-configuration resource is the account-level record that enables SMS for a company. It is a singleton: an account has at most one, and its id is the account's company id. Create it before provisioning any senders.

• org_prefix — a branding prefix prepended to outbound messages so recipients can identify the sender. Maximum 50 characters.
• opt_out_language — the opt-out instructions appended to outbound messages.
• status — active or disabled.
• created_at, updated_at — ISO 8601 timestamps.

Text messaging sender

The text-messaging-sender resource is a provisioned sending number. Toll-free is the currently supported sender type.

• sender_type — the kind of sender. Currently toll_free.
• sender_details — attributes specific to the sender type. For toll-free, this is the country (ISO 3166-1 alpha-2, for example US).
• status — the sender lifecycle state: pending_registration, registering, active, registration_failed, or suspended.
• forwarding_number — the E.164 number that inbound voice calls are forwarded to, or null when forwarding is not configured.
• sender_identifier — the sender's outbound address (the E.164 phone number). For toll-free, the number is assigned at provision time, so it's populated as soon as the sender is created — including while status is pending_registration. A toll-free number's US and Canada records share the same sender_identifier.
• created_at — ISO 8601 timestamp.
• Relationship: text-messaging-sender-registration — the sender's most recent carrier registration.

Text messaging sender registration

The text-messaging-sender-registration resource is a sender's carrier registration — the record carriers review before a toll-free number may send.

• status — action_required, in_review, approved, or rejected. A registration is created in in_review and ends in approved or rejected; action_required means the carrier needs more information before it can proceed.
• failures — a list of objects, each with a detail string describing a reason the registration was rejected. Populated only when status is rejected.
• submitted_at — when the registration was submitted, or null until it is.
• decided_at — when the carrier approved or rejected the registration, or null until a decision is returned.
• created_at, updated_at — ISO 8601 timestamps.
• Relationship: text-messaging-sender — the sender this registration belongs to.

Set up the account's configuration

Setting up a text messaging configuration is the first step — create it before any other action. Until it exists, the sender and registration endpoints return 403.

curl --request POST \
  --url 'https://a.klaviyo.com/api/text-messaging-configurations' \
  --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'revision: 2026-07-15.pre' \
  --data '{
    "data": {
      "type": "text-messaging-configuration",
      "attributes": {
        "org_prefix": "Acme"
      }
    }
  }'

{
  "data": {
    "type": "text-messaging-configuration",
    "id": "AbC123",
    "attributes": {
      "org_prefix": "Acme",
      "opt_out_language": "Text STOP to opt-out",
      "status": "active",
      "created_at": "2026-07-13T14:30:00+00:00",
      "updated_at": "2026-07-13T14:30:00+00:00"
    },
    "links": {
      "self": "https://a.klaviyo.com/api/text-messaging-configurations/AbC123/"
    }
  }
}

Retrieve the configuration with GET /api/text-messaging-configurations/{id}, where {id} is the account's company id. Because the configuration is a singleton, requesting any other id returns 404.

Provision a sender

POST /api/text-messaging-senders provisions a toll-free number and submits its initial carrier registration in one call. The registration details are embedded in the request under the text-messaging-sender-registration relationship.

📘

Provisioning a toll-free sender assigns a real toll-free number that can send in both the US and Canada, and counts against the account's number limit. A toll-free number is registered in both regions, so creating one region's sender creates the other's at the same time. Both records are the same number — they share the same sender_identifier — and they share one carrier registration, so registering (or resubmitting) one registers the other. The response returns the record for the country you requested; match on sender_identifier to relate the pair in list and retrieve responses, and read sender_details.country for the region.

curl --request POST \
  --url 'https://a.klaviyo.com/api/text-messaging-senders' \
  --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'revision: 2026-07-15.pre' \
  --data '{
    "data": {
      "type": "text-messaging-sender",
      "attributes": {
        "sender_type": "toll_free",
        "sender_details": {
          "country": "US"
        },
        "text-messaging-sender-registration": {
          "data": {
            "type": "text-messaging-sender-registration",
            "attributes": {
              "first_name": "Jane",
              "last_name": "Doe",
              "phone_number": "+16175551212",
              "email": "[email protected]",
              "address": {
                "street_address_1": "125 Summer Street",
                "city": "Boston",
                "region": "MA",
                "postal_code": "02110",
                "country": "US"
              },
              "business_name": "Acme Corp",
              "business_website": "https://www.acme.com",
              "business_type": "corporation",
              "business_registration_country": "US",
              "business_registration_authority": "EIN",
              "business_registration_number": "12-3456789"
            }
          }
        }
      }
    }
  }'

{
  "data": {
    "type": "text-messaging-sender",
    "id": "01HX2Z8RG7Y4PWFQK3V0M5N1B7",
    "attributes": {
      "sender_type": "toll_free",
      "sender_details": {
        "country": "US"
      },
      "status": "pending_registration",
      "forwarding_number": null,
      "sender_identifier": "+18885551234",
      "created_at": "2026-07-13T14:35:00+00:00"
    },
    "relationships": {
      "text-messaging-sender-registration": {
        "data": {
          "type": "text-messaging-sender-registration",
          "id": "01HX2Z8RG7Y4PWFQK3V0M5N1C8"
        },
        "links": {
          "self": "https://a.klaviyo.com/api/text-messaging-senders/01HX2Z8RG7Y4PWFQK3V0M5N1B7/relationships/text-messaging-sender-registration/",
          "related": "https://a.klaviyo.com/api/text-messaging-senders/01HX2Z8RG7Y4PWFQK3V0M5N1B7/text-messaging-sender-registration/"
        }
      }
    },
    "links": {
      "self": "https://a.klaviyo.com/api/text-messaging-senders/01HX2Z8RG7Y4PWFQK3V0M5N1B7/"
    }
  }
}

A successful request returns 201 Created with the sender for the requested country. The embedded registration is created in in_review.

List and retrieve senders

Use GET /api/text-messaging-senders to list the account's senders. The endpoint supports cursor pagination (page[size] up to 20), sorting on created_at, and sparse fieldsets. Use GET /api/text-messaging-senders/{id} to retrieve a single sender.

Include each sender's current registration inline with ?include=text-messaging-sender-registration:

curl --request GET \
  --url 'https://a.klaviyo.com/api/text-messaging-senders?include=text-messaging-sender-registration' \
  --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
  --header 'accept: application/json' \
  --header 'revision: 2026-07-15.pre'

The response is a JSON:API compound document: the senders are in data, and their registrations are in the top-level included array.

Because a toll-free number can send in both the US and Canada, the list includes a record for each region, both sharing the same sender_identifier. Match on sender_identifier to treat the pair as a single number — for example, when counting numbers in a dashboard — and read sender_details.country for the region.

Track and resubmit a registration

A registration starts in in_review and transitions to approved or rejected once the carrier returns a decision. Retrieve a registration directly with GET /api/text-messaging-sender-registrations/{id}, or fetch a sender's most recent registration with the related-resource link GET /api/text-messaging-senders/{id}/text-messaging-sender-registration. Both support ?include=text-messaging-sender to include the linked sender inline.

A toll-free number's US and Canada records share one carrier registration, so submitting or resubmitting for one applies to both regions.

When a registration is rejected, the failures array explains why:

{
  "data": {
    "type": "text-messaging-sender-registration",
    "id": "01HX2Z8RG7Y4PWFQK3V0M5N1C8",
    "attributes": {
      "status": "rejected",
      "failures": [
        {
          "detail": "Invalid business details"
        }
      ],
      "submitted_at": "2026-07-13T14:35:00+00:00",
      "decided_at": "2026-07-13T14:52:00+00:00",
      "created_at": "2026-07-13T14:35:00+00:00",
      "updated_at": "2026-07-13T14:52:00+00:00"
    },
    "relationships": {
      "text-messaging-sender": {
        "data": {
          "type": "text-messaging-sender",
          "id": "01HX2Z8RG7Y4PWFQK3V0M5N1B7"
        }
      }
    }
  }
}

After a rejection, correct the details and resubmit with POST /api/text-messaging-sender-registrations. Send the same registration attributes as a create, plus a relationship to the sender you are resubmitting for:

curl --request POST \
  --url 'https://a.klaviyo.com/api/text-messaging-sender-registrations' \
  --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'revision: 2026-07-15.pre' \
  --data '{
    "data": {
      "type": "text-messaging-sender-registration",
      "attributes": {
        "first_name": "Jane",
        "last_name": "Doe",
        "phone_number": "+16175551212",
        "email": "[email protected]",
        "address": {
          "street_address_1": "125 Summer Street",
          "city": "Boston",
          "region": "MA",
          "postal_code": "02110",
          "country": "US"
        },
        "business_name": "Acme Corp",
        "business_website": "https://www.acme.com",
        "business_type": "corporation",
        "business_registration_country": "US",
        "business_registration_authority": "EIN",
        "business_registration_number": "12-3456789"
      },
      "relationships": {
        "text-messaging-sender": {
          "data": {
            "type": "text-messaging-sender",
            "id": "01HX2Z8RG7Y4PWFQK3V0M5N1B7"
          }
        }
      }
    }
  }'

A successful resubmission returns 201 Created with a new registration in in_review. You can only resubmit when the sender has no in-flight registration; resubmitting while a registration is still in_review returns 409.

Rate limits

Text Messaging API endpoints use these rate limit tiers:

• Read endpoints (retrieve a configuration, list or retrieve senders, retrieve a registration): SMALL — 3 requests/second burst and 60 requests/minute steady.
• Write endpoints (create a configuration, provision a sender, resubmit a registration): EXTRA_SMALL — 1 request/second burst and 15 requests/minute steady.

See rate limits for more information.

Troubleshooting

Additional resources

• OpenAPI spec: beta/categories/text_messaging.json
• Authenticate API requests
• JSON:API relationships
• Filtering
• Sparse fieldsets
• Rate limits, status codes, and errors