Receiving Truecaller SMS codes programmatically

What does the API call chain for Truecaller look like?

Truecaller's service id is truecaller, and every call below is made against https://otproute.com/api/v1 using a Bearer key whose prefix is or_live_.

1. GET /api/v1/countries gives you country ids; cache them.
2. GET /api/v1/prices?country=<id>&service=truecaller returns the live price and whether a route is open right now.
3. POST /api/v1/activations with {"service": "truecaller", "country": "in"} (or any other country id) reserves the number and returns an activation id.
4. Enter that number in the Truecaller app on your test device and request verification.
5. The code arrives as an activation.sms_received webhook event, or you poll GET /api/v1/activations/{id}.
6. If the test is abandoned, POST /api/v1/activations/{id}/cancel refunds it at once.

An account supports 10 API keys, 5 webhook endpoints and 300 requests per minute. The API integration guide covers retries and timeouts.

How should the webhook handler treat Truecaller events?

Each delivery carries X-OTPRoute-Signature: t=<unix>,v1=<hex>. Recompute HMAC-SHA256 over the timestamp, a dot and the raw request body with your endpoint secret, compare in constant time, and reject timestamps that are too old.

Key all processing on the activation id. Webhooks can be retried, so a handler that stores the code twice or advances a test twice will produce flaky results; check whether the activation is already marked complete before acting. Treat activation.expired and activation.cancelled as terminal states that tell your test runner to stop waiting. Polling works as a fallback for local development where no public endpoint exists.

Why does Truecaller ask for a phone number at all?

Truecaller is a caller ID and spam-blocking app, and the phone number is the account. Registration confirms the user controls the number before the profile is created, and the check repeats when the app is reinstalled or moved to a new device. On some devices the app may try to verify with a call rather than an SMS. An OTP Gateway number captures SMS only, so a call-based check will not produce a code on the activation; the window simply runs out and the wallet is refunded.

Legitimate reasons teams verify Truecaller accounts include checking how a company's outbound support or delivery numbers are labelled for people in a given market, QA on apps that integrate caller identification, and operations staff who need a work profile separate from their personal phone.

Which countries carry Truecaller routes?

The live snapshot lists Truecaller routes in 198 countries, among them India, Pakistan, Bangladesh, Nigeria, Kenya, Egypt, Indonesia, Sri Lanka, Nepal, Saudi Arabia, the United Arab Emirates, Brazil, Mexico, South Africa, the United Kingdom and the United States.

Choose the country to match the test case. Caller labels, spam reports and the app's language follow the market, so a check of how your Lagos support line appears should use a Nigerian route, not whatever happens to be cheapest. Availability changes through the day; query the prices endpoint before each run.

Can non-developers do this from the dashboard?

Yes. Sign in, open the OTP Gateway, choose Truecaller and a country, confirm the price shown, and the number appears on an activation card. Enter it in Truecaller, request the code, and it shows up on the same card when the SMS lands. The 20-minute window is visible on the card. If no code arrives, or you cancel, the full amount returns to your wallet automatically. Wallet top-ups work by card or USDT/USDC, with a PDF invoice by email for each one; see pricing.

Why might a Truecaller code fail to arrive?

Common causes:

• Truecaller declined the number because it treats it as virtual. Some services do; this is why you are refunded.
• The app chose call-based verification instead of SMS.
• The route was briefly congested. Try later or with another country that fits your test.
• The number was entered without its country code, or with a stray trunk 0.

Do not hammer the order endpoint in a loop. Space attempts out and log each activation id so you can see patterns.

When does a Dedicated Number make more sense for Truecaller?

A one-time number is gone after the activation. If a Truecaller profile has to be reverified later, for example a support team's work device that gets reset, use a Dedicated Number instead. These are available instantly in the United States and Canada from $1.95/month, receive SMS in the dashboard and through the number.sms_received webhook, and renew from the wallet until you release them. See virtual numbers.

Use OTP Route only for your own legitimate accounts and products: one account per real person or business, no reports or label changes against other people's numbers, and full respect for Truecaller's terms and the OTP Route Acceptable Use Policy. Truecaller is a trademark of its owner, and OTP Route is not affiliated with it.

Frequently asked questions

What is the service id for Truecaller in the API?

It is truecaller. Pair it with a country id in GET /api/v1/prices and in the POST /api/v1/activations body.

Can I receive a Truecaller OTP on a virtual number?

Often, but not always; Truecaller may refuse numbers it classifies as virtual. If no code arrives in 20 minutes, the charge is refunded automatically.

Why did Truecaller call instead of sending an SMS?

The app can choose call-based verification on some devices. OTP Gateway numbers capture SMS only, so request the SMS option if the app offers it.

Which country should I pick for Truecaller SMS verification testing?

Pick the market your test is about, since caller labels and language follow the number's country. Check live availability with the prices endpoint first.

Can I keep the same Truecaller phone number for later logins?

Yes, with a Dedicated Number in the United States or Canada from $1.95/month. One-time gateway numbers cannot be reused.

How do I stop duplicate webhook deliveries from breaking my tests?

Make the handler idempotent on the activation id and verify the signature before doing anything with the payload.

Is OTP Route affiliated with Truecaller?

No. Truecaller is a trademark of its owner; OTP Route provides numbers for testing and operating your own legitimate accounts.

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.