Build automated SMS verification workflows with account-level API keys, wallet-backed billing, idempotent ordering, and documented error responses.
Every API request must include the NumFlow API key generated by the current account. NumFlow applies that account's balance, permissions, rate limits, and risk controls:X-API-Key + HMAC-SHA256 signature headers
Developers only call the NumFlow API. Each account owns its API keys, balance, orders, and wallet ledger. Sensitive platform credentials and other account data are never exposed.
Billing model: after a number is assigned, NumFlow places a hold for the platform price. The hold is captured only after the first SMS code is received. If no code arrives and cancellation or timeout processing succeeds, the held amount is released. Amounts submitted in the request body are ignored.
Recommended Flow
1. Check balance and confirm the account has enough available balance.
2. Call the number-ordering endpoint with a unique Idempotency-Key for each business request.
3. Poll the SMS result every 3-5 seconds. Use the expires_at value returned by the order response as the receiving window.
4. When a code is returned, the order is completed and billed automatically. Within the effective window, continue querying the same order for later codes. If no code arrives, cancel only when the order state allows it.
Error responses use a consistent JSON shape: { success: false, error: { code, message } }
API_UNAUTHENTICATEDThe API key is missing, invalid, or revoked.API_SIGNATURE_REQUIREDSigned request headers are required.API_SIGNATURE_INVALIDThe HMAC signature is invalid.API_REPLAY_DETECTEDThe nonce has already been used inside the replay window.IDEMPOTENCY_KEY_REQUIREDNumber ordering requires an Idempotency-Key.IDEMPOTENCY_KEY_REUSEDThe key was reused with different order parameters.IDEMPOTENCY_RECOVERY_REQUIREDA previous allocation result is uncertain; automatic retry was stopped to prevent a duplicate purchase.VALIDATION_ERRORThe request payload or path parameters are invalid.INSUFFICIENT_WALLET_BALANCEThe account does not have enough available balance.RATE_LIMITEDToo many requests. Retry after a short delay.NO_FREE_PHONESNo number is currently available for the selected country, service, or line.BAD_COUNTRYThe country code is invalid.BAD_OPERATORThe line/operator code is invalid.NO_PRODUCTThe service code is invalid.ORDER_NOT_FOUNDThe order does not exist or does not belong to this API key account.SMS_CODE_REQUIREDThe order cannot be completed before an SMS code is received.ORDER_NOT_CANCELABLEThe order already received a code or reached a terminal state.ORDER_STATE_CONFLICTThe order changed concurrently; refresh before retrying.ORDER_BILLING_CONFLICTCode delivery was stopped because billing state requires reconciliation.NUMBER_SERVICE_NOT_CONFIGUREDThe number service is not configured for this environment.NUMBER_SERVICE_UNAVAILABLEThe number service is temporarily unavailable. Retry later.NUMBER_SERVICE_TEMPORARILY_UNAVAILABLENumber ordering is temporarily unavailable. Contact support if it persists.BUSINESS_ERRORThe request could not be completed. Refresh the order status and retry.Create an account, add wallet balance, and generate an API key from your account center. Each account has independent billing, rate limits, and order records.
Open Account Center