Truecaller Verification SDK: Integration Guide

In India, the phone number is the identity. And most of your users already have the Truecaller app sitting on their device, which means you can verify a number in a single tap instead of firing off an OTP and praying it lands. So how does the flow actually work, how do you verify the token on your server, and what happens to the users who don't have Truecaller? That's the whole guide. NamoID puts Truecaller behind the same OIDC issuer as your other login methods, so you get one-tap when it's available and an OTP path when it isn't, without maintaining two separate auth systems.

How Truecaller verification works

Truecaller number verification is a federated phone check. Instead of you sending a code and waiting for the user to type it back, you ask Truecaller to confirm that the person holding the device owns the number on their Truecaller account. Truecaller already verified that number when the user set up the app, so the trust is reused.

The flow has three actors:

• Your app (Android or web), which holds the Truecaller SDK and a partner key.
• The Truecaller app on the user's device, which shows the consent screen and signs the result.
• Your server, which receives a token and verifies it before trusting the phone number.

At a high level: your app asks for verification, the Truecaller app shows a consent bottom sheet with the user's name and number, the user taps to confirm, and your app receives a payload. That payload is then checked on your server. You never trust the result purely on the client, because a client can be tampered with. The server check is what makes the verification real.

Truecaller's mobile SDK is intended for native Android. For other surfaces, Truecaller exposes a REST flow (sometimes called the OTP-less or mobile number verification API) that does the same job through HTTP calls rather than an in-app bottom sheet. The mental model is identical: request, consent, server-side verification.

One-tap vs the missed-call flow

Truecaller has two ways to verify, and you should plan for both because not every user has the app.

One-tap (user has Truecaller). The Truecaller app is installed and the user is logged in. You trigger verification, the consent sheet appears, the user taps "Continue", and you get a verified profile back. This is the one-tap experience people expect: no code, no typing, done in a second or two.

Missed-call / OTP-less verification (user does not have Truecaller). When the app is not present, Truecaller can still verify the number without you sending an SMS. The user enters their number, and verification completes through a Truecaller-driven check (historically a missed call to a Truecaller number, or a similar OTP-less path). This covers a slice of users who do not have the app but whose number Truecaller can still confirm.

Neither path covers everyone. A user with no Truecaller app and a number Truecaller cannot verify will fail both, which is why the OTP fallback later in this guide matters.

The point is to layer them. Try one-tap first, drop to Truecaller's no-app path if needed, and keep your own OTP as the floor.

SDK setup and the consent screen

Setup is the same shape regardless of platform: register, get keys, declare your app, and render consent honestly.

1. Register on the Truecaller developer portal and create an app. You get a client identifier (often called an App Key or partner key).
2. Bind your app identity. For Android you register your package name and the SHA-1 of your signing certificate so a stolen key cannot be used from another app. For the REST flow you configure allowed origins and credentials server-side.
3. Add the SDK or call the API. On Android you add the Truecaller SDK dependency and initialise it with your key. On other platforms you call Truecaller's verification endpoints from your backend.
4. Render the consent screen. Truecaller controls the bottom sheet, but you choose the call-to-action wording and the consent heading. Keep it truthful: say what you do with the number.

The consent screen is not just UX. Under India's data protection law, consent must be free, specific, informed, and unambiguous, and it must be as easy to withdraw as to give. See the Digital Personal Data Protection Act, 2023, Section 6, on the MeitY site. Do not pre-check anything, do not bury the purpose, and record that consent happened.

NamoID is built to record exactly this. Every provider connection appends an immutable event with a timestamp, the IP, and the scope the user agreed to, which is what gives you a DPDP-grade audit trail without you wiring up logging by hand. If a regulator or the user later asks what was consented to and when, the answer is in the event store.

This section is general information, not legal advice. Confirm your consent and retention design with your own counsel.

Verifying the token on your server

This is the step you cannot skip. The client gives you a payload that claims "this number is verified". You must prove that claim on the server before you create a session.

There are two common shapes depending on which Truecaller flow you used.

One-tap SDK profile. The SDK returns a profile plus a payload and a cryptographic signature. Your server fetches Truecaller's public key, checks the signature over the payload, and confirms the payload was not modified. Only then do you read the phone number from inside the verified payload, never from a field the client could set on its own.

REST / OTP-less flow. You complete the verification request, then call Truecaller's server-side endpoint with your credentials and the request identifier to fetch the verified result. Because the call is server-to-server and authenticated with your secret, the response is trustworthy.

Either way, the rules are the same:

• Trust the server-verified number, not the client-claimed number. A login should key off the value your backend confirmed.
• Bind the result to the session you are about to issue. Do not let a verified payload for one number mint a session for another.
• Check freshness. Reject stale or replayed payloads. Tie each verification to a single login attempt.

A minimal server check looks like this:

# Pseudocode for the server-side verification step.
# Your app sends Truecaller's signed payload + signature to your backend.
curl -X POST https://your-api.example.com/v1/verify/truecaller \
  -H "Content-Type: application/json" \
  -d '{
        "payload": "<base64-payload-from-client>",
        "signature": "<signature-from-client>",
        "signatureAlgorithm": "SHA512withRSA"
      }'

Your handler then verifies the signature against Truecaller's published key, parses the phone number out of the verified payload, and returns a result your auth layer can act on:

{
  "verified": true,
  "phone": "+9198XXXXXX10",
  "source": "truecaller_onetap",
  "verifiedAt": "2026-06-21T09:30:00Z"
}

Inside NamoID, that verified phone becomes a connection on the user, and the verification appends an event. Because NamoID issues RS256-signed JWTs and exposes only its public key via the JWKS endpoint, your downstream services verify the resulting session statelessly. The Truecaller secret stays on your verification path; it never reaches the browser. If you want the deeper background on why we enforce PKCE and rotate refresh tokens on every flow, see PKCE explained.

An OTP fallback strategy

Truecaller will not cover every user, so design the fallback as a first-class path, not an afterthought. The cleanest pattern is a single "verify phone" step that tries the fastest method first and degrades gracefully.

A practical order:

1. Try Truecaller one-tap. If the app is present and the user consents, you are done.
2. Try Truecaller's no-app verification. If the SDK reports the app is missing, attempt the missed-call / OTP-less path.
3. Fall back to your own OTP. If Truecaller cannot verify, send a code over SMS or WhatsApp and verify it yourself.

For the SMS fallback in India, your sender ID and message template must be registered on the DLT (Distributed Ledger Technology) platform mandated by TRAI, or the message gets blocked or scrubbed. TRAI's commercial communication rules are summarised on the TRAI site. We cover the template and channel trade-offs in WhatsApp OTP vs SMS OTP in India.

Whatever channel you use, the OTP itself needs guardrails:

• A short expiry, for example 5 minutes.
• A small attempt cap before the code is invalidated, to stop brute force.
• Rate limiting per number and per IP, so nobody can run up your SMS bill by spamming sends.

NamoID is built so all of these phone paths, Truecaller, WhatsApp OTP, and DLT-compliant SMS OTP, sit behind one issuer. Your app integrates the issuer once. Whether a given user verified by one-tap or by typing a code, the session that comes out the other side looks the same to your code.

When to use Truecaller vs SMS or WhatsApp OTP

There is no single best channel. Pick by where the user is in your funnel and what you are protecting.

Guidance:

• Use Truecaller for speed at the top of the funnel. It removes the OTP step for a large share of Indian users, which lifts conversion on sign-up and login.
• Use WhatsApp OTP where reach is strong and you want a richer, cheaper-than-SMS channel.
• Always keep SMS OTP as the floor. It is the one method that works for any working SIM, so it is your guaranteed fallback.

For higher-risk actions, do not stop at phone verification. Step up to a passkey or TOTP. NamoID supports passkeys (WebAuthn) and TOTP MFA behind the same issuer, so phone verification can be the front door while a stronger factor guards sensitive operations. If you are choosing between the India verification rails more broadly, including DigiLocker and Aadhaar offline KYC, read Aadhaar vs DigiLocker vs offline KYC.

FAQ

Is Truecaller verification secure enough to log a user in by itself?

For low-risk sign-in, yes, as long as you verify the token on your server and never trust a client-claimed number. For sensitive actions like changing a password or moving money, treat phone verification as one factor and step up to a passkey or TOTP.

What happens to users who do not have the Truecaller app?

Truecaller offers a no-app verification path for some of those users, but it will not cover everyone. You need your own OTP fallback over SMS or WhatsApp so that any user with a working SIM can still verify.

Do I need DLT registration to use Truecaller?

Not for the Truecaller flow itself. You need DLT registration for the SMS fallback, because TRAI requires registered sender IDs and templates for commercial SMS in India. WhatsApp uses Meta's template approval instead.

How does NamoID handle Truecaller and consent under DPDP?

NamoID is built to record each provider connection as an immutable event with the timestamp, IP, and consented scope, and to expose a DSAR export of a user's full history. This is general information and not legal advice, so confirm your consent and retention design with counsel. For the engineering view, see our DPDP audit trail guide.

Talk to us

NamoID is pre-launch and ships in a few weeks. If you want Truecaller one-tap, WhatsApp and SMS OTP, passkeys, and India verification rails behind a single OIDC issuer, we would like to show you how it fits together. Book a demo at calendly.com/polymindslabs/30min or email us at hello@namoid.in.