# TempNumber Public API

> REST API to provision private phone numbers, read incoming SMS in real time, and manage the full number lifecycle. JSON over HTTPS, Bearer-token auth, prices are final user-facing USD rates.

## Essentials
- Base URL: https://api.temp-number.com/v1
- Auth: `Authorization: Bearer <token>` (created in dashboard → API Access; scope `api:access`).
- Responses: `{"success":true,"data":...,"meta":...}`; errors `{"success":false,"message":"..."}`.
- Rate limit: 60 req/min per token; back off on HTTP 429 using `Retry-After`.
- Idempotency: send a unique `Idempotency-Key` (UUID) header on all POST endpoints.
- OpenAPI spec: https://api.temp-number.com/api.json

## Account
- `GET /account` - Returns the authenticated account's available wallet balance and currency.

## Discovery & Pricing
- `GET /pricing` - The complete live pricing catalog, grouped by country.
- `GET /pricing/{countryCode}` - Live pricing for a single country.
  - `countryCode` (path, required): ISO 3166-1 alpha-2 country code, e.g.
- `GET /inventory` - Real-time stock for a country + duration so you can preflight a purchase.
  - `country_code` (query, required): ISO 3166-1 alpha-2 country code for the market.
  - `duration` (query, optional): Package duration key (see /pricing/{country}).
  - `number_type` (query, optional): Inventory type: voip or non_voip.

## Number Lifecycle
- `POST /numbers/buy` - Allocates a new private number and settles the order against your wallet atomically.
  - `country_code` (body, required): A country returned by GET /pricing.
  - `duration` (body, required): A duration key from that country's packages[] (e.g.
  - `number_type` (body, optional): voip or non_voip.
- `POST /numbers/{id}/renew` - Extends a number by the requested package.
  - `id` (path, required): Number id from GET /numbers.
  - `package` (body, optional): oneMonth (default), threeMonths, sixMonths, oneYear.
- `POST /numbers/{id}/cancel` - Releases a number and stops further SMS.
  - `id` (path, required): Number id from GET /numbers.

## Your Numbers & SMS
- `GET /numbers` - Every number on your account, newest first.
  - `status` (query, optional): active, expiring_soon, expired, cancelled, or all (default).
- `GET /numbers/{id}/sms` - Full details of one number together with the SMS it has received, newest first.
  - `id` (path, required): Number id from GET /numbers.
- `GET /receive-sms` - Cursor-paginated SMS for a number you own, addressed by its E.164 phone number rather than its id.
  - `phoneNumber` (query, required): The number in E.164 (or digits), e.g.
  - `limit` (query, optional): Page size 1-100 (default 50).
  - `cursor` (query, optional): Opaque pagination cursor from a previous response.