Set up SMS and approved Sender IDs

An SMS Sender ID identifies your business in supported SMS delivery routes. Convert requires an approved sender appropriate to the route it selects. Submitting a Sender ID request is not the same as carrier approval.

Request a Sender ID

Use the Sender ID settings to submit the requested business and sender details. Follow the fields and route choices displayed in Convert; different message types can need separate approvals. Check the request status before trying a live send.

The customer API supports requests and status queries:

POST /api/v1/sender_id_requests requires sender_ids:write.
GET /api/v1/sender_id_requests and GET /api/v1/sender_id_requests/:id require sender_ids:read.

See the API reference for the request schema. Carrier-partner update endpoints are not ordinary customer endpoints and should not be used with a customer Bearer key.

Choose the message flow

Transactional messages include verification codes and service alerts. The single-message API uses the transactional send flow and selects the approved transactional Sender ID. Promotional campaigns use the campaign purpose and route configuration.

Keep content within the selected purpose. Setting a purpose field does not turn promotional content into a service notification or bypass sender approval, consent, suppression, or sending-window controls.

Send SMS explicitly

Set channel: "sms" with an international recipient phone number and message. A raw email address cannot be used on SMS or phone-based Smart routing.

1234567{
  "to": "+2348012345678",
  "channel": "sms",
  "purpose": "otp",
  "message": "Your verification code is 638492",
  "test": true
}

Include an Idempotency-Key in the HTTP request even when validating. For a real new OTP or changed recipient, create a new key. See OTP protection.

Diagnose failures

sender_id_required: no approved effective transactional sender is available.
Invalid recipient: store a full international phone number and validate it before submitting.
Insufficient balance or plan limit: inspect the wallet/allowance before creating another request.
Provider failure or delayed receipt: inspect the existing send and delivery event; provider acceptance does not guarantee handset delivery.

Next: review routing, messages, or billing.

Smart routing can select SMS. It still requires sender readiness and available funds; fallback is not an exemption from SMS rules.