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

# Phone

> Manage numbers, contacts, assistant allocation, and scheduled calls.

# Phone

Use Phone endpoints for telephony resource management.

## Authentication & scope

* Header: `X-API-Key: YOUR_API_KEY`
* Read operations: `phone:read`
* Write operations: `phone:write`
* Use **API Reference** for Try-it on each phone endpoint.

## `GET /v1/phone/purchases`

Lists purchased numbers for your organization.

<CodeGroup>
  ```bash Bash theme={null}
  curl -X GET "https://api.indigenius.ai/v1/phone/purchases" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript Node theme={null}
  const response = await fetch('https://api.indigenius.ai/v1/phone/purchases', {
    headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY },
  });
  console.log(await response.json());
  ```

  ```python Python theme={null}
  import requests
  response = requests.get(
      "https://api.indigenius.ai/v1/phone/purchases",
      headers={"X-API-Key": "YOUR_API_KEY"},
      timeout=30,
  )
  print(response.status_code)
  print(response.json())
  ```
</CodeGroup>

### Common status codes

* `200` success
* `403` missing `phone:read`
* `500` server error

## `GET /v1/phone/contacts/{id}`

Lists contacts for a purchased number.

<CodeGroup>
  ```bash Bash theme={null}
  curl -X GET "https://api.indigenius.ai/v1/phone/contacts/665e4a34c65bb95f2f2d72e4?page=1&pageSize=10" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript Node theme={null}
  const phonePurchaseId = '665e4a34c65bb95f2f2d72e4';
  const response = await fetch(
    `https://api.indigenius.ai/v1/phone/contacts/${phonePurchaseId}?page=1&pageSize=10`,
    { headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY } },
  );
  console.log(await response.json());
  ```

  ```python Python theme={null}
  import requests
  phone_purchase_id = "665e4a34c65bb95f2f2d72e4"
  response = requests.get(
      f"https://api.indigenius.ai/v1/phone/contacts/{phone_purchase_id}?page=1&pageSize=10",
      headers={"X-API-Key": "YOUR_API_KEY"},
      timeout=30,
  )
  print(response.status_code)
  print(response.json())
  ```
</CodeGroup>

### Common status codes

* `200` success
* `403` missing `phone:read`
* `404` purchase not found
* `500` server error

## `POST /v1/phone/allocate-assistant`

Assigns inbound/outbound agents to a number. Body is DTO-accurate to `PhoneAssistantDTO`.

<CodeGroup>
  ```bash Bash theme={null}
  curl -X POST "https://api.indigenius.ai/v1/phone/allocate-assistant" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "inboundAssistantId": "665e4a34c65bb95f2f2d72e2",
      "outboundAssistantId": "665e4a34c65bb95f2f2d72e3",
      "id": "665e4a34c65bb95f2f2d72e4",
      "message": "Hello, this call may be recorded."
    }'
  ```

  ```javascript Node theme={null}
  const response = await fetch(
    'https://api.indigenius.ai/v1/phone/allocate-assistant',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.INDIGENIUS_API_KEY,
      },
      body: JSON.stringify({
        inboundAssistantId: '665e4a34c65bb95f2f2d72e2',
        outboundAssistantId: '665e4a34c65bb95f2f2d72e3',
        id: '665e4a34c65bb95f2f2d72e4',
        message: 'Hello, this call may be recorded.',
      }),
    },
  );
  console.log(await response.json());
  ```

  ```python Python theme={null}
  import requests
  payload = {
      "inboundAssistantId": "665e4a34c65bb95f2f2d72e2",
      "outboundAssistantId": "665e4a34c65bb95f2f2d72e3",
      "id": "665e4a34c65bb95f2f2d72e4",
      "message": "Hello, this call may be recorded.",
  }
  response = requests.post(
      "https://api.indigenius.ai/v1/phone/allocate-assistant",
      headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
      json=payload,
      timeout=30,
  )
  print(response.status_code)
  print(response.json())
  ```
</CodeGroup>

### Common status codes

* `200` success
* `400` validation error
* `403` missing `phone:write`
* `404` resource not found
* `500` server error

## `POST /v1/phone/schedule-call`

Schedules outbound calls. Body is DTO-accurate to `ScheduleCallDTO`.

<CodeGroup>
  ```bash Bash theme={null}
  curl -X POST "https://api.indigenius.ai/v1/phone/schedule-call" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Morning outreach",
      "contacts_id": ["665e4a34c65bb95f2f2d72e5", "665e4a34c65bb95f2f2d72e6"],
      "phone_id": "665e4a34c65bb95f2f2d72e4",
      "message": "Hi, just checking in on your request.",
      "dates": ["2026-06-15T09:00:00.000Z"],
      "timezone": "GMT_plus_1"
    }'
  ```

  ```javascript Node theme={null}
  const response = await fetch(
    'https://api.indigenius.ai/v1/phone/schedule-call',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.INDIGENIUS_API_KEY,
      },
      body: JSON.stringify({
        name: 'Morning outreach',
        contacts_id: ['665e4a34c65bb95f2f2d72e5', '665e4a34c65bb95f2f2d72e6'],
        phone_id: '665e4a34c65bb95f2f2d72e4',
        message: 'Hi, just checking in on your request.',
        dates: ['2026-06-15T09:00:00.000Z'],
        timezone: 'GMT_plus_1',
      }),
    },
  );
  console.log(await response.json());
  ```

  ```python Python theme={null}
  import requests
  payload = {
      "name": "Morning outreach",
      "contacts_id": ["665e4a34c65bb95f2f2d72e5", "665e4a34c65bb95f2f2d72e6"],
      "phone_id": "665e4a34c65bb95f2f2d72e4",
      "message": "Hi, just checking in on your request.",
      "dates": ["2026-06-15T09:00:00.000Z"],
      "timezone": "GMT_plus_1",
  }
  response = requests.post(
      "https://api.indigenius.ai/v1/phone/schedule-call",
      headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
      json=payload,
      timeout=30,
  )
  print(response.status_code)
  print(response.json())
  ```
</CodeGroup>

### `201 Created`

```json theme={null}
{
  "status": true,
  "message": "Call scheduled",
  "id": "665e4a34c65bb95f2f2d72e5"
}
```

### Common status codes

* `201` scheduled
* `400` validation error
* `403` missing `phone:write`
* `404` resource not found
* `500` server error