Provynx SMS
REST API v1

Provynx SMS API

Purchase virtual numbers and receive verification codes with the Provynx SMS REST API. Browse routes by section, copy examples, and ship in minutes.

14 endpointsOpenAPI 3.1Sandbox keysWebhooks
Create accountAPI keysOpenAPI JSON
Quick example

Base URL

https://sms.provynx.com/api/v1/sms

Auth header

Authorization: Bearer nsk_live_your_api_key

Sample request
curl -X GET "https://sms.provynx.com/api/v1/sms/us/services?operator=any" \
  -H "Authorization: Bearer nsk_live_••••••••"

Getting started

Auth, workflow, and sandbox

Authentication

Send your API key on every request via Authorization. Create keys in Settings → API Keys.

Live

nsk_live_…

Test

nsk_test_…

Up to 10 active keys per account.

Sandbox

Test keys use the nsk_test_ prefix and return sandbox responses. No wallet debits and no live number purchases. Verification codes are returned after two polls with code 123456.

Fixed balance: $100.00 USD

Wallet (live keys)

Live API purchases debit your Provynx wallet. There is no public top-up endpoint — add funds on the website, then use GET /balance before buying numbers.

Top up wallet

Integration workflow

  1. 1

    Create a live or test API key in Settings → API Keys.

  2. 2

    For live keys: sign in and top up your wallet on the website (Wallet → Top up). There is no public top-up API.

  3. 3

    Use a test key (nsk_test_) to integrate against sandbox responses first — no wallet funding required.

  4. 4

    Check balance: GET /balance (live keys reflect your wallet; test keys always return $100.00 sandbox balance).

  5. 5

    Pick a server (1, 2, or 3) and keep it consistent for catalog + purchase in each flow.

  6. 6

    US flow: GET /us/operators?server=1 → GET /us/services?server=1&operator=any → POST /us/numbers with the same server → GET /us/numbers/{id}/code. Cancel with DELETE /us/numbers/{id} if needed.

  7. 7

    Global flow: GET /global/countries?server=1 → GET /global/services?server=1&country=gb&operator=any → POST /global/numbers with the same server → GET /global/numbers/{id}/code. Global numbers cannot be canceled via the API.

  8. 8

    Alternatively, receive otp.received webhooks when a verification code arrives (live and test keys). Verify deliveries with your whsec_ signing secret.

SMS servers

Upstream server selection for catalog and purchases

Provynx exposes three interchangeable SMS servers. Pick one server for the whole flow — catalog browsing and purchase must use the same server value. Defaults to server 1 when omitted.

Server 1

Server 1

Default catalog for US and global numbers.

Server 2

Server 2

Alternate catalog for US and global numbers.

Server 3

Server 3

Alternate catalog for US and global numbers with broad international coverage.

  • Supported values: 1, 2, or 3. All three work for US routes (/us/*) and global routes (/global/*).
  • Catalog: append ?server=1|2|3 to GET /us/operators, GET /us/services, GET /global/countries, and GET /global/services.
  • Purchase: include "server": 1|2|3 in the JSON body for POST /us/numbers and POST /global/numbers.
  • Use the same server when browsing catalog and placing an order. A pricingId from server 1 cannot be purchased with server 2 or 3.
  • If a server is not configured in the environment, catalog responses return configured: false or empty products/stock.
  • Server 3 global services require country and operator query params, e.g. GET /global/services?server=3&country=br&operator=any.
  • Server 3 US services use GET /us/services?server=3&operator=any.
?server=3·"server": 3

Reference

Errors, limits, and platform notes

HTTP error codes

401

Missing or invalid API key

400

Invalid request body or product unavailable

402

Insufficient wallet balance

404

Number or pricing not found

409

Purchase already in progress (retry with same idempotency key)

429

Rate limit exceeded

502

Temporary service failure

503

SMS numbers are temporarily unavailable

Body shape: { "error": "..." }

Limits & notes

  • Purchases: 10 req/min · Code polling: 60 req/min · Webhook ping: 5 req/min · Reads: 120 req/min per scope
  • Lists return today's numbers only; fetch any number with GET …/numbers/{id}
  • Top-ups are website-only (Wallet → Top up)
  • Global numbers have no public cancel endpoint; only US numbers support DELETE /us/numbers/{id}
  • Set API_CORS_ORIGINS for browser clients