---
title: "Buy a phone number"
method: POST
path: "/v1/phone-number"
tags: ["Phone Number"]
---

# Buy a phone number

`POST /v1/phone-number`

## Request

- Base URL: `https://api.roark.ai`
- URL: `https://api.roark.ai/v1/phone-number`
- Auth: HTTP bearer

Buys a number from the carrier for this project: the one named by e164, or one Roark picks to match autoPick (trying the next match if the carrier has just sold one). Free inside the plan allowance; past it, the first month of rent is charged now and monthly after that.

## Request body

- CreatePhoneNumberInput: Input for buying a phone number
  - `e164` string: The number to buy, in E.164 format, from a search result. Give this or autoPick.
  - `autoPick` PhoneNumberAutoPickInput: What the number Roark picks should look like. Roark buys the first matching number the carrier will sell, preferring the area code and falling back to a nearby one.
    - `country` 'US' | 'CA': ISO 3166-1 alpha-2 country of the number: US or CA
    - `numberType` 'LOCAL' | 'TOLL_FREE': LOCAL for a number in an area code, TOLL_FREE for one from the shared US and Canada toll-free pool
    - `areaCode` string: Three-digit area code, or a toll-free prefix such as 800. When it has no numbers, nearby ones are returned instead, flagged bestEffort.
    - `contains` string: Digits or letters the number must contain (1 to 7, * matches any digit)
  - `country` 'US' | 'CA': The country of the number given by e164 (default: US). An auto-picked number uses autoPick.country.
  - `name` string: A label for the number
  - `agentId` string, uuid: The agent to assign the number to
  - `expectFree` boolean: Whether you expect this number to be free (from the allowance). The purchase is refused with 409 if that has changed since you checked.
  - `expectMonthlyRentMicros` integer: The monthly rent you expect for a paid number, in micros (from the allowance). The purchase is refused with 409 if that has changed since you checked.

## Response `201`

The purchased phone number

- object
  - `data` PhoneNumberResponse, required: A phone number the project owns
    - `id` string, uuid, required: Phone number ID
    - `e164` string, required: The number in E.164 format
    - `name` string, nullable, required: Label the project gave the number
    - `localityCode` string, nullable, required: ISO 3166-2 code of the region the number is from, when the carrier gave one
    - `purchasedAt` string, required: When the number was bought (ISO 8601)
    - `rentNextChargeAt` string, required: When the next month of rent is due (ISO 8601)
    - `isFree` boolean, required: Whether the number sits inside the plan free allowance right now
    - `monthlyRentMicros` integer, required: What a month of this number costs in micro-dollars; 0 while it is free
    - `agentId` string, uuid, nullable, required: The agent the number is assigned to, if any

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `402`: Payment Required
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `500`: Internal Server Error

## Changes

> 188 revisions in range; 1 not diffed.

- **2026-10-28** `f7faf263170a`: 3 info
  - added the new optional request property `autoPick`
  - added the new optional request property `country`
  - the request property `e164` became optional
- **2026-10-26** `0fb1c3b1940a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/phone-number/post.md)

---

[API](https://skmtc.dev/roarkhq/apis/roark-analytics-api.md) - [All operations](https://skmtc.dev/roarkhq/apis/roark-analytics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roarkhq/apis/roark-analytics-api/revisions/efc3377249d1?raw)