Same engine as the apps

Developer API for lawful SMS OTP

The Ucode API rents numbers and delivers SMS with the same wallet and auto-refund rules as iOS, Android, and Web. Responses never include wholesale provider names. For AI agents that should pay per SMS without a human account, use the x402 agent rail instead of a long-lived password.

What you can build

  • Automated QA for your own sign-up and login flows using real SMS in different countries.
  • Internal tools that give support or ops teams a shared, auditable OTP inbox.
  • AI agents that need one verification code (see the agent rail for keyless x402 payments).

Quick start

Base URL

https://app-api.ucodesim.com/api/v1

Authenticate every request with your key

Authorization: Bearer uc_live_…

Create an activation (rent a number for a service and country)

POST /activations
{ "service": "wa", "country": 0 }

When the SMS arrives, Ucode POSTs to your HTTPS webhook

{ "type": "sms.received", "rentalId": "…", "phone": "…", "text": "…" }

Verify each webhook with the X-Ucode-Signature header: an HMAC-SHA256 of the raw request body using your webhook secret. Reject requests where it does not match.

How it behaves

  • Same wallet as the apps: credits bought anywhere work in the API.
  • Automatic refunds: if no SMS arrives within the rental window (about 20 minutes), credits return.
  • No provider names are exposed in responses.
  • Service codes are short identifiers (for example wa for WhatsApp); agents can search the catalogue at /api/v1/agent/services?search=.

Getting a key

Sign in to the web app and create a key under Developers (/app/developers). Keys start with uc_live_. Keep them server-side and rotate them if they leak.

Testing tips

  • Keep one retry, then switch country or route. Hammering resend triggers rate limits on the sending app.
  • Log the rental ID, number, country, and timestamps so failures are easy to diagnose.
  • Use test numbers for staging only, never to create accounts on third-party platforms at scale.

Guides: OTP testing playbook, staging and UAT testing, what to log when SMS fails.

FAQ

Does the API refund failed SMS?

Yes. If no SMS arrives within the rental window, credits return automatically, exactly as in the apps.

How do I receive the SMS?

Register an HTTPS webhook and Ucode POSTs an sms.received event with the text. Verify the X-Ucode-Signature header.

Are provider names in the payload?

No.

Can agents use the API without a key?

Yes, through the x402 agent rail: they pay in USDC on Base per request, or buy a credit pack and receive a uc_live key.

Where do I get a key?

Sign in at ucode.uk/app and open Developers.

Download FreeOpen Ucode Web