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

# List SMS Numbers

> List all SMS phone numbers in an organization

# List SMS Numbers

Retrieve all SMS phone numbers belonging to an organization, including their assignment status.

## Authentication

<ParamField header="X-API-Key" type="string" required>
  Your API key
</ParamField>

## Query Parameters

<ParamField query="organization_id" type="string" required>
  The organization's unique\_id
</ParamField>

<ParamField query="include_assigned" type="boolean" default="true">
  If `false`, only returns unassigned numbers (available pool)
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="phone_numbers" type="array">
  List of phone number objects
</ResponseField>

<ResponseField name="count" type="integer">
  Total count of phone numbers returned
</ResponseField>

### Phone Number Object

| Field                 | Type    | Description                 |
| --------------------- | ------- | --------------------------- |
| `id`                  | string  | UUID of the phone record    |
| `phone_number`        | string  | E.164 format (+15551234567) |
| `pretty_phone_number` | string  | Formatted for display       |
| `nickname`            | string  | Friendly name (if set)      |
| `is_available`        | boolean | True if unassigned          |
| `assigned_to`         | object  | User info if assigned       |
| `assigned_at`         | string  | ISO timestamp of assignment |
| `created_at`          | string  | ISO timestamp of creation   |

## Example Request

```bash theme={null}
curl -X GET "https://api.teli.ai/v1/sms/phone-numbers?organization_id=org_abc123" \
  -H "X-API-Key: your-api-key"
```

## Example Response

```json theme={null}
{
  "success": true,
  "phone_numbers": [
    {
      "id": "6d7f8580-2c18-4ca9-8917-c9ca121a2c49",
      "phone_number": "+14155551234",
      "pretty_phone_number": "+1 415-555-1234",
      "nickname": "Sales Line",
      "is_available": false,
      "assigned_to": {
        "user_id": "user_xyz789",
        "email": "john@company.com",
        "name": "John Smith"
      },
      "assigned_at": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-10T09:00:00Z"
    },
    {
      "id": "8a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "phone_number": "+14155555678",
      "pretty_phone_number": "+1 415-555-5678",
      "nickname": null,
      "is_available": true,
      "assigned_to": null,
      "assigned_at": null,
      "created_at": "2024-01-12T14:00:00Z"
    }
  ],
  "count": 2,
  "powered_by": "Teli"
}
```

## Get Only Available Numbers

To see only unassigned numbers:

```bash theme={null}
curl -X GET "https://api.teli.ai/v1/sms/phone-numbers?organization_id=org_abc123&include_assigned=false" \
  -H "X-API-Key: your-api-key"
```

Or use the dedicated endpoint:

```bash theme={null}
curl -X GET "https://api.teli.ai/v1/sms/phone-numbers/available?organization_id=org_abc123" \
  -H "X-API-Key: your-api-key"
```

## Related

* [Purchase SMS Number](/partner-api/sms-phone-numbers/purchase)
* [Assign to User](/partner-api/sms-phone-numbers/assign)