Sender IDs

List the active sender IDs assigned to your organisation. Use the sender_id value when sending an SMS to control which name appears on the recipient's device.

Endpoint

GET /v1/bulk-sms/sender-ids/

Authentication: Bearer API key + X-Organisation-Id

Request

No body or query parameters required.

curl https://api.v1.talkntalk.africa/v1/bulk-sms/sender-ids/ \
  -H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Organisation-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6"

Response

200 OK

Only active sender IDs are returned. Each result is one sender name, and its providers array lists every provider/network route that can carry it — a single sender name may be routed through more than one provider.

{
  "count": 1,
  "results": [
    {
      "sender_id": "TextSMS",
      "type": "promotional",
      "is_default": true,
      "providers": [
        {
          "provider": "textsms",
          "network": null
        }
      ]
    }
  ]
}

Field	Type	Description
`count`	integer	Number of distinct sender names returned
`results[].sender_id`	string	The sender name shown on recipient devices. This is your account's actual registered name (e.g. `TextSMS`) — use it verbatim.
`results[].type`	string	`promotional` or `transactional`
`results[].is_default`	boolean	Whether this sender ID is used when none is specified in a send request
`results[].providers`	array	Provider/network routes that can deliver this sender name
`results[].providers[].provider`	string	Underlying SMS provider slug routing this sender ID (e.g. `textsms`)
`results[].providers[].network`	string \| null	Target network (`safaricom`, `airtel`, `telkom`, `faiba`, `other`) — may be `null` when the provider routes across all networks

Field notes from live data

The endpoint returns active sender IDs only; there is no status field on results — anything listed here is usable. If you cache these client-side, do not drop entries for a missing/null status; treat them as usable unless you have an explicit reason not to.

network is frequently null (a provider that routes across all networks). Do not require a specific network value to consider a route valid.

sender_id reflects your account's real registered name, which may differ from examples in these docs. Whatever value the API returns is what recipients see.

The default sender ID (is_default: true) is used automatically when you do not specify a sender_id in your send request. When multiple routes exist, the API selects the best match for the recipient's network automatically.

Code Examples

curl https://api.v1.talkntalk.africa/v1/bulk-sms/sender-ids/ \
  -H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Organisation-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6"

Error Responses

Status	Meaning
`401 Unauthorized`	Missing/invalid API key, or missing `X-Organisation-Id` header

{
  "detail": "Invalid or revoked API key."
}

Get Balance Send SMS