API reference
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, so they always match what the API accepts.
- Base URL:
https://api.joinsimplesms.com/v1 - Send your key as a bearer token. Test keys run against the sandbox, live keys send for real (authentication).
- Requests and responses are JSON. Lists are paged with a cursor.
- Errors share one envelope, with a code, a message and a request id (errors).
- 110 endpoints in 24 groups. All of them work with a free sandbox key.
Messages
Guide: Messages
Batches
Guide: Batches & broadcasts
- POSTSend a batch/v1/batches
- GETList batches/v1/batches
- GETRetrieve a batch/v1/batches/{id}
- GETList a batch’s recipients/v1/batches/{id}/recipients
- GETResults of a batch/v1/batches/{id}/results
- POSTPause a batch/v1/batches/{id}/pause
- POSTResume a paused batch/v1/batches/{id}/resume
- POSTCancel a batch/v1/batches/{id}/cancel
- POSTRetry failed recipients/v1/batches/{id}/retry
Scheduled messages
Guide: Scheduled messages
Verify
Guide: Verify
Numbers
Guide: Numbers
- GETSearch available numbers/v1/numbers/available
- GETList your numbers/v1/numbers
- POSTPurchase a number/v1/numbers
- POSTAttach a number to a registration/v1/numbers/{id}/registration
- GETRetrieve a number/v1/numbers/{id}
- PATCHAssign a number to a customer/v1/numbers/{id}
- DELETERelease a number/v1/numbers/{id}
- POSTAct on many numbers at once/v1/numbers/bulk
- POSTBuy many numbers in an area code/v1/numbers/bulk-purchase
- GETExport numbers as CSV/v1/numbers/export
- GETList sender pools/v1/numbers/pools
- POSTCreate a sender pool/v1/numbers/pools
- GETRetrieve a pool/v1/numbers/pools/{id}
- PATCHRename a pool/v1/numbers/pools/{id}
- DELETEDelete a pool/v1/numbers/pools/{id}
- POSTClone a pool/v1/numbers/pools/{id}/clone
Contacts
Guide: Contacts
- POSTCreate or update a contact/v1/contacts
- GETList contacts/v1/contacts
- POSTBulk create or update contacts/v1/contacts/import
- POSTTag, untag, or delete many contacts/v1/contacts/bulk
- GETRetrieve a contact/v1/contacts/{id}
- PATCHUpdate a contact/v1/contacts/{id}
- DELETEDelete a contact/v1/contacts/{id}
- GETA contact's topic subscriptions/v1/contacts/{id}/topics
- PUTSubscribe or unsubscribe a contact from a topic/v1/contacts/{id}/topics/{topic}
Customers
Guide: Customers
Lookup
Guide: Lookup
Segments
Guide: Contacts
Topics
Guide: Contacts
Consent
Guide: Opt-out, consent & TCPA
- GETList opted-out numbers (suppression list)/v1/consent
- GETConsent state and append-only history for one number/v1/consent/{phone}
- POSTSet consent state from your own system (CRM sync)/v1/consent/{phone}
- POSTBulk-import a suppression list (up to 500 numbers)/v1/consent/import
- GETExport the suppression list, or the full consent ledger with opt-in proof, as CSV/v1/consent/export
Registrations
Guide: Compliance & registration
- GETList brand + campaign registrations/v1/registrations
- POSTCreate a registration and run the website disclosure check/v1/registrations
- POSTSuggest a registration from a website/v1/registrations/prefill
- GETGet a registration/v1/registrations/{id}
- POSTRe-run the checks (optionally correcting input fields)/v1/registrations/{id}/recheck
- POSTSubmit a ready registration for carrier review (or resubmit after a rejection)/v1/registrations/{id}/submit
- GETList the filed copies of a registration/v1/registrations/{id}/submissions
Events
Guide: Webhooks
Webhooks
Guide: Webhooks
Deliverability
Guide: Deliverability
Balance
Spend limit
Guide: Spend limits
Audit log
Guide: Audit log
Exports
Tracked events
Guide: Automations
Schedules
Automations
Guide: Automations
- GETList automations (at most 50 per account)/v1/automations
- POSTCreate an automation (as a draft)/v1/automations
- GETRetrieve an automation/v1/automations/{id}
- PATCHEdit an automation/v1/automations/{id}
- DELETEDelete an automation/v1/automations/{id}
- POSTActivate an automation/v1/automations/{id}/activate
- POSTPause an automation/v1/automations/{id}/pause
- GETList an automation's runs, newest first/v1/automations/{id}/runs
- GETRetrieve a run with its timeline/v1/automations/{id}/runs/{run_id}
- DELETECancel a run in progress/v1/automations/{id}/runs/{run_id}
Templates
Guide: Batches & broadcasts
Sandbox
Guide: Sandbox & test numbers