API Documentation

Introduction

The NonVoIP User API lets you check your account balance, list services, create orders, read SMS messages, and receive webhook events.

Base URL

All relative paths in this documentation are under the base URL below. Endpoint cards show relative paths; cURL examples use the full URL.

https://nonvoip.com/api/v1

Authentication

Every request requires a Bearer API key. Create and manage API keys in Dashboard → API.

Authorization: Bearer nv_live_your_api_key
Accept: application/json
Content-Type: application/json

Required Headers

Authorization: Bearer <api_key> — required on every request.

Accept: application/json — recommended on every request.

Content-Type: application/json — required for POST/PATCH requests with a JSON body.

Idempotency-Key — required for create order requests to prevent duplicate charges.

Authorization: Bearer nv_live_your_api_key
Accept: application/json
Content-Type: application/json
Idempotency-Key: order-create-unique-id-123

Response Envelope

Successful responses set success to true and place the response payload in data.

{
  "success": true,
  "data": { },
  "error": null,
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-07-10T12:00:00.000Z"
  }
}

Error Response

Failed responses set success to false. Use error.code for programmatic handling; details may include additional context.

{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": { "fields": { "quoted_price": "Invalid format" } }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-07-10T12:00:00.000Z"
  }
}

API Error Codes

Common User API error codes. See endpoint cards for additional codes.

Rate Limits

Rate limit: 300 requests per minute per account.

If you exceed the limit, the API returns RATE_LIMIT_EXCEEDED with HTTP 429. Use webhooks for SMS delivery and avoid aggressive polling.

Idempotency

Create order requests require a unique Idempotency-Key header. Reusing the same key returns the original result and prevents duplicate charges.

Idempotency-Key: order-create-unique-id-123

Price / Currency

All prices and wallet balances are shown in USD as decimal strings, for example "0.31" or "120.50".

Send quoted_price as the catalog customer_price you showed the customer. If the current price is higher, the API returns 409 PRICE_CHANGED and does not charge — confirm the new price, then retry. If the current price is lower, the order continues and you are charged the lower price.

Pagination

List endpoints use offset pagination with page (default 1) and per_page (default 15; max depends on the endpoint, typically 50).

{
  "page": 1,
  "per_page": 15,
  "total": 42
}

Timezone

All timestamps are ISO 8601 in UTC, for example 2026-07-10T12:00:00.000Z.

API Versioning

The current version is exposed under the /api/v1 path prefix. Breaking changes are announced; do not rely on undocumented fields.

Quickstart

1. Create an API key in Dashboard → API.

2. Check account and balance — GET /account.

3. List services — GET /products?type=short-term.

4. Create an order — POST /orders.

5. Receive SMS — use a webhook (preferred), or poll GET /orders/:id/messages?sync=0.

curl -s "https://nonvoip.com/api/v1/account" \
  -H "Authorization: Bearer nv_live_your_api_key"

curl -s "https://nonvoip.com/api/v1/products?type=short-term" \
  -H "Authorization: Bearer nv_live_your_api_key"

curl -s -X POST "https://nonvoip.com/api/v1/orders" \
  -H "Authorization: Bearer nv_live_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-create-unique-id-123" \
  -d '{"type":"short-term","service_id":"svc:whatsapp:short_term","offer_id":"off_abc123","quoted_price":"0.31"}'