Attach a number to a registration

POST /v1/numbers/{id}/registration

Ties a live US local number to one of your registrations. Needed only when you have more than one approved registration, or to retry a link that failed; otherwise numbers follow your registration on their own. If the registration is approved the number is linked with the carriers (sender.state pending, then active); a registration holds at most 49 numbers. Emits number.sender_updated.

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.

Path parameters

Name	Type	Required	Description
`id`	string	Yes	The E.164 number

Request body

JSON (Content-Type: application/json).

Field	Type	Required	Description
`registration_id`	string	Yes	Example: `reg_a1B2c3D4e5F6`.

Responses

Status	Meaning	Body
200	The number with its new sender	`Number`
400	Unknown registration, or a number that is not registered (sandbox, toll-free)	`Error`
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`
404	Not found	`Error`
409	The registration already has 49 numbers, or the number is active elsewhere and this registration is not approved yet	`Error`
429	Rate limit or quota exceeded	`Error`

200: `Number` fields

Field	Type	Description
`id`	string	Example: `+15005550132`.
`object`	`number`
`phone_number`	string
`status`	`active`, `released`
`mode`	`test`, `live`
`created_at`	string (date-time)
`customer_id`	string	The customer this number is assigned to Nullable.
`label`	string	Nullable.
`tags`	array of string
`pools`	array of string	Pool ids
`sender`	object	How the number stands with the carriers. null on sandbox numbers and on numbers that need no registration (toll-free, Canadian). Only an active number can text anyone; in every other state it can text only your verified numbers. Nullable.
`sender.state`	`test_only`, `pending`, `active`, `action_needed`	test_only: no registration submitted. pending: a registration is in review, or approved and being linked. active: linked to an approved registration. action_needed: see reason.
`sender.registration_id`	string	The registration it is (being) linked to Nullable.
`sender.reason`	string	What to do, in plain words, when state is action_needed Nullable.
`sender.updated_at`	string (date-time)

Errors

Status	When
400	Unknown registration, or a number that is not registered (sandbox, toll-free)
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
404	Not found
409	The registration already has 49 numbers, or the number is active elsewhere and this registration is not approved yet
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 POST "https://api.joinsimplesms.com/v1/numbers/+15005550132/registration" \
  -H "Authorization: Bearer $SIMPLESMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "registration_id": "reg_a1B2c3D4e5F6"
}'

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/numbers/+15005550132/registration', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SIMPLESMS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "registration_id": "reg_a1B2c3D4e5F6"
  }),
});

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/numbers/+15005550132/registration",
    method="POST",
    headers={
        "Authorization": f"Bearer {os.environ['SIMPLESMS_API_KEY']}",
        "Content-Type": "application/json",
    },
    data=json.dumps({
        "registration_id": "reg_a1B2c3D4e5F6"
    }).encode(),
)
with urllib.request.urlopen(req) as res:
    data = json.load(res)