Sender IDs API

Register the names your SMS comes from, see where each one is in review, and pick the project's default. Sailup reviews every new sender ID.

GET/senders/

List sender IDs

List the sender IDs registered on this project, newest first. The project comes from the API key. An unknown status filter returns 400 rather than an empty list.

Query Parameters

statusstring

Only sender IDs with this status: pending, active, rejected or inactive.

pageinteger

Page number to return. Defaults to 1.

page_sizeinteger

Number of sender IDs per page.

200 OKResponse
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "6f1d2c9e-3b7a-4e0f-9a51-2d8c4b7e1f03",
      "name": "AcmeShop",
      "use_case": "transactional",
      "sample_message": "AcmeShop: your order #1042 has shipped.",
      "notes": "",
      "status": "active",
      "status_reason": "",
      "is_default": false,
      "reviewed_at": "2026-11-04T09:12:00Z",
      "created_at": "2026-11-03T15:40:00Z"
    }
  ]
}
400 Bad RequestUnknown status
{
  "message": "Validation failed",
  "errors": [
    "Select a valid choice. bogus is not one of the available choices."
  ]
}
POST/senders/

Register a sender ID

Submit a sender ID for review. It is created as pending and can't send until Sailup approves it. Sender IDs registered through the API are for Ghana. Registering sends no webhook; the review decision does.

Body Parameters

namestringrequired

The name recipients see. Letters, numbers and spaces, up to 11 characters.

use_casestringrequired

transactional or promotional.

sample_messagestringrequired

An example of what you will send from this name, up to 500 characters. Sailup reviews it alongside the name.

notesstring

Anything that helps the review, such as how the name relates to your business. Up to 500 characters.

Request Body
{
  "name": "AcmeShop",
  "use_case": "transactional",
  "sample_message": "AcmeShop: your order #1042 has shipped.",
  "notes": "We trade as AcmeShop; our registered name is Acme Retail Ltd."
}
201 CreatedCreated
{
  "id": "6f1d2c9e-3b7a-4e0f-9a51-2d8c4b7e1f03",
  "name": "AcmeShop",
  "use_case": "transactional",
  "sample_message": "AcmeShop: your order #1042 has shipped.",
  "notes": "We trade as AcmeShop; our registered name is Acme Retail Ltd.",
  "status": "pending",
  "status_reason": "",
  "is_default": false,
  "reviewed_at": null,
  "created_at": "2026-11-03T15:40:00Z"
}
400 Bad RequestValidation failed
{
  "message": "Validation failed",
  "errors": [
    "name: Ensure this field has no more than 11 characters.",
    "sample_message: This field is required."
  ]
}
400 Bad RequestInvalid name
{
  "error": "invalid_sender_id_name",
  "message": "Sender ID may only contain letters, numbers and spaces."
}
GET/senders/{sender_id}/

Get a sender ID

Get one sender ID by its ID. Returns 404 for an unknown ID or a sender ID that belongs to another project.

Path Parameters

sender_idstringrequired

The sender ID's id, from the list, the register response or a webhook's data.id.

200 OKResponse
{
  "id": "6f1d2c9e-3b7a-4e0f-9a51-2d8c4b7e1f03",
  "name": "AcmeShop",
  "use_case": "transactional",
  "sample_message": "AcmeShop: your order #1042 has shipped.",
  "notes": "",
  "status": "active",
  "status_reason": "",
  "is_default": false,
  "reviewed_at": "2026-11-04T09:12:00Z",
  "created_at": "2026-11-03T15:40:00Z"
}
404 Not FoundNot found
{
  "message": "Sender ID not found."
}
POST/senders/{sender_id}/set-default/

Set the default sender ID

Make an active sender ID the project's default. Takes no body. Returns 400 if the sender ID is not active, and 404 for an unknown ID.

Path Parameters

sender_idstringrequired

The id of an active sender ID.

200 OKResponse
{
  "id": "6f1d2c9e-3b7a-4e0f-9a51-2d8c4b7e1f03",
  "name": "AcmeShop",
  "use_case": "transactional",
  "sample_message": "AcmeShop: your order #1042 has shipped.",
  "notes": "",
  "status": "active",
  "status_reason": "",
  "is_default": true,
  "reviewed_at": "2026-11-04T09:12:00Z",
  "created_at": "2026-11-03T15:40:00Z"
}
400 Bad RequestNot active
{
  "error": "sender_id_not_active",
  "message": "Only an active Sender ID can be set as default."
}
404 Not FoundNot found
{
  "message": "Sender ID not found."
}

The sender ID object

Every endpoint on this page returns this shape, and so does the data of a sender_id webhook.

statusstring

pending while it waits for review, active once approved, rejected, or inactive after Sailup stops it. Only active sender IDs can send.

status_reasonstring

Why it was rejected or deactivated. Empty for pending and active.

is_defaultboolean

Whether this is the project's default sender ID. Cleared when the sender ID is deactivated, and not restored when it is reactivated.

reviewed_atstring | null

When Sailup approved or rejected it. null while pending.

notesstring

The notes you registered it with. "" when none.

Errors

sender_id_exists400

A sender ID with this name is already registered on the project.

sender_id_deactivated400

A sender ID with this name was deactivated by Sailup.

invalid_sender_id_name400

The name has characters other than letters, numbers and spaces.

sender_id_not_active400

Only an active sender ID can be set as the default.

401auth

A missing or revoked API key, or a suspended account.