> ## 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.

# Buy Numbers

> Purchase one or more available phone numbers from telephony providers and register them to your organization.

### Headers

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

### Body Parameters

The request body should be an array of objects representing the numbers to purchase.

<ParamField body="[]" type="array[]" required>
  List of numbers to purchase.

  <Expandable title="item properties">
    <ParamField body="number" type="string" required>
      The phone number to purchase.
    </ParamField>

    <ParamField body="provider" type="string" required>
      Telephony provider alias name.

      <Expandable title="options">
        * `eg. timepay, timepay_v2 ..more`
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Response

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

<ResponseField name="data" type="array">
  List of results for each requested number.

  <Expandable title="item properties">
    <ResponseField name="number" type="string">
      The phone number that was processed.
    </ResponseField>

    <ResponseField name="success" type="boolean">
      Indicates if the purchase of this specific number succeeded.
    </ResponseField>

    <ResponseField name="error" type="string">
      Error message if the purchase failed, or `null` if successful.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.agents.timepay.ai/api/v1/numbers/buyNumbers \
    --header 'Authorization: Bearer <your_token>' \
    --header 'Content-Type: application/json' \
    --data '[
    {
      "number": "919876543210",
      "provider": "plivo"
    }
  ]'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true,
    "data": [
      {
        "number": "919876543210",
        "success": true,
        "error": null
      }
    ]
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "success": false,
    "message": "Phone Numbers are required!"
  }
  ```

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

  ```json 500 Server Error theme={null}
  {
    "success": false,
    "message": "Unexpected error at server. Please try again!"
  }
  ```
</ResponseExample>