> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hany.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# List and Register SMS Sender IDs — Hany API Reference

> GET /sms/sender-ids lists all Sender IDs on your account. POST /sms/sender-ids submits a new name for approval, which takes 1–3 business days.

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.

<Note>
  All requests must include the `Authorization: Bearer YOUR_API_KEY` header. Requests and responses use `Content-Type: application/json`.
</Note>

***

## 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

```bash theme={null}
curl https://api.hany.tools/v1/sms/sender-ids \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

#### 200 — Success

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

### Response Fields

<ResponseField name="status" type="string">
  Indicates the outcome of the request. Either `"success"` or `"error"`.
</ResponseField>

<ResponseField name="data" type="array">
  An array of Sender ID objects associated with your account.

  <ResponseField name="data[].id" type="string">
    Unique identifier for the Sender ID record.
  </ResponseField>

  <ResponseField name="data[].name" type="string">
    The Sender ID string as it appears to message recipients.
  </ResponseField>

  <ResponseField name="data[].status" type="string">
    Approval status of the Sender ID. One of `pending`, `approved`, or `rejected`.
  </ResponseField>

  <ResponseField name="data[].created_at" type="string">
    ISO 8601 timestamp indicating when the Sender ID was submitted.
  </ResponseField>
</ResponseField>

***

## 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

```bash theme={null}
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

<ParamField body="name" type="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.
</ParamField>

### Response

#### 201 — Created

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

### Response Fields

<ResponseField name="status" type="string">
  Indicates the outcome of the request. Either `"success"` or `"error"`.
</ResponseField>

<ResponseField name="data" type="object">
  The newly created Sender ID record.

  <ResponseField name="data.id" type="string">
    Unique identifier for the new Sender ID record.
  </ResponseField>

  <ResponseField name="data.name" type="string">
    The Sender ID string as submitted.
  </ResponseField>

  <ResponseField name="data.status" type="string">
    Always `"pending"` immediately after submission. Updates to `"approved"` or `"rejected"` after review.
  </ResponseField>

  <ResponseField name="data.created_at" type="string">
    ISO 8601 timestamp of when the Sender ID was submitted.
  </ResponseField>
</ResponseField>

<Warning>
  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.
</Warning>

## Code Examples

<CodeGroup>
  ```javascript JavaScript theme={null}
  // 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"
  ```

  ```python Python theme={null}
  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"
  ```
</CodeGroup>