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.
/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
statusstringOnly sender IDs with this status: pending, active, rejected or inactive.
pageintegerPage number to return. Defaults to 1.
page_sizeintegerNumber of sender IDs per page.
{
"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"
}
]
}{
"message": "Validation failed",
"errors": [
"Select a valid choice. bogus is not one of the available choices."
]
}/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
namestringrequiredThe name recipients see. Letters, numbers and spaces, up to 11 characters.
use_casestringrequiredtransactional or promotional.
sample_messagestringrequiredAn example of what you will send from this name, up to 500 characters. Sailup reviews it alongside the name.
notesstringAnything that helps the review, such as how the name relates to your business. Up to 500 characters.
{
"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."
}{
"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"
}{
"message": "Validation failed",
"errors": [
"name: Ensure this field has no more than 11 characters.",
"sample_message: This field is required."
]
}{
"error": "invalid_sender_id_name",
"message": "Sender ID may only contain letters, numbers and spaces."
}/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_idstringrequiredThe sender ID's id, from the list, the register response or a webhook's data.id.
{
"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"
}{
"message": "Sender ID not found."
}/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_idstringrequiredThe id of an active sender ID.
{
"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"
}{
"error": "sender_id_not_active",
"message": "Only an active Sender ID can be set as default."
}{
"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.
statusstringpending while it waits for review, active once approved, rejected, or inactive after Sailup stops it. Only active sender IDs can send.
status_reasonstringWhy it was rejected or deactivated. Empty for pending and active.
is_defaultbooleanWhether this is the project's default sender ID. Cleared when the sender ID is deactivated, and not restored when it is reactivated.
reviewed_atstring | nullWhen Sailup approved or rejected it. null while pending.
notesstringThe notes you registered it with. "" when none.
Errors
sender_id_exists400A sender ID with this name is already registered on the project.
sender_id_deactivated400A sender ID with this name was deactivated by Sailup.
invalid_sender_id_name400The name has characters other than letters, numbers and spaces.
sender_id_not_active400Only an active sender ID can be set as the default.
401authA missing or revoked API key, or a suspended account.