Sender IDs

The name a recipient sees as the sender of your SMS. You need at least one approved sender ID before the API will send a message.

Why you need one

Mobile network operators in Ghana only deliver SMS from sender names they have approved for a specific business. Each sender ID is reviewed by the network operator and registered to your account, and the from field of POST /v1/sms must be one of yours. The match ignores case, and the registered spelling is used on the message.

Platform names such as Kpododo, and names made to look like them (for example KP0D0D0), are reserved and cannot be requested.

How to request one

Request sender IDs in the dashboard under Account > Sender IDs > Request. There is no API for this step. You will be asked for:

  • the name: 3 to 11 characters of letters, digits and single spaces, with at least one letter (spaces count towards the 11);
  • what you will send, and a sample message;
  • the business name and a contact;
  • supporting documents: your business registration certificate and a letter of authorisation.

The network operator reviews the request. This usually takes about 48 hours.

Statuses

StatusMeaning
pendingWe have received the request and have not yet sent it to the network operator.
submittedWith the network operator for review, typically about 48 hours.
approvedApproved. Check usable before sending: it may still be activating on the network for a few minutes.
rejectedNot approved. rejection_reason says why. You can request again.
revokedNo longer usable. Request again if you need it.
cancelledThe request was cancelled. Request again if you need it.

Check which sender IDs you can use

GET /v1/sender-ids lists every sender ID on your account. Use the usable field to decide: it is true only when the sender ID is approved and active on the network (ready_to_send). An approved sender ID that is not yet ready is still being activated, which takes minutes.

curl https://api.kpododo.com/v1/sender-ids \
  -H "Authorization: Bearer $KPODODO_API_KEY"
Response
{
  "data": [
    {
      "id": "uuid",
      "name": "MyShop",
      "status": "approved",
      "usable": true,
      "ready_to_send": true,
      "rejection_reason": null,
      "created_at": "...",
      "approved_at": "..."
    },
    {
      "id": "uuid",
      "name": "MyShopGH",
      "status": "submitted",
      "usable": false,
      "ready_to_send": false,
      "rejection_reason": null,
      "created_at": "...",
      "approved_at": null
    }
  ]
}

Sender errors

When POST /v1/sms refuses a sender, nothing is sent or charged. Branch on code:

HTTPCodeWhat it meansWhat to do
400SENDER_REQUIREDThe from field is empty.Pass one of your sender IDs.
403SENDER_NOT_OWNEDThe name is not registered to your account, or it is a reserved platform name or look-alike.Request your own sender ID.
403SENDER_NOT_APPROVEDIt is yours, but pending, submitted, rejected, revoked or cancelled.Wait for approval, or request again.
403SENDER_NOT_READYApproved, but still being activated on the network.Retry in a few minutes.