# Sender IDs

> List the sender identities on your account and learn which values a send accepts as from — no more guessing why a sender was rejected.

A **sender identity** is a name your account may send as. Sender IDs are captured at
registration and approved on the network-operator side, usually in about 30 minutes; only an
approved SMS identity is accepted as a message's `from`.

## The sender identity object

### Attributes

- **`id`** (`string (uuid)`)
  Identity id. Not what a send takes — use `address`.

- **`channel`** (`string`)
  The channel this identity belongs to. Only `sms` identities are usable as an SMS `from`.

- **`name`** (`string`)
  Display name of the identity.

- **`address`** (`string`)
  **The value you pass as `from`** on [send](/api/sms#send-an-sms) and
  [bulk send](/api/sms#send-bulk-sms).

- **`status`** (`string`)
  Identity state. A send requires `active`.

- **`verification_status`** (`string`)
  Approval state. A send requires `verified`; an identity still in carrier review is not yet
  usable.

An identity is usable as `from` only when all three line up: `channel: sms`,
`status: active`, `verification_status: verified`. Anything else is rejected with
`400 unknown or unapproved sender id` — and a non-`verified` row here is exactly how you
explain a rejected `from` without a support ticket.

```json [Sender identity]
{
  "id": "3c9d1e5f-7a2b-4c8d-9e0f-1a2b3c4d5e6f",
  "channel": "sms",
  "name": "Sendai SMS",
  "address": "Sendai SMS",
  "status": "active",
  "verification_status": "verified"
}
```

## List sender IDs

`GET /api/v1/accounts/{id}/channel-identities`

Lists the sender identities on your account, across every channel.

This is the endpoint behind the hosted MCP server's `list_sender_ids` tool — see
[AI agents](/guides/mcp).

### Path parameters

- **`id`** (`string (uuid)`, required)
  Your account id. It is on the [key create response](/api/api-tokens#create-an-api-key) as
  `account_id`, and on every row of the key listing as `AccountId`.

### Response

Enveloped: `data` is an array of [sender identity objects](#the-sender-identity-object).

### Errors

| Status | When |
| --- | --- |
| `401` | Missing, malformed, or revoked API key. |

```bash [cURL]
curl https://api.sendai.co.zw/api/v1/accounts/2d6f4b8e-1a90-4e21-8b7d-3f1a5c2e9a0c/channel-identities \
  -H "Authorization: Bearer $SENDAI_API_KEY"
```

```js [Node.js]
const accountId = '2d6f4b8e-1a90-4e21-8b7d-3f1a5c2e9a0c'

const res = await fetch(
  `https://api.sendai.co.zw/api/v1/accounts/${accountId}/channel-identities`,
  { headers: { 'Authorization': `Bearer ${process.env.SENDAI_API_KEY}` } },
)

const { data: identities } = await res.json()

const usableAsFrom = identities
  .filter(i => i.channel === 'sms'
    && i.status === 'active'
    && i.verification_status === 'verified')
  .map(i => i.address)
```

```python [Python]
import os
import requests

account_id = "2d6f4b8e-1a90-4e21-8b7d-3f1a5c2e9a0c"

res = requests.get(
    f"https://api.sendai.co.zw/api/v1/accounts/{account_id}/channel-identities",
    headers={"Authorization": f"Bearer {os.environ['SENDAI_API_KEY']}"},
)

usable_as_from = [
    i["address"]
    for i in res.json()["data"]
    if i["channel"] == "sms"
    and i["status"] == "active"
    and i["verification_status"] == "verified"
]
```

```json [200 OK]
{
  "status": "success",
  "message": "request successful",
  "data": [
    {
      "id": "3c9d1e5f-7a2b-4c8d-9e0f-1a2b3c4d5e6f",
      "channel": "sms",
      "name": "Sendai SMS",
      "address": "Sendai SMS",
      "status": "active",
      "verification_status": "verified"
    },
    {
      "id": "8e2f4a6c-1b3d-4e5f-a7c9-2d4e6f8a0b1c",
      "channel": "sms",
      "name": "MyStore",
      "address": "MyStore",
      "status": "active",
      "verification_status": "pending"
    }
  ]
}
```