---
title: "Search Available Phone Numbers"
method: POST
path: "/v2/phone-numbers/available"
tags: ["v2", "phone-numbers"]
---

# Search Available Phone Numbers

`POST /v2/phone-numbers/available`

## Request

- Base URL: `https://api.mentium.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.mentium.io/v2/phone-numbers/available`
- Auth: HTTP bearer

Search for available phone numbers from Twilio that can be purchased.

Filter by area code, contains pattern, or get a general list for the country.

## Headers

- `mentium-workspace-id` string, nullable

## Request body

- SearchAvailableNumbersRequest: Request to search for available phone numbers
  - `country_code` string: ISO country code
  - `area_code` string, nullable: Filter by area code (e.g., 312)
  - `contains` string, nullable: Filter by numbers containing digits
  - `limit` integer: Max results to return

## Response `200`

Successful Response

- SearchAvailableNumbersResponse: Response with available phone numbers
  - `phone_numbers` AvailablePhoneNumber[], required
    - `phone_number` string, required: E.164 formatted phone number
    - `friendly_name` string, required: Human-readable phone number
    - `area_code` string, required: Area code (e.g., 312)
    - `city` string, required: City name
    - `state` string, required: State/region code
    - `country_code` string: ISO country code
    - `capabilities` AvailablePhoneNumberCapabilities: Capabilities of an available phone number
      - `voice` boolean
      - `sms` boolean
      - `mms` boolean

## Other responses

- `422`: Validation Error

---

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