SimpleSMSDocs

Act on many numbers at once

POST /v1/numbers/bulk

Tag, untag, label, pool, unpool or release up to 1000 numbers (100 for release). Returns 200 with a result per id even when some fail. Release requires confirm: "RELEASE <count of ids>"; test keys cannot release live numbers.

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.

Request body

JSON (Content-Type: application/json).

FieldTypeRequiredDescription
idsarray of stringYesAt most 1000 items.
actionadd_to_pool, remove_from_pool, add_tags, remove_tags, set_label, releaseYes
pool_idstringNoadd_to_pool / remove_from_pool
tagsarray of stringNoadd_tags / remove_tags. Lowercased; up to 20 per number.
labelstringNoset_label; null clears At most 64 characters. Nullable.
confirmstringNorelease only Example: RELEASE 2.

Responses

StatusMeaningBody
200Per-id resultsBulkResult
400Malformed request or missing release confirmationError
401Missing, malformed, or revoked API keyError
402Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or chargedError
429Rate limit or quota exceededError

200: BulkResult fields

FieldTypeDescription
objectbulk_result
actionstring
requestedinteger
succeededinteger
failedinteger
resultsarray of object
results[].idstring
results[].okboolean
results[].errorinvalid_id, duplicate, not_found, too_many_tags, mode_mismatch, carrier_error
results[].messagestring

Errors

StatusWhen
400Malformed request or missing release confirmation
401Missing, malformed, or revoked API key
402Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged
429Rate 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/bulk" \
  -H "Authorization: Bearer $SIMPLESMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "ids": [
    "+15005550132",
    "+15005550154"
  ],
  "action": "add_to_pool",
  "confirm": "RELEASE 2"
}'

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/bulk', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SIMPLESMS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "ids": [
      "+15005550132",
      "+15005550154"
    ],
    "action": "add_to_pool",
    "confirm": "RELEASE 2"
  }),
});

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/bulk",
    method="POST",
    headers={
        "Authorization": f"Bearer {os.environ['SIMPLESMS_API_KEY']}",
        "Content-Type": "application/json",
    },
    data=json.dumps({
        "ids": [
            "+15005550132",
            "+15005550154"
        ],
        "action": "add_to_pool",
        "confirm": "RELEASE 2"
    }).encode(),
)
with urllib.request.urlopen(req) as res:
    data = json.load(res)

Related