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

# List Numbers

> Search for available phone numbers across different telephony providers.

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication (e.g., `Bearer <your_token>`).
</ParamField>

### Query Parameters

<ParamField query="provider" type="string" default="timepay">
  Telephony provider alias name.
</ParamField>

<ParamField query="country_iso" type="string" default="IN">
  Two-letter ISO country code.
</ParamField>

<ParamField query="limit" type="integer" default={10}>
  Maximum number of results to return.
</ParamField>

<ParamField query="page" type="integer" default={1}>
  The page number for pagination.
</ParamField>

<ParamField query="prefix" type="string">
  **Limited support:** Pattern or prefix to search for within the phone numbers.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful.
</ResponseField>

<ResponseField name="status" type="integer">
  HTTP status code of the response.
</ResponseField>

<ResponseField name="data" type="array">
  List of available phone numbers.

  <Expandable title="item properties">
    <ResponseField name="number" type="string">
      The available phone number in E.164 format.
    </ResponseField>

    <ResponseField name="sms_enabled" type="boolean">
      Indicates if SMS is supported on this number.
    </ResponseField>

    <ResponseField name="voice_enabled" type="boolean">
      Indicates if voice calls are supported on this number.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="page" type="integer">
  The current page number (returned for Vobiz and Plivo).
</ResponseField>

<ResponseField name="totalPages" type="integer">
  Total number of pages available.
</ResponseField>

<ResponseField name="totalCount" type="integer">
  Total number of available numbers matching the query.
</ResponseField>

<ResponseField name="message" type="string">
  Descriptive response message.
</ResponseField>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true,
    "status": 200,
    "data": [
      {
        "number": "+919876543210",
        "sms_enabled": false,
        "voice_enabled": true
      },
      {
        "number": "+918765432109",
        "sms_enabled": false,
        "voice_enabled": true
      }
    ],
    "page": 1,
    "totalPages": 1,
    "totalCount": 2,
    "message": "Found Available Phone Numbers"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "success": false,
    "status": 404,
    "message": "No Available Numbers Found for this provider!"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "success": false,
    "error": "Unauthorized",
    "message": "Missing or invalid authorization header"
  }
  ```

  ```json 500 Server Error theme={null}
  {
    "success": false,
    "status": 500,
    "message": "Failed to get numbers"
  }
  ```
</ResponseExample>