Add a join keyword
POST/api/v1/sms/numbers/{id}/join-keywords
POST /sms/numbers/{id}/join-keywords
curl -X POST 'https://www.unitpost.com/api/v1/sms/numbers/sms_123/join-keywords' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'User-Agent: my-app/1.0' \
-H 'Content-Type: application/json' \
-d '{ }'Response · 200
{
"object": "sms_join_keyword",
"id": "id_123",
"number_id": "number_123",
"keyword": "string",
"segment_id": "segment_123",
"topic_id": "topic_123",
"created_at": "2026-01-01T00:00:00.000Z",
"registration_warning": "string"
}A text that is exactly this word (any case) gets the double opt-in request ("Reply YES to get … texts"). The YES records marketing consent, makes the texter a contact if they aren't one, and adds them to segment_id (a static segment) and/or topic_id (an SMS topic). A keyword is never consent by itself and never lifts a STOP: an opted-out texter is told to text START. STOP, HELP, START, YES and their variants are refused; at most 10 per number; only numbers people can text back. Adding the same keyword again answers it (200), so a retry is safe. Requires the sms:manage capability.
Parameters1 field
| Field | Type | Description |
|---|---|---|
idrequired | string · path | — |
Request body3 fields
| Field | Type | Description |
|---|---|---|
keywordrequired | string | One word of 2–20 letters or digits, such as JOIN. STOP, HELP, START, YES and their variants are refused. |
segment_id | string | A static segment (`seg_…`) to add confirmed texters to. |
topic_id | string | An SMS topic to subscribe confirmed texters to. |
Response · 200 fields8 fields
| Field | Type | Description |
|---|---|---|
objectrequired | string | — |
idrequired | string | `sjk_…`. |
number_idrequired | string | The number (`snum_…`) people text the keyword to. |
keywordrequired | string | As you wrote it. A text matches it whatever the case and surrounding punctuation. |
segment_idrequired | string | null | The static segment (`seg_…`) a confirmed texter joins, or null. |
topic_idrequired | string | null | The SMS topic a confirmed texter is subscribed to, or null. |
created_atrequired | string | — |
registration_warningrequired | string | null | Set when the number's carrier registration doesn't list texting a keyword as a way to opt in: carriers can flag sign-ups its registration didn't declare, so add keyword opt-in to its use case and resubmit. Null otherwise. |
200201400401403404409422