Register a Sender ID

Goal: get your own SMS Sender ID (the name or number recipients see as the message sender) approved and in Active status, so you can send under your brand instead of the generic default.

Prerequisites:

• Access to the Client portal at https://client.routeon.io/.
• An API key with the omni-api scope (to check sender status via the API).

You do not need a registered Sender ID for a first test send — without one, a generic default sender is used. Register your own sender for production and branded traffic.

Steps

1. Create the sender in the portal

1. Log in to the Client portal and open Assets → Sender IDs.
2. Create a new sender and submit it for approval.

2. Wait for approval

Approval times vary by country and operator — start this step early, before you plan to go live. Approval is granted per destination: a sender approved for one country/operator is not automatically usable everywhere.

Also make sure the destination itself is open for your account — the operators you want to reach must be enabled and routed. If in doubt, check with your account manager.

3. Check the sender status via the API

The API exposes a read-only view of your senders. Creation and edits always happen in the portal.

curl -sS -H "X-API-Key: <API_KEY>" "https://client.routeon.io/api/v1/senders"

Expected response:

{
  "error": false,
  "data": [
    {
      "senderId": "Routeon",
      "displayName": "SMS Sender",
      "channel": 1,
      "status": 2,
      "webhookUrl": ""
    }
  ]
}

Status codes returned in status:

Code	Status	Can send?	Meaning
-1	Blocked	No	Blocked by the system owner
0	Draft	No	Saved in the portal but not submitted for approval
1	In tests	Limited	Approved for testing, usually with restricted recipients
2	Active	Yes	Fully approved and operational

Only a sender with channel: 1 (SMS) and status: 2 (Active) can be used in the senderId field of POST /messages and in broadcast flow steps.

There is no webhook for approval status changes — poll GET /senders (or check the portal) until the sender shows status: 2.

4. Use the sender

Pass the senderId value exactly as returned by GET /senders:

curl -sS -X POST "https://client.routeon.io/api/v1/messages" 
  -H "X-API-Key: <API_KEY>" 
  -H "Content-Type: application/json" 
  -d '{
    "contact": "905063565285",
    "channel": 1,
    "senderId": "Routeon",
    "payload": { "text": "First message from our own sender" }
  }'

Verify

• GET /senders shows your sender with channel: 1 and status: 2.
• A test send with that senderId returns 202 and later reaches mdnStatus: "DELIVRD" in GET /edrs (or status: "delivered" in the messageStatus webhook).
• The recipient’s handset shows your Sender ID as the message sender.

Common failures

Symptom	Cause	Fix
Message accepted (202) but EDR shows mdnStatus: "REJECTD"	Sender ID not approved or not Active for the destination	Check GET /senders — the sender must be status: 2. Wait for approval or use the generic default sender
REJECTD even though the sender is Active	Destination (country/operator) closed for your account, or the sender is not approved for that destination	Confirm with your account manager that the required operator is enabled and routed
REJECTD on every send	The API key is missing the required scope, or the sender is not allowed for that key	Verify the key has the omni-api scope and is allowed to use this sender
404 from POST /messages	senderId does not exist for your account, or belongs to a different channel	Use a senderId returned by GET /senders with channel: 1
Sender stuck in a non-Active state for a long time	Approval is pending on the operator side	Approval times vary by country and operator; contact your account manager or support if it stalls