API v1

API reference

Every endpoint, the scope it needs, and what it returns.

← Back to the developer guide

Catalogue

GET/api/v1/countriescountries:read

List supported countries and their operators.

GET/api/v1/servicesservices:read

List supported services.

GET/api/v1/operatorscountries:read

List operators, optionally filtered by ?country=NG.

GET/api/v1/availabilityavailability:read

Stock and price right now for a country/service pair.

Requires ?country= and ?service=. An order pays this price when placed, or exactly what a quote locked.

Orders

POST/api/v1/quotesorders:write

Lock the current price for a few minutes.

Body: country, service. Pass the returned quote to POST /orders. One quote, one order.

POST/api/v1/ordersorders:write

Buy a number. Returns 201.

Body: country, service, optional quote, max_price and idempotency_key. A quiet number is replaced free; no code at all is refunded in full.

GET/api/v1/ordersorders:read

List your orders. Supports ?limit, ?cursor and ?status.

GET/api/v1/orders/:idorders:read

Fetch one order with its messages; also moves it on.

POST/api/v1/orders/:id/replaceorders:write

Swap the current number for a new one, free.

Allowed from replace.available_at, while replace.remaining lasts.

POST/api/v1/orders/:id/cancelorders:write

Cancel and refund in full, while no code has arrived.

Activations (earlier purchases)

GET/api/v1/activationsactivations:read

List your earlier activations. Supports ?limit, ?cursor and ?status.

Buying with POST /api/v1/activations is retired (410): use POST /api/v1/orders.

GET/api/v1/activations/:idactivations:read

Fetch one activation; also refreshes it from the supplier.

GET/api/v1/activations/:id/messagesactivations:read

Messages received on this activation.

POST/api/v1/activations/:id/cancelactivations:write

Cancel and refund in full, if no SMS has arrived.

POST/api/v1/activations/:id/additional-smsactivations:write

Request another code on the same number.

Returns ADDITIONAL_SMS_UNSUPPORTED when the supplier cannot do this.

Rentals

GET/api/v1/rentalsrentals:read

List your rentals.

POST/api/v1/rentalsrentals:write

Rent a number. Body: country, duration_days, optional service.

GET/api/v1/rentals/:idrentals:read

Fetch one rental with its recent messages.

POST/api/v1/rentals/:id/renewrentals:write

Extend a rental. Body: duration_days.

POST/api/v1/rentals/:id/releaserentals:write

Free the number early. Not refunded.

Wallet

GET/api/v1/walletwallet:read

Current balance and currency.

GET/api/v1/transactionstransactions:read

Your ledger, newest first. Supports ?limit, ?cursor and ?type.

Scopes

countries:readList supported countries
services:readList supported services
availability:readCheck stock and pricing
orders:readRead orders and their messages
orders:writeBuy numbers, lock prices, cancel and replace numbers
activations:readRead activations and their messages
activations:writeCancel and manage earlier activations
rentals:readRead rentals and their messages
rentals:writeCreate, renew and release rentals
wallet:readRead the wallet balance
transactions:readRead wallet transactions

Error codes

Branch on the code, not the message. Codes are stable; wording may change.

Code	HTTP	Meaning
`UNAUTHORIZED`	401	You need to sign in to continue.
`FORBIDDEN`	403	You do not have access to this resource.
`INVALID_CREDENTIALS`	401	That email or password is incorrect.
`EMAIL_NOT_VERIFIED`	403	Please verify your email address first.
`ACCOUNT_SUSPENDED`	403	This account is suspended. Contact support.
`SESSION_EXPIRED`	401	Your session has expired. Please sign in again.
`INVALID_TOKEN`	400	This link is invalid or has already been used.
`TOKEN_EXPIRED`	400	This link has expired. Please request a new one.
`VALIDATION_ERROR`	422	Some of the details provided are not valid.
`NOT_FOUND`	404	We could not find what you were looking for.
`CONFLICT`	409	That action conflicts with the current state.
`EMAIL_TAKEN`	409	An account with that email already exists.
`INSUFFICIENT_BALANCE`	402	Your wallet balance is too low for this purchase.
`WALLET_FROZEN`	403	This wallet is frozen. Contact support.
`PAYMENT_FAILED`	402	The payment could not be completed.
`PAYMENT_ALREADY_PROCESSED`	409	This payment has already been processed.
`INVALID_AMOUNT`	422	Please enter a valid amount.
`CURRENCY_MISMATCH`	422	That currency does not match your wallet.
`NO_INVENTORY`	409	No numbers are available for that combination right now.
`NUMBER_UNAVAILABLE`	409	That number was just taken. Please try another.
`ACTIVATION_EXPIRED`	410	This activation has expired.
`ACTIVATION_NOT_CANCELLABLE`	409	This activation can no longer be cancelled.
`QUOTE_INVALID`	400	That price could not be verified. Check the price and try again.
`QUOTE_EXPIRED`	409	That price has expired. Check the new price and try again.
`QUOTE_USED`	409	That price has already been used for an order.
`PRICE_ABOVE_MAXIMUM`	409	The price is above the maximum you set.
`ORDER_NOT_CANCELLABLE`	409	This order can no longer be cancelled.
`REROLL_UNAVAILABLE`	409	A new number can only be requested while you are waiting for a code.
`REROLL_TOO_SOON`	409	Give this number a minute before asking for another.
`REROLL_LIMIT`	409	This order has already had its replacement numbers.
`INVALID_STATE_TRANSITION`	409	That action is not valid at this stage.
`ALREADY_REFUNDED`	409	This order has already been refunded.
`RENTAL_EXPIRED`	410	This rental has expired.
`SERVICE_UNAVAILABLE_IN_COUNTRY`	409	That service is not available for the selected country.
`PROVIDER_UNAVAILABLE`	503	Our number supplier is temporarily unavailable.
`PROVIDER_ERROR`	502	The number supplier returned an unexpected response.
`ADDITIONAL_SMS_UNSUPPORTED`	400	This supplier does not support requesting another SMS.
`RATE_LIMITED`	429	Too many requests. Please slow down and try again.
`INVALID_API_KEY`	401	That API key is invalid or has been revoked.
`INSUFFICIENT_SCOPE`	403	This API key lacks the required scope.
`ENDPOINT_RETIRED`	410	This endpoint has been retired.
`INVALID_SIGNATURE`	401	The request signature could not be verified.
`BLOCKED_BY_RISK_RULES`	403	This action was blocked by our automated risk checks. Contact support if this is a mistake.
`MAINTENANCE_MODE`	503	SMSPVO is briefly down for maintenance.
`INTERNAL_ERROR`	500	Something went wrong on our side. Please try again.