Subscribe or unsubscribe a contact from a topic

topic is a topic id or name.

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

Path Parameters

idstringrequired
Contact id or phone number
topicstringrequired
Topic id (tp_...) or name

Body Parameters

subscribedbooleanrequired
sourcestring
Where the change came from, e.g. "preference_page". Default "api".

Details

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.

Responses

200JSON object
The new state; changed is false when it already was
401Error
Missing, malformed, or revoked API key
402Error
Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged
404Error
No such contact, number, or topic
429Error
Rate limit or quota exceeded

Response Fields

objecttopic_subscription
phonestring
contact_idstring
Nullable.
topic_idstring
namestring
subscribedboolean
changedboolean

Errors

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.

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
No such contact, number, or topic
429
Rate limit or quota exceeded

const res = await fetch('https://api.jointextkit.com/v1/contacts/ct_a1B2c3D4e5F6/topics/tp_marketing', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.TEXTKIT_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();

Response 200

{
  "object": "topic_subscription"
}