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

# Purchase number

> Purchase a phone number and add it to your account.

Purchases a phone number that was returned by the [search endpoint](/api-reference/phone-numbers/search-phone-numbers). The platform handles pricing, billing, and provisioning automatically.

<Note>
  You must have a valid payment method on file before purchasing. The purchase creates a monthly subscription that auto-renews.
</Note>

## Endpoint

`POST /user/phone-numbers/purchase`

## Request

<ParamField body="phone_number" type="string" required>
  Phone number to purchase in E.164 format (e.g., `+14155551234`). Must be a number returned from the search endpoint.
</ParamField>

## Response

<ResponseField name="message" type="string">Confirmation message.</ResponseField>

<ResponseField name="data" type="object">
  The purchased phone number details.

  <Expandable title="properties">
    <ResponseField name="id" type="integer">Unique identifier of the phone number.</ResponseField>
    <ResponseField name="phone_number" type="string">Phone number in E.164 format.</ResponseField>
    <ResponseField name="country_code" type="string">ISO country code.</ResponseField>
    <ResponseField name="type" type="string">Phone number type — always `normal` for purchased numbers.</ResponseField>
    <ResponseField name="sms_capable" type="boolean">Whether the number supports SMS.</ResponseField>
  </Expandable>
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://portal.intellixent.ai/api/user/phone-numbers/purchase" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"phone_number": "+14155551234"}'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://portal.intellixent.ai/api/user/phone-numbers/purchase', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ phone_number: '+14155551234' })
  });

  const data = await response.json();
  console.log(data.data.id); // New phone number ID
  ```
</CodeGroup>

```json 201 Created theme={null}
{
  "message": "Phone number purchased successfully.",
  "data": {
    "id": 123,
    "phone_number": "+14155551234",
    "country_code": "US",
    "type": "normal",
    "sms_capable": true
  }
}
```

```json 402 No payment method theme={null}
{
  "error": "No payment method found. Please add a payment method to your account."
}
```

```json 400 Already in use theme={null}
{
  "error": "This phone number is already in use."
}
```

<Warning>
  Purchases are non-refundable. The subscription continues until you [release the number](/api-reference/phone-numbers/release-phone-number).
</Warning>