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

# Setup Inbound Agent

Configure a phone number to route inbound calls to a specific voice AI assistant.

## Overview

This endpoint links an assistant to a phone number so that incoming calls to that number are handled by the specified agent. Use this after you have provisioned a phone number and created an assistant.

## Request

### Headers

| Header         | Value              | Required |
| -------------- | ------------------ | -------- |
| `x-api-key`    | Your API key       | Yes      |
| `Content-Type` | `application/json` | Yes      |
| `accept`       | `*/*`              | No       |

### Request Body

| Field           | Type   | Required | Description                                             |
| --------------- | ------ | -------- | ------------------------------------------------------- |
| `assistantId`   | String | Yes      | ID of the assistant to handle inbound calls             |
| `phoneNumberId` | String | Yes      | ID of the phone number to configure for inbound routing |

### Example Request

```bash theme={null}
curl -X 'POST' \
  'https://api.callhq.ai/api/phone-numbers/inbound/setup' \
  -H 'accept: */*' \
  -H 'x-api-key: your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
  "assistantId": "your_assistant_id",
  "phoneNumberId": "your_phone_number_id"
}'
```

## Response

### Success Response (200)

Inbound agent configured successfully.

### Error Responses

| Status Code | Description                         |
| ----------- | ----------------------------------- |
| 400         | Missing required fields             |
| 404         | Assistant or phone number not found |
| 500         | Failed to setup inbound agent       |

## Use Cases

* **Inbound AI front desk**: Route incoming calls to a support or reception assistant
* **After-hours handling**: Direct callers to an AI agent outside business hours
* **Programmatic setup**: Configure inbound routing as part of your onboarding or deployment workflow

## Related Endpoints

* [List Phone Numbers](/api-reference/phone/list-phone-numbers) - Retrieve available phone numbers and their IDs
* [List Assistants](/api-reference/assistants/list-assistants) - Retrieve assistant IDs to use with inbound routing


## OpenAPI

````yaml post /phone-numbers/inbound/setup
openapi: 3.1.0
info:
  title: OpenAPI Plant Store
  description: >-
    A sample API that uses a plant store as an example to demonstrate features
    in the OpenAPI specification
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.callhq.ai/api
security:
  - apiKeyAuth: []
paths:
  /phone-numbers/inbound/setup:
    post:
      tags:
        - Phone Numbers
      summary: Setup Inbound Agent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - assistantId
                - phoneNumberId
              properties:
                assistantId:
                  type: string
                  description: ID of the assistant to handle inbound calls
                phoneNumberId:
                  type: string
                  description: ID of the phone number to configure for inbound routing
      responses:
        '200':
          description: Inbound agent configured successfully
        '400':
          description: Missing required fields
        '404':
          description: Assistant or phone number not found
        '500':
          description: Failed to setup inbound agent
      security:
        - apiKeyAuth: []
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````