---
title: "POST /api/numbers"
method: POST
path: "/api/numbers"
---

# POST /api/numbers

`POST /api/numbers`

## Request

- Base URL: `https://call4.me`
- URL: `https://call4.me/api/numbers`
- Auth: HTTP bearer

Buy another phone number, in the US or abroad, paid from the balance at the carrier's own price (see call4me_list_numbers for prices). It renews from the balance every 30 days; if the balance can't cover a renewal the number is released after 7 days. Only buy when the user asks for a number or needs one to call a country. A number abroad is reviewed by the carrier after it's paid for, from minutes to a few days: it comes back pending, activates by itself, and can't place calls until then.

## Request body

- object
  - `country` string, required: ISO country code from the countries list, e.g. "NL", "GB", "CA", "US"
  - `area_code` string: preferred area code (national destination code), e.g. "415" or "20"; the nearest available is used otherwise

## Response `201`

The number bought, ready to call from

- object
  - `number` string, required: formatted for people
  - `e164` string, required
  - `country` string, required: ISO 3166-1 alpha-2
  - `country_name` string, required
  - `type` string, required: local, mobile, national or toll_free
  - `included` boolean, required: the free number that came with the account
  - `monthly` string, required
  - `monthly_cents` integer, required
  - `renews` string, nullable, required: date the next monthly charge is due; null for the free number
  - `overdue` boolean, required: the last renewal failed for lack of credits
  - `release_after` string, nullable, required: when an overdue number is released unless credits are added

## Other responses

- `202`: The number bought and waiting on the carrier's approval; it activates by itself
- `400`: Request failed
- `401`: Request failed
- `402`: Request failed
- `409`: Request failed
- `502`: Request failed
- `503`: Request failed

---

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