Receiving +966 Verification Codes Programmatically for Saudi Launches

What does a single +966 activation look like over the API?

Start with the calls, since most readers of this page are wiring an SMS verification API into a test suite or an internal tool. All endpoints sit under https://otproute.com/api/v1 and expect a Bearer key with the or_live_ prefix, created in the Developer console.

1. GET /api/v1/countries and GET /api/v1/services give you the ids. Saudi Arabia is sa.
2. GET /api/v1/prices?country=sa&service=<id> returns the live rate for that pairing; log it next to the test run.
3. POST /api/v1/activations with {"service": "<id>", "country": "sa"} returns an activation id and a +966 number.
4. Your test enters the number in the app, and the code arrives as an event or through GET /api/v1/activations/{id}.
5. If the test is abandoned, POST /api/v1/activations/{id}/cancel releases it and refunds the wallet.

GET /api/v1/balance is handy as a pre-flight check so a nightly job fails early with a clear message rather than mid-run. Limits to plan around: 10 keys and 5 webhook endpoints per account, 300 requests per minute.

How should our webhook receiver treat Saudi OTP events?

Register an endpoint and subscribe to activation.sms_received, activation.expired and activation.cancelled. Every request includes X-OTPRoute-Signature in the form t=<unix>,v1=<hex>.

• Rebuild the signed string as <t>.<raw body> and compute HMAC-SHA256 with that endpoint's secret.
• Compare against v1 with a constant-time function, and reject anything whose timestamp is too old.
• Treat each event as keyed on the activation id, so a redelivery updates nothing twice.
• Reply with a 2xx quickly and do slow work in a background job.

Polling remains a valid fallback for runners that cannot accept inbound connections. Our write-ups on webhook-based OTP capture and securing OTP webhooks with HMAC go further.

Why are product teams testing with a +966 number?

Saudi Arabia is one of the larger digital markets in the Gulf, and teams arrive at this page for practical reasons: a fintech preparing onboarding for Saudi residents, a marketplace adding Gulf sellers, a SaaS vendor whose customer requires a regional sign-in check, or an operations team that manages business accounts for a Riyadh or Jeddah office. In each case someone has to prove the flow works with a real Saudi verification number, and OTP routing through the gateway saves shipping SIM cards to the region. The fintech onboarding page describes that scenario in more detail.

Which services can receive codes on Saudi routes?

The live snapshot for Saudi Arabia covers more than 1,000 services. Frequently used ones include Snapchat, WhatsApp, X (Twitter), Uber, TikTok, Instagram, Google (Gmail & YouTube), Telegram, Amazon, Microsoft & Outlook, LinkedIn, Discord and Netflix. Snapchat and X have notably large audiences in the Kingdom, which makes them common items on a localisation checklist. Inventory moves during the day, so query the API at run time.

How do I format +966 numbers and parse Arabic messages?

Locally, Saudi mobile numbers are written with a trunk 0, usually as 05 followed by eight digits. The international form drops that zero: +966 5 and the remaining eight digits. Normalise everything to E.164 at the point of entry and strip the zero if a user types it after the country code.

Arabic is the official language, so verification texts may arrive in Arabic, in English, or in both. Arabic is written right to left, and some templates may use Arabic-Indic digits rather than Western numerals. A parser that maps those digits to ASCII before matching, and logs raw UTF-8, avoids a frustrating class of false failures.

Is there a dashboard path for people who don't code?

Yes. Sign in to OTP Route, open the OTP Gateway, choose Saudi Arabia and the service, review the price, and confirm. The number appears straight away and the code is displayed beside it on arrival. A support agent can use this to reproduce a customer's sign-up issue in a couple of minutes.

What if the code never arrives, and what about long-term lines and billing?

If no SMS arrives within 20 minutes, or you cancel, the full amount goes back to the wallet automatically. Let the window finish, retry later or through another service route, confirm that the service accepts virtual numbers, and avoid re-ordering in a tight loop.

There is no self-serve long-term Saudi number. Dedicated Virtual Numbers are offered only in the United States and Canada, from $1.95/month; for a long-term +966 line, email [email protected], bearing in mind that local rules decide whether it is possible.

Funding uses one prepaid USD wallet, pay as you go, with no monthly fee. Card payments and USDT/USDC both work for top-ups, and each one produces an emailed PDF invoice. A development account can be switched to sandbox on request for simulated numbers and codes. Check the pricing page for current rates.

Frequently asked questions

How do I receive a Saudi SMS OTP through an API?

Create an activation with country sa and your service id, then take the code from the activation.sms_received webhook or by polling the activation.

Is a +966 number for testing billed if the code fails?

No. A missing code means the full amount is returned to the wallet when the 20-minute window closes or you cancel.

Can I test my app's Saudi sign-up flow without a local SIM?

Yes. The OTP Gateway issues a +966 number for one code, which you enter in your app and read back through the dashboard or the API.

How should I store a Saudi mobile number entered as 05XXXXXXXX?

Drop the trunk zero and store it as +966 5 plus the remaining eight digits in E.164.

Can we keep the same Saudi number for later logins?

Not with a self-serve product, because long-term Dedicated Numbers cover only the US and Canada. Email the team if you need a Saudi line, with no assurance it can be provided.

Is there a way to rehearse the Saudi flow before real money is involved?

Yes. Ask for sandbox mode on a development account to receive simulated numbers and codes, webhooks included.

What usage does OTP Route allow?

Testing and operating your own legitimate products and accounts. Follow every service's terms; the OTP Route Acceptable Use Policy applies.

Service names are trademarks of their respective owners. OTP Route is not affiliated with them. Use numbers lawfully, follow each service's terms and our Acceptable Use Policy.