Request sender

/sender_id_requestsPOST

Registers a new alpha-numeric SMS Sender ID for carrier provisioning.

Authorization

BearerAuth *Bearer <token>

API key generated under Account Settings → API Keys (rk_live_...). Send as header Authorization: Bearer <key>.

Request Bodyapplication/jsonrequired

requested_sender_id *string

Desired alpha-numeric Sender ID (1-11 characters).

Example: "MYBRAND"

carrier?string

Target carrier key (e.g. mtn).

Example: "mtn"

sms_type?"transactional" | "promotional"

Example: "transactional"

transactional_sender_id?string

Example: "MYBRAND"

promotional_sender_id?string

Example: "MYBRANDPROMO"

use_case?string

Example: "OTP delivery and critical customer updates"

Response

200 · Sender ID request submitted

success?boolean

Example: true

data?object

Show properties

id?integer

Example: 5

tracking_id?string

Example: "sid_938472"

requested_sender_id?string

Example: "MYBRAND"

transactional_sender_id?string

Example: "MYBRAND"

promotional_sender_id?string

Example: "MYBRANDPROMO"

sms_type?string

Example: "transactional"

carriers?string[]

sms_types?string[]

carrier_statuses?object

approved_carriers?string[]

rejected_carriers?string[]

status?"pending" | "approved" | "rejected"

Example: "pending"

admin_notes?string | null

approved_at?string (date-time) | null

rejected_at?string (date-time) | null

created_at?string (date-time)

Example: "2026-07-22T14:00:00Z"

updated_at?string (date-time)

Example: "2026-07-22T14:00:00Z"

message?string

Example: "Sender ID registration submitted for processing."

401 · Unauthorized

success *boolean

Example: false

error *string

Human-readable error message explaining the failure reason.

Example: "Recipient not reachable on WhatsApp."

error_code *string

Stable machine-readable error code.

Example: "recipient_not_on_whatsapp"

422 · Missing required fields

success *boolean

Example: false

error *string

Human-readable error message explaining the failure reason.

Example: "Recipient not reachable on WhatsApp."

error_code *string

Stable machine-readable error code.

Example: "recipient_not_on_whatsapp"

Request example

curl -X POST "https://convert.ruut.chat/api/v1/sender_id_requests" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "requested_sender_id": "MYBRAND",
  "carrier": "mtn",
  "sms_type": "transactional",
  "transactional_sender_id": "MYBRAND",
  "promotional_sender_id": "MYBRANDPROMO",
  "use_case": "OTP and critical transactional notifications"
}'

Response example

{
  "success": false,
  "error": "Invalid, expired, or revoked API key.",
  "error_code": "unauthorized"
}