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

# Purchase phone number

> Purchase a dedicated phone number

This endpoint allows you to purchase a phone number that was found using the [search endpoint](https://docs.lacy.ai/api-reference/phone-numbers/search-phone-numbers.md). The platform automatically handles pricing, billing, and provisioning.

> [!NOTE]
>
> You must have a valid payment method on file before purchasing a phone number. The purchase creates a monthly subscription that will auto-renew.

### Request Body

**phone\_number** `string` *required*

The phone number to purchase in E.164 format (e.g., +14155551234). Must be a number returned from the search endpoint.

### Response

**message** `string`

Success message

**data** `object`

The purchased phone number details

**data properties**

**id** `integer`

The unique identifier of the phone number

**phone\_number** `string`

The phone number in E.164 format

**country\_code** `string`

The ISO country code

**type** `string`

The phone number type (always `normal` for purchased numbers)

**sms\_capable** `boolean`

Whether the number supports SMS

```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 400 Already In Use theme={null}
{
  "error": "This phone number is already in use."
}
```

```json 400 Not Available theme={null}
{
  "error": "This phone number is not available for purchase. Please search for available numbers first."
}
```

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

```json 402 Payment Failed theme={null}
{
  "error": "Payment failed. Please update your payment method."
}
```

```json 422 Invalid Format theme={null}
{
  "error": "Unable to parse phone number. Please provide a valid E.164 format number."
}
```

```json 500 Provider Error theme={null}
{
  "error": "Failed to purchase phone number from provider. Please contact support."
}
```

### How It Works

1. **Search** - First use the [search endpoint](https://docs.lacy.ai/api-reference/phone-numbers/search-phone-numbers.md) to find available numbers
2. **Purchase** - Submit the phone number you want to this endpoint
3. **Automatic Processing** - The platform:
   * Validates the number is still available
   * Determines the correct pricing based on country
   * Creates a monthly subscription on your payment method
   * Provisions the number with our telephony provider
   * Creates the phone number record in your account

> [!WARNING]
>
> Phone number purchases are non-refundable. The subscription will continue until you [release the number](https://docs.lacy.ai/api-reference/phone-numbers/release-phone-number.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.