List brand + campaign registrations

GET /v1/registrations

Send your API key as a bearer token: Authorization: Bearer ssms_sk_.... Test keys run this endpoint against the sandbox; see Authentication for key modes and scopes.

Responses

Status	Meaning	Body
200	Registrations, newest first	Page of `Registration`
401	Missing, malformed, or revoked API key	`Error`
402	Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged	`Error`
429	Rate limit or quota exceeded	`Error`

200: each item in `data` (Registration)

The body is a page: data (the array), has_more, and next_cursor (null on the last page).

Field	Type	Description
`id`	string	Example: `reg_a1B2c3D4e5F6`.
`object`	`registration`
`status`	`draft`, `checks_failed`, `ready`, `submitted`, `in_review`, `approved`, `rejected`
`business_name`	string
`website`	string
`use_case`	string
`opt_in_url`	string	Nullable.
`privacy_url`	string	Nullable.
`terms_url`	string	Nullable.
`support_email`	string	Nullable.
`brand`	object
`sample_messages`	array of string	The examples as they stand: yours, or starter drafts (see samples_source). These are what a submission files.
`samples_source`	`starter`, `customer`	starter: our drafts, not yet edited or confirmed; the registration cannot be ready. customer: yours.
`description`	string	Your own description; null when the generated one (generated.campaign.description) is filed Nullable.
`sample_check`	object	The example-message check. Deterministic rules, no AI. Recomputed on every read.
`sample_check.passed`	integer
`sample_check.failed`	integer
`sample_check.warnings`	integer
`sample_check.ok`	boolean
`sample_check.findings`	array of SampleFinding
`guidance`	object	The five answers every state gives
`guidance.what_happened`	string
`guidance.why`	string
`guidance.next_actor`	`you`, `delivered`, `carriers`, `nobody`
`guidance.next_step`	string
`guidance.after`	string
`check`	object	Nullable.
`check.checked_at`	string (date-time)
`check.passed`	integer
`check.failed`	integer
`check.warnings`	integer
`check.urls`	object
`check.findings`	array of Finding
`rejection`	object	Nullable.
`rejection.code`	string
`rejection.title`	string
`rejection.explanation`	string
`rejection.fix`	string
`rejection.note`	string	Nullable.
`rejection.related_findings`	array of string
`rejection.rejected_at`	string (date-time)
`generated`	object	Deterministic compliant copy and the registry draft
`generated.opt_in_cta`	string
`generated.privacy_clause`	string
`generated.sms_terms`	string
`generated.sample_messages`	array of string	Starter drafts from templates. What is filed is the top-level sample_messages (also in generated.campaign.sample_messages). At most 5 items. At least 2 items.
`generated.help_reply`	string
`generated.stop_reply`	string
`generated.opt_in_confirmation`	string
`generated.brand`	object
`generated.brand.missing`	array of string
`generated.campaign`	object
`generated.campaign.use_case`	string
`generated.campaign.description`	string
`generated.campaign.message_flow`	string
`generated.campaign.sample_messages`	array of string
`generated.campaign.opt_in_keywords`	array of string
`generated.campaign.opt_in_message`	string
`generated.campaign.opt_out_keywords`	array of string
`generated.campaign.opt_out_message`	string
`generated.campaign.help_keywords`	array of string
`generated.campaign.help_message`	string
`generated.campaign.embedded_link`	boolean
`generated.campaign.embedded_phone`	boolean
`generated.campaign.number_pooling`	boolean
`generated.campaign.direct_lending`	boolean
`generated.campaign.age_gated`	boolean
`generated.campaign.affiliate_marketing`	boolean
`generated.campaign.privacy_policy_url`	string
`generated.campaign.terms_url`	string
`submissions`	integer
`history`	array of object
`history[].at`	string (date-time)
`history[].status`	string
`history[].actor`	`customer`, `delivered`, `system`
`history[].label`	string
`history[].reason_code`	string
`history[].note`	string
`created_at`	string (date-time)
`updated_at`	string (date-time)

Errors

Status	When
401	Missing, malformed, or revoked API key
402	Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged
429	Rate limit or quota exceeded

Every error has the same JSON shape, and request_id matches the X-Request-Id response header. Errors lists every code and what to do about it.

json

{
  "error": {
    "code": "invalid_request",
    "message": "What went wrong, in plain words.",
    "param": "the_field",
    "request_id": "req_a1B2c3D4e5F6g7H8"
  }
}

Examples

curl

bash

curl -X GET "https://api.joinsimplesms.com/v1/registrations" \
  -H "Authorization: Bearer $SIMPLESMS_API_KEY"

Node.js

The Node.js SDK does not wrap this endpoint yet; call it with fetch.

javascript

const res = await fetch('https://api.joinsimplesms.com/v1/registrations', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SIMPLESMS_API_KEY}`,
  },
});

if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

Python

The Python SDK does not wrap this endpoint yet; call it over HTTP.

python

import json, os, urllib.request

req = urllib.request.Request(
    "https://api.joinsimplesms.com/v1/registrations",
    method="GET",
    headers={
        "Authorization": f"Bearer {os.environ['SIMPLESMS_API_KEY']}",
    },
)
with urllib.request.urlopen(req) as res:
    data = json.load(res)