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

# Create Custom Dialing Pool

> Create a new custom dialing pool with phone numbers for optimized call routing.

<Info>
  **Enterprise Feature** - Custom dialing is only available on Enterprise plans. Contact your Bland representative for access.
</Info>

Custom dialing pools allow you to create collections of phone numbers that will be automatically selected based on geographic proximity to optimize call pickup rates.

### Headers

<ParamField header="authorization" type="string" required>
  Your API key for authentication.
</ParamField>

### Body

<ParamField body="phone_numbers" type="array" required>
  Array of phone numbers to include in the pool. All numbers must be valid US phone numbers with +1 prefix.

  **Format**: Each phone number must be exactly 12 characters: `+1` followed by 10 digits.

  **Example**: `["+12345678901", "+19876543210"]`
</ParamField>

<ParamField body="encrypted_key" type="string">
  Optional UUID of Twilio credentials to associate with this pool. If provided, must be valid credentials that belong to your account.

  **Format**: UUID format (e.g., `550e8400-e29b-41d4-a716-446655440000`)

  Learn more about BYOT [here](/tutorials/custom-twilio).
</ParamField>

### Response

<ResponseField name="status" type="string">
  Can be `success` or `error`.
</ResponseField>

<ResponseField name="data" type="object">
  The created custom dialing pool object (present only if status is `success`).

  <Expandable title="data properties">
    <ResponseField name="id" type="string">
      Unique identifier for the pool.
    </ResponseField>

    <ResponseField name="owner_id" type="string">
      Organization ID that owns this pool.
    </ResponseField>

    <ResponseField name="phone_numbers" type="array">
      Array of phone numbers in the pool.
    </ResponseField>

    <ResponseField name="encrypted_key" type="string">
      UUID of associated Twilio credentials (or null if none).
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Timestamp when the pool was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="errors" type="array">
  Array of error objects (present only if status is `error`).

  <Expandable title="error object properties">
    <ResponseField name="error" type="string">
      Error code indicating the type of error.
    </ResponseField>

    <ResponseField name="message" type="string">
      Human-readable error message.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://us.api.bland.ai/v1/custom-dialing-pools" \
    -H "Authorization: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "phone_numbers": ["+12345678901", "+19876543210", "+15551234567"],
      "encrypted_key": "550e8400-e29b-41d4-a716-446655440000"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://us.api.bland.ai/v1/custom-dialing-pools', {
    method: 'POST',
    headers: {
      'Authorization': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      phone_numbers: ['+12345678901', '+19876543210', '+15551234567'],
      encrypted_key: '550e8400-e29b-41d4-a716-446655440000'
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  url = "https://us.api.bland.ai/v1/custom-dialing-pools"
  headers = {
      "Authorization": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  data = {
      "phone_numbers": ["+12345678901", "+19876543210", "+15551234567"],
      "encrypted_key": "550e8400-e29b-41d4-a716-446655440000"
  }

  response = requests.post(url, headers=headers, json=data)
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "status": "success",
    "data": {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "owner_id": "550e8400-e29b-41d4-a716-446655440002",
      "phone_numbers": ["+12345678901", "+19876543210", "+15551234567"],
      "encrypted_key": "550e8400-e29b-41d4-a716-446655440000",
      "created_at": "2024-01-15T10:30:00Z"
    },
    "errors": null
  }
  ```

  ```json Error Response - Invalid Phone Numbers theme={null}
  {
    "status": "error",
    "data": null,
    "errors": [
      {
        "error": "INVALID_PHONE_NUMBERS",
        "message": "All phone numbers must be valid US numbers with +1 prefix"
      }
    ]
  }
  ```

  ```json Error Response - Invalid Credentials theme={null}
  {
    "status": "error",
    "data": null,
    "errors": [
      {
        "error": "INVALID_CREDENTIALS",
        "message": "Twilio credentials not found or do not belong to your account"
      }
    ]
  }
  ```
</ResponseExample>

## Usage with Calls

Once you've created a custom dialing pool, you can use it in your call requests by specifying the `custom_dialing` parameter:

```json theme={null}
{
  "phone_number": "+12345678901",
  "task": "Your call task here",
  "custom_dialing": "550e8400-e29b-41d4-a716-446655440001"
}
```

## The system will automatically select the most geographically appropriate phone number from your pool to maximize pickup rates.

Docs for agents: [llms.txt](/llms.txt)