Mobile Network Identity APIs: Number Verify and SIM Swap Signals

SMS one-time passcodes prove only that someone can receive a text, and mobile network identity APIs let a service ask the operator directly whether a phone number really belongs to the device in front of it and whether its SIM changed recently. The CAMARA project at the Linux Foundation publishes open definitions for these APIs, and mobile operators expose them commercially through the GSMA Open Gateway initiative. This guide explains the three most used for identity and fraud: Number Verification, SIM Swap and KYC Match. It covers how each works, the OAuth and OpenID Connect profile behind them, privacy and consent, and how to wire the signals into onboarding, login and payment risk decisions. It is written for identity architects, fraud teams and developers. The attack itself is covered in the SIM Swap Fraud Guide; this page is about the defensive APIs.

Key takeaways

• Number Verification is silent possession proof. It confirms the phone number of the SIM in the device using network-based or SIM-based authentication, with no user interaction and no SMS.
• SIM Swap is a risk signal, not an authenticator. It returns the date of the last SIM change or whether one happened within a window you choose (1 to 2400 hours in the specification), so you can hold a risky action.
• KYC Match checks data without exchanging it. You send the attributes a customer typed; the operator returns true, false or not_available per attribute, and where supported, a 0 to 100 similarity score.
• The security profile is strict. CAMARA requires private_key_jwt client authentication, recommends signed requests and PKCE, and for Number Verification mandates single-use access tokens that last no more than 300 seconds (as stated in the API definitions on the main branch in November 2026; check the release your operator supports).
• Coverage varies by operator and country. Each operator decides which APIs, versions and monitoring windows it supports, so design for a not_available or error path every time.

What it is and who it applies to

CAMARA is an open source project within the Linux Foundation that defines, develops and tests telco network APIs, published under the Apache 2.0 licence. It works with the GSMA Operator Platform Group to align requirements. GSMA Open Gateway is the GSMA initiative through which operators offer these capabilities commercially; a GSMA release of 3 December 2024 said 67 mobile network groups, representing 278 networks, had joined, and that Bouygues Telecom, Free, Orange and SFR would launch KYC Match, SIM Swap and Number Verification in France, targeting commercial launch in the first half of 2025.

CAMARA groups these under authentication and fraud prevention, a family that also includes Device Swap, Call Forwarding Signal, Number Recycling, KYC Fill-in, KYC Age Verification, KYC Tenure and One Time Password SMS. This guide sticks to the three most used in identity flows.

Repositories note that there are no compatibility guarantees for the main branch until a release is made. Always build against a released version and the version your operator or aggregator states it supports.

Structure and key requirements

Number Verification

The API offers two endpoints, both requiring a three-legged access token:

• POST /verify: you send the number the user registered, as plain text or as a SHA-256 hash in hexadecimal of the E.164 number including the plus sign. The response is true or false.
• POST /device-phone-number: returns the number the operator associates with the SIM in the device.

The specification says the API provider guarantees no user interaction and that SMS OTP or username and password are incompatible with the flow. Without a GSMA TS.43 temporary token, the consumer uses the OpenID Connect Authorization Code Flow with prompt=none, and the device must be on the mobile network. With a TS.43 temporary token, it can work over any connection, including Wi-Fi, through a CIBA request or a JWT-Bearer token request. The access token must be single use, must not exceed 300 seconds and must not come with a refresh token.

SIM Swap

• POST /retrieve-date: returns latestSimChange as an RFC 3339 timestamp. Where no swap has happened and the operator supports unlimited monitoring, it returns the activation date. Where local rules or operator policy stop it keeping the date, the value is null and an optional monitoredPeriod (in days) tells you the window in which no swap occurred.
• POST /check: takes maxAge in hours, from 1 to 2400 with a default of 240, and returns whether a swap occurred in that period. An operator with a shorter privacy window returns 400 OUT_OF_RANGE.
• Subscriptions: the separate sim-swap-subscriptions API lets you receive notifications rather than poll.

The specification describes SIM swap broadly: a new SIM for the same number, but also number porting to another provider and activating a new SIM on the same line. Expect legitimate swaps in your data.

KYC Match

A single POST /match endpoint compares the attributes you send, such as idDocument, givenName, familyName, address, birthdate and email, against the operator's verified KYC record. Each attribute returns true (equal to a score of 100), false or not_available. Where the operator supports scoring, a match score from 0 to 100 can be returned per attribute, using the Jaro-Winkler algorithm unless the operator's implementation notes say otherwise. The response only contains the attributes you asked about.

Two-legged or three-legged tokens

Identity and NHI requirements

Every call to these APIs is made by a machine identity: your backend client registered with the operator or an aggregator. The CAMARA Security and Interoperability Profile sets the rules for that client.

• Client authentication: the API consumer must authenticate to the authorisation server with private_key_jwt. There is no shared client secret to leak, but the private signing key becomes the crown jewel. Keep it in an HSM or a managed key service and rotate it. See the Secrets Management Guide.
• Signed requests: signed authentication requests are recommended, and the authorisation server must support them; the request object must carry iss, aud, iat, exp and jti.
• PKCE: recommended for the Authorization Code Flow, with state and nonce handling required where it is not used.
• Purpose: the consumer declares purpose as a scope in the form dpv:<value> using W3C Data Privacy Vocabulary purposes. The operator decides from scope and purpose whether user consent is needed under local law.
• CIBA: poll mode only, with login_hint required, formatted as a tel URI in E.164.
• Refresh tokens: a new access token must not be issued once the user has revoked consent.

Treat the API client as a privileged non-human identity: one client per environment and purpose, keys never in source code, access logged, and the client's permitted scopes reviewed when the product changes. For OAuth and OIDC client design generally see the OAuth 2.0 and OpenID Connect Guide.

Implementation steps

1. Map the decision points. List where you currently send SMS OTP or trust a phone number: sign-up, login, recovery, payee creation, payment, contact detail change.
2. Pick the signal per point. Number Verification where the user is on a mobile device and you need possession proof; SIM Swap before any action that relies on the number; KYC Match at onboarding.
3. Choose access route. Contract directly with operators or through an aggregator. Confirm per country which APIs, versions, monitoring windows and token types are supported.
4. Register the client securely. Generate the private_key_jwt key pair in a key vault, register the public key, and declare purpose scopes accurately.
5. Write the privacy basis. Record the lawful basis and purpose, update your privacy notice and, where the operator requires consent, design the consent step. Complete a DPIA for KYC Match. See the DPIA Guide.
6. Design fallbacks. Every call can return not_available, null, OUT_OF_RANGE or an error, and Wi-Fi users may not reach the network flow. Decide the fallback (another factor, manual review, delay) before launch.
7. Pilot in monitor mode. Call the APIs and log results without acting on them for a few weeks; measure coverage, latency and how often SIM swap results coincide with confirmed fraud.
8. Enforce gradually. Start with step-up or delay on a recent swap, then block only where fraud data supports it. Keep a feature flag to roll back to the previous flow.

Decision guidance

Smaller firms usually buy through an aggregator for one contract and many operators. Large banks and platforms often contract with major operators directly for price and service levels. Either way, these APIs complement phishing-resistant authentication; they do not replace it. See the Phishing-Resistant MFA Guide.

Evidence and assessment

• Per-decision logs: API called, version, operator, result, x-correlator value and the action taken, without storing more personal data than needed.
• Coverage report: share of customers per country and operator for whom each API returns a usable result.
• Privacy file: lawful basis, declared purpose scopes, consent design where needed and the DPIA.
• Key management records: where the private_key_jwt key lives, who can use it and when it was last rotated.
• Policy record: thresholds such as the SIM swap window, with the fraud data that justified them.

Metrics

• SMS OTP reduction: share of verifications completed by Number Verification instead of SMS.
• SIM swap hit rate: recent-swap results per 10,000 checks, and the share later confirmed as fraud.
• Fallback rate: calls ending in not_available, null, OUT_OF_RANGE or error.
• Account takeover via SIM swap: confirmed cases per quarter, before and after enforcement.
• Added latency: 95th percentile response time per API and operator.

Mapping to other frameworks

For how SMS and telephone-based authenticators are treated in US federal guidance, see the NIST SP 800-63B-4 Authenticator Assurance Levels Guide.

Common pitfalls

• Treating Number Verification as strong MFA: it proves the SIM is in the device, not who holds the device. Use it as possession evidence alongside other signals.
• Blocking on every swap: new phones, porting and eSIM activation all register as SIM changes. Step up or delay instead of hard-blocking.
• Assuming a null date means safe: null can mean the operator cannot keep the data; read monitoredPeriod and treat absence of data as unknown.
• Weak client key handling: a private_key_jwt key stored in a config file defeats the profile. Keep it in a vault or HSM.
• Over-collecting for KYC Match: send only the attributes you need and do not store scores longer than your retention policy allows.
• Building on main: unreleased definitions change. Pin to the released version your provider supports.

Practitioner checklist

• List every flow that trusts a phone number and decide which API, if any, protects it.
• Confirm API, version, token type and monitoring window per operator and country.
• Store the private_key_jwt signing key in an HSM or managed key service and rotate it.
• Declare accurate dpv purpose scopes and record the lawful basis and consent design.
• Check SIM Swap before sending SMS OTP and before payee, payment and recovery actions.
• Handle not_available, null, OUT_OF_RANGE and errors with a defined fallback.
• Run in monitor mode first and tune thresholds from your own fraud data.
• Log the x-correlator and decision for every call for investigations.
• Pin to released CAMARA versions and track the Spring and Fall releases.

Standards and references

• CAMARA: Number Verification API repository
• CAMARA: SIM Swap API repository
• CAMARA: Know Your Customer API repository
• CAMARA: Identity and Consent Management, Security and Interoperability Profile
• CAMARA: The Telco Global API Alliance
• GSMA: French mobile industry accelerates deployment of network APIs through GSMA Open Gateway

Related NHI Mgmt Group resources: SIM Swap Fraud Guide · Account Takeover Prevention Guide · Authenticator Apps and OTP Guide · Identity Proofing and KYC Guide