Skip to main content
Manage your Sender IDs programmatically via the API. A Sender ID is the name or number that recipients see as the message sender. All Sender IDs must be approved before you can use them to send messages.
All requests must include the Authorization: Bearer YOUR_API_KEY header. Requests and responses use Content-Type: application/json.

​
List Sender IDs

​
Endpoint

GET https://api.hany.tools/v1/sms/sender-ids
Returns all Sender IDs registered to your account, including their current approval status.

​
Request

curl https://api.hany.tools/v1/sms/sender-ids \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

​
200 — Success

{
  "status": "success",
  "data": [
    {
      "id": "sid_001",
      "name": "YourBrand",
      "status": "approved",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

​
Response Fields

​
status
string
Indicates the outcome of the request. Either "success" or "error".
​
data
array
An array of Sender ID objects associated with your account.
​
data[].id
string
Unique identifier for the Sender ID record.
​
data[].name
string
The Sender ID string as it appears to message recipients.
​
data[].status
string
Approval status of the Sender ID. One of pending, approved, or rejected.
​
data[].created_at
string
ISO 8601 timestamp indicating when the Sender ID was submitted.

​
Register a Sender ID

​
Endpoint

POST https://api.hany.tools/v1/sms/sender-ids
Submit a new Sender ID for approval. Once submitted, the Sender ID enters a review queue and cannot be used for sending until its status is "approved".

​
Request

curl -X POST https://api.hany.tools/v1/sms/sender-ids \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "NewBrand"
  }'

​
Request Body Parameters

​
name
string
required
The Sender ID you want to register. Maximum 11 alphanumeric characters (letters and numbers only; no spaces or special characters). This is the name recipients will see when they receive your messages.

​
Response

​
201 — Created

{
  "status": "success",
  "data": {
    "id": "sid_002",
    "name": "NewBrand",
    "status": "pending",
    "created_at": "2024-06-01T08:00:00Z"
  }
}

​
Response Fields

​
status
string
Indicates the outcome of the request. Either "success" or "error".
​
data
object
The newly created Sender ID record.
​
data.id
string
Unique identifier for the new Sender ID record.
​
data.name
string
The Sender ID string as submitted.
​
data.status
string
Always "pending" immediately after submission. Updates to "approved" or "rejected" after review.
​
data.created_at
string
ISO 8601 timestamp of when the Sender ID was submitted.
Sender IDs require manual approval, which typically takes 1–3 business days. You cannot use a Sender ID with status: "pending" or status: "rejected" to send messages — attempts will return a 400 invalid_sender_id error.

​
Code Examples

// List all Sender IDs
const listResponse = await fetch("https://api.hany.tools/v1/sms/sender-ids", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
const { data: senderIds } = await listResponse.json();
const approved = senderIds.filter((sid) => sid.status === "approved");
console.log(approved);

// Register a new Sender ID
const registerResponse = await fetch("https://api.hany.tools/v1/sms/sender-ids", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "NewBrand" }),
});
const newSenderId = await registerResponse.json();
console.log(newSenderId.data.id);     // "sid_002"
console.log(newSenderId.data.status); // "pending"