SimpleSMSDocs

Subscribe or unsubscribe a contact from a topic

PUT /v1/contacts/{id}/topics/{topic}

topic is a topic id or name. Recorded in the consent ledger and the audit log. No record means subscribed, so only an unsubscribe narrows who is sent to. Subscribing to a topic does not lift an opt-out.

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

NameTypeRequiredDescription
idstringYesContact id or phone number
topicstringYesTopic id (tp_...) or name

Request body

JSON (Content-Type: application/json).

FieldTypeRequiredDescription
subscribedbooleanYes
sourcestringNoWhere the change came from, e.g. "preference_page". Default "api".

Responses

StatusMeaningBody
200The new state; changed is false when it already wasJSON object
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
404No such contact, number, or topicError
429Rate limit or quota exceededError

200: response fields

FieldTypeDescription
objecttopic_subscription
phonestring
contact_idstringNullable.
topic_idstring
namestring
subscribedboolean
changedboolean

Errors

StatusWhen
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
404No such contact, number, or topic
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 PUT "https://api.joinsimplesms.com/v1/contacts/ct_a1B2c3D4e5F6/topics/tp_marketing" \
  -H "Authorization: Bearer $SIMPLESMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "subscribed": true
}'

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/contacts/ct_a1B2c3D4e5F6/topics/tp_marketing', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.SIMPLESMS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "subscribed": true
  }),
});

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/contacts/ct_a1B2c3D4e5F6/topics/tp_marketing",
    method="PUT",
    headers={
        "Authorization": f"Bearer {os.environ['SIMPLESMS_API_KEY']}",
        "Content-Type": "application/json",
    },
    data=json.dumps({
        "subscribed": True
    }).encode(),
)
with urllib.request.urlopen(req) as res:
    data = json.load(res)

Related