List and Register SMS Sender IDs — Hany API Reference

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

string

Indicates the outcome of the request. Either "success" or "error".

array

An array of Sender ID objects associated with your account.

string

Unique identifier for the Sender ID record.

string

The Sender ID string as it appears to message recipients.

string

Approval status of the Sender ID. One of pending, approved, or rejected.

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

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

string

Indicates the outcome of the request. Either "success" or "error".

object

The newly created Sender ID record.

string

Unique identifier for the new Sender ID record.

string

The Sender ID string as submitted.

string

Always "pending" immediately after submission. Updates to "approved" or "rejected" after review.

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"

import requests

BASE_URL = "https://api.hany.tools/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# List all Sender IDs
list_response = requests.get(f"{BASE_URL}/sms/sender-ids", headers=HEADERS)
sender_ids = list_response.json()["data"]
approved = [sid for sid in sender_ids if sid["status"] == "approved"]
print(approved)

# Register a new Sender ID
register_response = requests.post(
    f"{BASE_URL}/sms/sender-ids",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={"name": "NewBrand"},
)
new_sender_id = register_response.json()
print(new_sender_id["data"]["id"])      # "sid_002"
print(new_sender_id["data"]["status"])  # "pending"

Overview

SMS

Webhooks

List and Register SMS Sender IDs — Hany API Reference

List Sender IDs

Endpoint

Request

Response

200 — Success

Response Fields

Register a Sender ID

Endpoint

Request

Request Body Parameters

Response

201 — Created

Response Fields

Code Examples

​List Sender IDs

​Endpoint

​Request

​Response

​200 — Success

​Response Fields

​Register a Sender ID

​Endpoint

​Request

​Request Body Parameters

​Response

​201 — Created

​Response Fields

​Code Examples

List Sender IDs

Endpoint

Request

Response

200 — Success

Response Fields

Register a Sender ID

Endpoint

Request

Request Body Parameters

Response

201 — Created

Response Fields

Code Examples