# NonVoipUsNumber API

NonVoipUsNumber provides an API for non-VoIP number ordering, product availability, SMS retrieval, renewals, rejection, reuse, and callback/webhook delivery. This file is for AI agents, coding tools, and app builders that need to understand how to integrate with the API.

## Source Of Truth

- OpenAPI JSON: https://nonvoipusnumber.com/manager/api-docs/openapi.json
- Full AI guide: https://nonvoipusnumber.com/llms-full.txt
- API docs: https://nonvoipusnumber.com/manager/api-docs
- Swagger UI: https://nonvoipusnumber.com/manager/api-docs/swagger
- Static OpenAPI JSON: https://nonvoipusnumber.com/manager/openapi.json

## API Basics

- Base URL: https://nonvoipusnumber.com/manager
- Request formats: application/json, application/x-www-form-urlencoded, multipart/form-data
- Authentication: send `email` and `password` in the body of every external API request.
- Product selection: call `/api/products` first and use the returned `product_id` values for ordering.
- Order actions: prefer `order_id` for `/api/reuse`, `/api/activate`, `/api/reject`, `/api/renew`, and `/api/getsms`.
- Time values: API timestamps are UTC. Short-term `expiration` values are seconds.
- 30-days multi-service ordering: `/api/order` accepts `product_ids` (maximum 5) to create a new 30-days number with multiple services on the same number.
- Existing 30-days number add-service: this is a website/internal flow, not a documented external API path in the OpenAPI spec.

## Endpoints

- `POST /api/balance`: get account balance.
- `POST /api/products`: list USA products, prices, and stock.
- `POST /api/order`: place USA 10-minute, 30-days, 1-day, or legacy 3-days orders.
- `POST /api/country/products`: list country-wise products.
- `POST /api/country/order`: place country-wise order.
- `POST /api/reuse`: reuse a short-term number.
- `POST /api/activate`: activate a long-term or 3-days number.
- `POST /api/reject`: reject a number before receiving SMS.
- `POST /api/renew`: renew a rented number.
- `POST /api/getsms`: get latest SMS for an order.
- `POST /api/saveurl`: save callback URL.

## Important Integration Rules

- For 10-minute products, the `price` returned by `/api/products` is the current expected route price.
- If `/api/order` returns `Price_Change_Required`, show the user the `available_price` and retry with `accepted_max_price` only after the user accepts the higher price.
- If `/api/order` returns `Premium_Available`, retry the same `product_id` with `auction` set to the recommended bid only after the user accepts premium bidding.
- Save callback URLs with `/api/saveurl`; callbacks are sent to the saved URL when SMS messages or premium bid events arrive.
- For web applications, prefer calling this API from a backend service instead of hard-coding credentials in frontend JavaScript.

For code generation, app builders, and AI agents, use the OpenAPI JSON as the source of truth and read `llms-full.txt` for implementation workflow details.