# API reference

Source: https://joinsimplesms.com/docs/api
Index: https://joinsimplesms.com/llms.txt

Every endpoint of the SimpleSMS REST API, one page each: parameters, request
body, response fields, errors, and examples in curl, Node.js and Python. The
pages are generated from the [OpenAPI document](/openapi.json), so they always
match what the API accepts.

- Base URL: `https://api.joinsimplesms.com/v1`
- Authentication: `Authorization: Bearer ssms_sk_test_...` (sandbox) or `ssms_sk_live_...` (live). See [Authentication](/docs/authentication).
- Requests and responses are JSON. Lists are paged with `cursor`, `has_more` and `next_cursor`.
- Errors share one envelope: `{ "error": { "code", "message", "param", "request_id" } }`. See [Errors](/docs/errors).
- 110 endpoints in 24 groups. All of them work with a free sandbox key.

## Messages

Guide: [Messages](/docs/messages)

| Endpoint | Request |
| --- | --- |
| [Send an SMS](/docs/api/messages/send) | `POST /v1/messages` |
| [List messages](/docs/api/messages/list) | `GET /v1/messages` |
| [Retrieve a message](/docs/api/messages/get) | `GET /v1/messages/{id}` |

## Batches

Guide: [Batches & broadcasts](/docs/broadcasts)

| Endpoint | Request |
| --- | --- |
| [Send a batch](/docs/api/batches/create-batch) | `POST /v1/batches` |
| [List batches](/docs/api/batches/list) | `GET /v1/batches` |
| [Retrieve a batch](/docs/api/batches/get-batch) | `GET /v1/batches/{id}` |
| [List a batch’s recipients](/docs/api/batches/list-batch-recipients) | `GET /v1/batches/{id}/recipients` |
| [Results of a batch](/docs/api/batches/get-batch-results) | `GET /v1/batches/{id}/results` |
| [Pause a batch](/docs/api/batches/pause-batch) | `POST /v1/batches/{id}/pause` |
| [Resume a paused batch](/docs/api/batches/resume-batch) | `POST /v1/batches/{id}/resume` |
| [Cancel a batch](/docs/api/batches/cancel-batch) | `POST /v1/batches/{id}/cancel` |
| [Retry failed recipients](/docs/api/batches/retry-batch) | `POST /v1/batches/{id}/retry` |

## Scheduled messages

Guide: [Scheduled messages](/docs/scheduled)

| Endpoint | Request |
| --- | --- |
| [List scheduled messages](/docs/api/scheduled-messages/list) | `GET /v1/scheduled_messages` |
| [Retrieve a pending scheduled message](/docs/api/scheduled-messages/get) | `GET /v1/scheduled_messages/{id}` |
| [Cancel a scheduled message](/docs/api/scheduled-messages/cancel) | `DELETE /v1/scheduled_messages/{id}` |

## Verify

Guide: [Verify](/docs/verify)

| Endpoint | Request |
| --- | --- |
| [Send a verification code](/docs/api/verify/send-verification) | `POST /v1/verify` |
| [Check a verification code](/docs/api/verify/check-verification) | `POST /v1/verify/check` |
| [Retrieve a verification](/docs/api/verify/get-verification) | `GET /v1/verify/{id}` |

## Numbers

Guide: [Numbers](/docs/numbers)

| Endpoint | Request |
| --- | --- |
| [Search available numbers](/docs/api/numbers/search-available) | `GET /v1/numbers/available` |
| [List your numbers](/docs/api/numbers/list) | `GET /v1/numbers` |
| [Purchase a number](/docs/api/numbers/purchase) | `POST /v1/numbers` |
| [Attach a number to a registration](/docs/api/numbers/attach-registration) | `POST /v1/numbers/{id}/registration` |
| [Retrieve a number](/docs/api/numbers/get) | `GET /v1/numbers/{id}` |
| [Assign a number to a customer](/docs/api/numbers/update) | `PATCH /v1/numbers/{id}` |
| [Release a number](/docs/api/numbers/release) | `DELETE /v1/numbers/{id}` |
| [Act on many numbers at once](/docs/api/numbers/bulk-update) | `POST /v1/numbers/bulk` |
| [Buy many numbers in an area code](/docs/api/numbers/bulk-purchase) | `POST /v1/numbers/bulk-purchase` |
| [Export numbers as CSV](/docs/api/numbers/export) | `GET /v1/numbers/export` |
| [List sender pools](/docs/api/numbers/list-pools) | `GET /v1/numbers/pools` |
| [Create a sender pool](/docs/api/numbers/create-pool) | `POST /v1/numbers/pools` |
| [Retrieve a pool](/docs/api/numbers/get-pool) | `GET /v1/numbers/pools/{id}` |
| [Rename a pool](/docs/api/numbers/update-pool) | `PATCH /v1/numbers/pools/{id}` |
| [Delete a pool](/docs/api/numbers/delete-pool) | `DELETE /v1/numbers/pools/{id}` |
| [Clone a pool](/docs/api/numbers/clone-pool) | `POST /v1/numbers/pools/{id}/clone` |

## Contacts

Guide: [Contacts](/docs/contacts)

| Endpoint | Request |
| --- | --- |
| [Create or update a contact](/docs/api/contacts/upsert) | `POST /v1/contacts` |
| [List contacts](/docs/api/contacts/list) | `GET /v1/contacts` |
| [Bulk create or update contacts](/docs/api/contacts/import) | `POST /v1/contacts/import` |
| [Tag, untag, or delete many contacts](/docs/api/contacts/bulk) | `POST /v1/contacts/bulk` |
| [Retrieve a contact](/docs/api/contacts/get) | `GET /v1/contacts/{id}` |
| [Update a contact](/docs/api/contacts/update) | `PATCH /v1/contacts/{id}` |
| [Delete a contact](/docs/api/contacts/delete) | `DELETE /v1/contacts/{id}` |
| [A contact's topic subscriptions](/docs/api/contacts/get-topics) | `GET /v1/contacts/{id}/topics` |
| [Subscribe or unsubscribe a contact from a topic](/docs/api/contacts/set-topic) | `PUT /v1/contacts/{id}/topics/{topic}` |

## Customers

Guide: [Customers](/docs/customers)

| Endpoint | Request |
| --- | --- |
| [Create a customer](/docs/api/customers/create) | `POST /v1/customers` |
| [List customers](/docs/api/customers/list) | `GET /v1/customers` |
| [Retrieve a customer](/docs/api/customers/get) | `GET /v1/customers/{id}` |
| [Update a customer](/docs/api/customers/update) | `PATCH /v1/customers/{id}` |
| [Delete a customer](/docs/api/customers/delete) | `DELETE /v1/customers/{id}` |
| [A customer's usage](/docs/api/customers/get-usage) | `GET /v1/customers/{id}/usage` |

## Lookup

Guide: [Lookup](/docs/lookup)

| Endpoint | Request |
| --- | --- |
| [Look up a phone number](/docs/api/lookup/phone) | `GET /v1/lookup/{phone}` |

## Segments

Guide: [Contacts](/docs/contacts)

| Endpoint | Request |
| --- | --- |
| [Create a segment](/docs/api/segments/create) | `POST /v1/segments` |
| [List segments](/docs/api/segments/list) | `GET /v1/segments` |
| [Retrieve a segment](/docs/api/segments/get) | `GET /v1/segments/{id}` |
| [Update a segment](/docs/api/segments/update) | `PATCH /v1/segments/{id}` |
| [Delete a segment](/docs/api/segments/delete) | `DELETE /v1/segments/{id}` |
| [Count a segment](/docs/api/segments/preview) | `GET /v1/segments/{id}/preview` |

## Topics

Guide: [Contacts](/docs/contacts)

| Endpoint | Request |
| --- | --- |
| [List subscription topics](/docs/api/topics/list) | `GET /v1/topics` |
| [Create a topic](/docs/api/topics/create) | `POST /v1/topics` |
| [Retrieve a topic](/docs/api/topics/get) | `GET /v1/topics/{id}` |
| [Rename or describe a topic](/docs/api/topics/update) | `PATCH /v1/topics/{id}` |
| [Delete a topic](/docs/api/topics/delete) | `DELETE /v1/topics/{id}` |

## Consent

Guide: [Opt-out, consent & TCPA](/docs/opt-out)

| Endpoint | Request |
| --- | --- |
| [List opted-out numbers (suppression list)](/docs/api/consent/list) | `GET /v1/consent` |
| [Consent state and append-only history for one number](/docs/api/consent/get) | `GET /v1/consent/{phone}` |
| [Set consent state from your own system (CRM sync)](/docs/api/consent/set) | `POST /v1/consent/{phone}` |
| [Bulk-import a suppression list (up to 500 numbers)](/docs/api/consent/import) | `POST /v1/consent/import` |
| [Export the suppression list, or the full consent ledger with opt-in proof, as CSV](/docs/api/consent/export) | `GET /v1/consent/export` |

## Registrations

Guide: [Compliance & registration](/docs/compliance)

| Endpoint | Request |
| --- | --- |
| [List brand + campaign registrations](/docs/api/registrations/list) | `GET /v1/registrations` |
| [Create a registration and run the website disclosure check](/docs/api/registrations/create) | `POST /v1/registrations` |
| [Suggest a registration from a website](/docs/api/registrations/prefill) | `POST /v1/registrations/prefill` |
| [Get a registration](/docs/api/registrations/get) | `GET /v1/registrations/{id}` |
| [Re-run the checks (optionally correcting input fields)](/docs/api/registrations/recheck) | `POST /v1/registrations/{id}/recheck` |
| [Submit a ready registration for carrier review (or resubmit after a rejection)](/docs/api/registrations/submit) | `POST /v1/registrations/{id}/submit` |
| [List the filed copies of a registration](/docs/api/registrations/list-submissions) | `GET /v1/registrations/{id}/submissions` |

## Events

Guide: [Webhooks](/docs/webhooks)

| Endpoint | Request |
| --- | --- |
| [List events](/docs/api/events/list) | `GET /v1/events` |
| [Long-poll for new events](/docs/api/events/wait-for) | `GET /v1/events/wait` |
| [Replay an event to one webhook endpoint](/docs/api/events/replay) | `POST /v1/events/{id}/replay` |

## Webhooks

Guide: [Webhooks](/docs/webhooks)

| Endpoint | Request |
| --- | --- |
| [List webhook endpoints](/docs/api/webhooks/list-endpoints) | `GET /v1/webhooks` |
| [Create a webhook endpoint](/docs/api/webhooks/create-endpoint) | `POST /v1/webhooks` |
| [Get a webhook endpoint](/docs/api/webhooks/get-endpoint) | `GET /v1/webhooks/{id}` |
| [Update a webhook endpoint](/docs/api/webhooks/update-endpoint) | `PATCH /v1/webhooks/{id}` |
| [Delete a webhook endpoint](/docs/api/webhooks/delete-endpoint) | `DELETE /v1/webhooks/{id}` |
| [List webhook delivery attempts](/docs/api/webhooks/list-deliveries) | `GET /v1/webhooks/deliveries` |

## Deliverability

Guide: [Deliverability](/docs/deliverability)

| Endpoint | Request |
| --- | --- |
| [Delivery rates by day, carrier, or sending number](/docs/api/deliverability/get) | `GET /v1/deliverability` |

## Balance

| Endpoint | Request |
| --- | --- |
| [Get the prepaid credit balance and auto-recharge setting](/docs/api/balance/get) | `GET /v1/balance` |

## Spend limit

Guide: [Spend limits](/docs/spend-limits)

| Endpoint | Request |
| --- | --- |
| [Get the monthly spend limit and this month's estimated spend](/docs/api/spend-limit/get) | `GET /v1/spend-limit` |
| [Set or remove the monthly spend limit and alert thresholds](/docs/api/spend-limit/update) | `PATCH /v1/spend-limit` |

## Audit log

Guide: [Audit log](/docs/audit-logs)

| Endpoint | Request |
| --- | --- |
| [List audit log entries](/docs/api/audit-logs/list) | `GET /v1/audit-logs` |

## Exports

| Endpoint | Request |
| --- | --- |
| [Export messages, delivery results, events, opt-outs, webhook deliveries, usage, credit history or the audit log as CSV](/docs/api/exports/csv) | `GET /v1/exports/{kind}` |

## Tracked events

Guide: [Automations](/docs/automations)

| Endpoint | Request |
| --- | --- |
| [Track a customer event](/docs/api/track/event) | `POST /v1/track` |

## Schedules

| Endpoint | Request |
| --- | --- |
| [List recurring schedules (at most 100 per account)](/docs/api/schedules/list) | `GET /v1/schedules` |
| [Create a recurring schedule](/docs/api/schedules/create) | `POST /v1/schedules` |
| [Retrieve a schedule, with its recent occurrences](/docs/api/schedules/get) | `GET /v1/schedules/{id}` |
| [Change, pause or resume a schedule](/docs/api/schedules/update) | `PATCH /v1/schedules/{id}` |
| [Delete a schedule](/docs/api/schedules/delete) | `DELETE /v1/schedules/{id}` |

## Automations

Guide: [Automations](/docs/automations)

| Endpoint | Request |
| --- | --- |
| [List automations (at most 50 per account)](/docs/api/automations/list) | `GET /v1/automations` |
| [Create an automation (as a draft)](/docs/api/automations/create) | `POST /v1/automations` |
| [Retrieve an automation](/docs/api/automations/get) | `GET /v1/automations/{id}` |
| [Edit an automation](/docs/api/automations/update) | `PATCH /v1/automations/{id}` |
| [Delete an automation](/docs/api/automations/delete) | `DELETE /v1/automations/{id}` |
| [Activate an automation](/docs/api/automations/activate) | `POST /v1/automations/{id}/activate` |
| [Pause an automation](/docs/api/automations/pause) | `POST /v1/automations/{id}/pause` |
| [List an automation's runs, newest first](/docs/api/automations/list-runs) | `GET /v1/automations/{id}/runs` |
| [Retrieve a run with its timeline](/docs/api/automations/get-run) | `GET /v1/automations/{id}/runs/{run_id}` |
| [Cancel a run in progress](/docs/api/automations/cancel-run) | `DELETE /v1/automations/{id}/runs/{run_id}` |

## Templates

Guide: [Batches & broadcasts](/docs/broadcasts)

| Endpoint | Request |
| --- | --- |
| [List message templates (at most 100 per account)](/docs/api/templates/list) | `GET /v1/templates` |
| [Create a template with {{merge}} fields](/docs/api/templates/create) | `POST /v1/templates` |
| [Retrieve a template](/docs/api/templates/get) | `GET /v1/templates/{id}` |
| [Rename or edit a template](/docs/api/templates/update) | `PATCH /v1/templates/{id}` |
| [Delete a template](/docs/api/templates/delete) | `DELETE /v1/templates/{id}` |

## Sandbox

Guide: [Sandbox & test numbers](/docs/sandbox)

| Endpoint | Request |
| --- | --- |
| [Simulate an inbound SMS (test keys only)](/docs/api/test/simulate-inbound) | `POST /v1/test/inbound` |