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

# GET /api/numbers

`GET /api/numbers`

## Request

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

The account's phone numbers, and the countries more can be bought in with today's prices. Calls go out from a number in the callee's country when the account holds one. US, Canadian and European businesses can always be called (Europe from a European number if the account has one, else from its US number), and UAE and Japanese businesses too, from the account's US number (the business sees a US caller ID); elsewhere, a number in the country is what lets the account call there. Numbers cost exactly what the carrier charges: the upfront cost plus the first month when bought, then the monthly cost every 30 days, taken from the balance. own_numbers are the user's own phone numbers verified with call4me_verify_number: free, and used only when call4me_place_call names one in from.

## Response `200`

The account's numbers and the countries more can be bought in

- object
  - `numbers` object[], required
    - `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
  - `pending_numbers` object[]: numbers paid for and waiting on the carrier's approval (numbers abroad are reviewed first, minutes to a few days). They activate by themselves and cannot place calls until they move to numbers. Omitted when there are none
    - `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
    - `monthly` string, required
    - `monthly_cents` integer, required
    - `ordered` string, required: date it was bought; it activates once the carrier approves it, and its first month starts then
  - `own_numbers` object[]: the user's own phone numbers, verified to call from: calls go out from one only when place_call names it in from. Omitted when the account has none
    - `number` string, required: formatted for people
    - `e164` string, required
    - `country` string, required: ISO 3166-1 alpha-2
    - `country_name` string, required
    - `status` 'pending' | 'verified', required: pending: the code was sent and has not come back yet
    - `method` 'sms' | 'call', required: how the code was sent
    - `verified_at` string, nullable, required
  - `countries` object[], required
    - `country` string, required
    - `name` string, required
    - `type` string, required
    - `available` boolean, required
    - `reason` string, nullable, required: why a number cannot be bought there right now
    - `upfront_cents` integer, nullable, required
    - `monthly_cents` integer, nullable, required
    - `price` string, nullable, required: taken from the balance when buying: upfront cost plus the first month
    - `monthly` string, nullable, required

## Other responses

- `401`: 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)