CAMARA Network API Integration

Skip key takeaways

Updated October 4, 2026

• Location Verification returns three answers, not two TRUE, FALSE and PARTIAL each mean something different, and PARTIAL carries a match_rate percentage a boolean field would throw away.
• A SIM Swap null is not a negative result It can mean the operator would not disclose a date under its own privacy rules, which is a different fact than no swap occurred.
• Number Verification only works over the mobile network A device on Wi-Fi without an operator token gets back an authentication error, not a lower-confidence result.
• Quality on Demand creates a session, not a stateless answer The granted duration can differ from the requested one, and nothing warns a client unless it registered a callback.
• CAMARA documents its own error lists as incomplete A client built to fail closed on any undocumented code is working against the specification's own design, not around a gap in it.

Copy takeaways

CAMARA APIs answer questions with more shape than a typical REST integration expects, and getting that shape wrong breaks a client before any business logic runs. Ask Location Verification whether a device sits inside a delivery radius and the answer is not a boolean: "If the network's estimation of the device's location is fully contained within the requested area, the verification result is `TRUE`." and "If the network's estimation of the device's location partially overlaps with the requested area, or it fully contains the requested area (because it is larger), the result is `PARTIAL`. In this case, a `match_rate` is included in the response, indicating an estimation of the likelihood of the match in percent." Ask SIM Swap when a number's SIM last changed and a missing date is not a negative result: "If the latest SIM swap date (or the activation date if no SIM swap) cannot be communicated due to local regulations (or MNO internal privacy policies) preventing the safekeeping of the information for longer than the stated period, a `null` value will be returned." Ask Number Verification to confirm a number over a connection the operator cannot see, and the precondition is stated directly: "For this method of authentication to work, the device must be connected to the mobile network." A device on Wi-Fi with no operator-token fallback gets back 403 NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK, not a generic authentication failure. A boolean location check, a null read as no swap and a connection-agnostic auth call are three assumptions a client can carry in from ordinary API design, and CAMARA breaks all three on purpose.

In short: the table below lines up what each of the four APIs a product team actually calls answers, requires and fails on. The identity and consent layer covers three-legged tokens, CIBA and the purpose scope a request over personal data has to carry. The error model section covers the rule that breaks clients written against a closed set of codes: CAMARA states its own lists are not exhaustive.

What CAMARA is, and what it is not

CAMARA is a specification project, not a single API and not a vendor. Its own site states the arrangement plainly: "CAMARA is an open source project within Linux Foundation to define, develop and test the APIs. CAMARA works in close collaboration with the GSMA Operator Platform Group to align API requirements and publish API definitions." That is the extent of the GSMA relationship any source read for this guide can support. The project publishes its API definitions under an open license, the detail that makes a read-the-spec-and-integrate approach possible at all: "Harmonization of APIs is achieved through fast and agile created working code with developer-friendly documentation. API definitions and reference implementations are free to use (Apache2.0 license)."

The stated reason for an abstraction layer rather than exposing network functions directly is given as three purposes in one breath on CAMARA's own site: "Abstraction by transformation from network capabilities to Service APIs is necessary: To simplify telco complexity making APIs easy to consume for customers with no telco expertise (user-friendly APIs) To satisfy data privacy and regulatory requirements To facilitate application to network integration" The capabilities behind it are partly available in 4G already and considerably more capable in 5G, framed as functions the network both reports through and can be configured by, not a read-only data feed. One paragraph on what sits underneath, since nothing read for this guide reaches into 3GPP territory: an operator's own CAMARA implementation sits in front of the mobile core function 3GPP specifies for exposing capabilities outward, generally known as the Network Exposure Function, and nothing here describes how that function behaves internally, since no 3GPP specification was consulted. What CAMARA adds on top, as an engineering read rather than a specification claim, is a stable, versioned HTTP contract that does not have to change when an operator changes what runs behind it.

There is no single CAMARA version a product targets: each API repository ships its own release on its own schedule. At the time this guide was written, Number Verification, Device Location and Quality on Demand were current at r3.2, SIM Swap at r3.3, and Identity and Consent Management on its own cadence at r4.2. Every one of the four API repositories, Number Verification, SIM Swap, Device Location and Quality on Demand, carries a warning about its own default branch: an integration reading specification files from main rather than a tagged release is reading a target the project does not promise will stay the same.

The four APIs, side by side

Each row stands on its own: the answers and auth-flow columns come from the API definitions; the failure mode is Pharos Production integration experience, not a specification claim.

API	What it answers	Auth flow	Failure mode seen in practice
Number Verification	Is the phone number the user typed the number of the SIM in the device making this request	Three-legged token with a dedicated scope, obtained by mobile-network authorization code, or by CIBA or JWT bearer carrying a GSMA TS.43 operator token	The device is on Wi-Fi and the integration holds no operator token, so a legitimate user gets a 403 the team never designed a fallback for
SIM Swap	When did the SIM behind this number last change, or did it change within a stated window	Three-legged token identifies the number from the token itself; two-legged token requires phoneNumber in the request body and must not carry a three-legged token at the same time	A null retention response is read as no swap occurred, when it means the operator could not disclose the date, and the check it exists for never fires
Location Verification	Is the device inside this circle, as far as the network's own estimate can tell	Same two-legged against three-legged identification rule, with the device object in place of the phone number	PARTIAL is mapped to a boolean at the first integration point, so the match_rate percentage never reaches the decision that needed it
Quality on Demand	Give this application flow a stable latency or throughput profile for a requested duration	Same identification rule; the call creates a session resource with a lifetime rather than answering a stateless query	The granted duration is assumed to equal the requested one, so sessions expire mid-experience with no callback registered to hear about it

Number Verification: a check that never asks the user anything

The API answers one question two ways, and the specification is explicit about which side does the comparison. The Number Verification definition states: "The Number Verification API is used by the API consumer to perform real-time checks to verify the phone number of a mobile device being used to access the application. This check can be done either by the API provider, returning "true" or "false", or by the application, by matching the phone number returned by the API Provider with the phone number of the device that is being used." Two endpoints answer two different product questions rather than one: a verify call takes a number the user typed and returns whether it matches the SIM in the requesting device, while a device-phone-number call simply returns the number associated with that SIM.

What makes either endpoint useful without an SMS code or a password is that the network already knows the answer: "A network operator knows to which subscriber a connected mobile phone belongs and what its associated phone number is." That is why the specification calls SMS one-time passwords and username-password logins incompatible with the API: the goal is validating the number accessing the application, not asking the person holding it to prove anything.

The precondition is stated as plainly as the mechanism: "For this method of authentication to work, the device must be connected to the mobile network." The specification requires a three-legged access token with a dedicated scope obtained over that same mobile-network authentication, and the error it defines for the mismatch reads like an operational note rather than a security policy: "Client authentication was not via mobile network. In order to check the authentication method, AMR parameter value in the 3-legged user's access token can be used and make sure that the authentication was not either by SMS+OTP nor username/password". In practice that is 403 NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK, and it fires for the ordinary case of a user on Wi-Fi rather than for anything unusual. The definition does describe a Wi-Fi-compatible path for a consumer already holding a GSMA TS.43 operator token, carried through CIBA or a JWT bearer assertion instead of the mobile-network authorization code, a fallback worth designing for up front rather than discovering after the first support ticket.

SIM Swap: what a null actually means

The API answers two related questions, framed by its own definition as a pair: "When did the last SIM swap occur?" and "Has a SIM swap occurred during last n hours?" A SIM swap here is broader than the fraud case that usually motivates the API: "A SIM swap is a process in which a user's mobile phone number (MSISDN) is associated with a new SIM card (IMSI). This is typically done by contacting the user's mobile service provider and requesting a new SIM card for various reasons, such as a lost or damaged SIM card or upgrading to a new phone." The same definition also counts a phone number change, a provider change that keeps the number and a new subscription landing on a previously used number as SIM swaps, so a risk engine built only for the lost-SIM case passes the other cases straight through.

Because a missing date is not a negative result, the retention limit is the fact worth designing around. The specification is explicit: "If the latest SIM swap date (or the activation date if no SIM swap) cannot be communicated due to local regulations (or MNO internal privacy policies) preventing the safekeeping of the information for longer than the stated period, a `null` value will be returned." An operator whose own privacy threshold is tighter than the specification's ceiling, which runs from 1 to 2400 hours on the monitored-period check, answers with 400 OUT_OF_RANGE instead of a date, an explicit error rather than a silent narrowing. Reading either response as no swap is where the check the API exists to support quietly stops working.

Identification follows the same two-legged against three-legged rule the other three APIs share: supplying both a token-derived identity and an explicit phone number, or neither, is a caller error the server will not resolve by itself, returning 422 MISSING_IDENTIFIER or 422 UNNECESSARY_IDENTIFIER.

Location Verification: a ternary answer, not a boolean

The input is narrower than most product teams assume: only a circle is supported as the area to check, given as coordinates plus a radius, never a polygon or a street address. What comes back is a statement about the network's own estimate rather than a fact about the device. The definition states: "The verification result depends on the network's ability and accuracy to locate the device at the requested area." Two of three outcomes read like a boolean; one does not: "If the network's estimation of the device's location is fully contained within the requested area, the verification result is `TRUE`." and "If the network's estimation of the device's location partially overlaps with the requested area, or it fully contains the requested area (because it is larger), the result is `PARTIAL`. In this case, a `match_rate` is included in the response, indicating an estimation of the likelihood of the match in percent." An integration that collapses the response onto a two-value field, true for TRUE and false for anything else, discards the one number the API adds that a plain geofence never had.

The specification defines verification as a directional check rather than a raw coordinate lookup: the client asserts an area and the network's job is to confirm or contradict that assertion, never to hand back a latitude and longitude the client did not already supply. Four error codes separate the cases the network itself cannot answer: the requested area sits outside operator coverage, the area is malformed, the device cannot be located at all, or the location record on file is older than the caller's stated maxAge tolerance. A less obvious failure sits in shared devices rather than in coverage: "In multi-SIM scenarios, where more than one mobile device is associated with the phone number given as input in the API call (e.g. a smartphone with an associated smartwatch), it might not be possible to uniquely identify the device whose location is to be verified." A phone number is not always one device, and the specification names that ambiguity directly.

Quality on Demand: a session with a lifetime, not a query

Quality on Demand is the odd one out among the four, because it does not just answer a question, it creates something. The specification frames the request as picking from a menu rather than dialing in a number: "The developer has a pre-defined set of Quality of Service (QoS) profiles which they could choose from depending on their latency or throughput requirements." What a client actually creates is a resource with its own lifecycle: "The usage of the API is based on QoS session resources, which can be created (based on available QoS profiles), queried and deleted. The deletion of a requested session can be triggered by the API consumer or can be triggered automatically once the QoS session has reached its limit." Duration is a request, not a promise: "Implementations can grant the requested session duration or set a different duration, based on network policies or conditions." A client that assumes the granted window equals the requested one will find a session it still thinks is active has already ended.

The device a session applies to is addressed by one of four identifiers, phone number among them, and status changes reach the consumer only if it asked for them: the specification lets the caller register an optional callback URL that receives a CloudEvents-compliant notification on events such as session termination. No callback registered means no warning before a session simply stops. The one profile-availability failure worth naming happens without any change on the consumer's side at all: a QoS profile that exists but has gone inactive or deprecated at the operator returns 422 QUALITY_ON_DEMAND.QOS_PROFILE_NOT_APPLICABLE, a working integration breaking on the provider's own catalog change rather than on anything the client did. The QoS profiles surface has already moved once, carved out of this same repository into one of its own, a live example of how much a CAMARA API's surface can shift between releases.

The identity and consent layer

Every one of the four APIs sits behind the same architectural decision rather than behind its own login system. The identity and consent model states it directly: "The concept common to all flows is that the access token used to invoke an API is created at the Authorization Server, and the API endpoint (Resource Server) grants access to the API based solely on the access token." That separation is deliberate: "This separation of concerns places all responsibility for implementing legal and business concerns under the authority of the Authorization Server, freeing the Resource Server from the need to worry about them." An API implementation never decides whether a user consented to anything; it only ever checks the token it was handed.

Two token shapes carry that decision, and only one fits the four APIs described here. A two-legged token has no resource owner attached and "must only be used for CAMARA APIs that do not process Personal Data." A three-legged token involves the resource owner, the authorization server and the client, produced by an authorization code flow, CIBA or a JWT bearer flow, and the rule for when it is required has no hedging: "Note: In cases where Personal Data is processed by a CAMARA API, and Users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of Three-Legged Access Tokens is mandatory." All four APIs here identify or affect a specific subscriber, so none is a candidate for a two-legged-only integration.

CIBA exists for the case where a redirect through the user's browser is not available at all, and the OpenID specification is precise about what that changes: "OpenID Connect Client Initiated Backchannel Authentication Flow is an authentication flow like OpenID Connect. However, unlike OpenID Connect, there is direct Relying Party to OpenID Provider communication without redirects through the user's browser." The base specification defines three delivery modes for the authentication result, poll, ping and push, but CAMARA's own security profile narrows that to poll only and makes the login_hint parameter mandatory rather than optional, less freedom than the OpenID specification alone would suggest.

Purpose is a formal parameter here rather than a comment field: exactly one purpose per authorization request, carried inside the OAuth2 scope value with a dpv: prefix drawn from a shared vocabulary, required whenever the request touches personal data. Who counts as an end user is also more specific than the account holder: the same glossary separates the subscriber on the account from the end user actually affected and from the device the API call actually targets, roles a single mobile subscription does not automatically collapse into one person. That glossary also defines an aggregator as a party that aggregates operator APIs and exposes services built on them to application providers, against direct integration with a single operator's own authorization server and API gateway; which of the two an integration uses is a commercial decision the specification leaves outside its own scope.

The error list is not exhaustive, by design

Number Verification, SIM Swap, Location Verification and Quality on Demand each carry the same warning about their own error list, word for word: "The list of error codes in this API specification is not exhaustive." A client that switches on a closed set of codes and treats anything else as unexpected is not handling an edge case badly, it is wrong by design, since the specification itself defers the complete list to a separate Commonalities release document rather than enumerating it in any single API. 501 NOT_IMPLEMENTED is the one exception worth naming, valid only when the specific API documents it, not something to expect by default. Every error body shares the same three required fields regardless of which API returned it: a numeric status, a string code and a human readable message, and the code itself follows one convention across the whole family. A generic code is bare, an API-specific one is prefixed with the API's own name and a dot, which is why a location failure reads LOCATION_VERIFICATION.AREA_NOT_COVERED rather than a code shared with the other three.

x-correlator and pinning a release

x-correlator is worth exactly one paragraph, because the specification gives it exactly that much: declared as both a request parameter and a response header, attached to every response including every error, and defined as a free-form string of at most 256 characters from a restricted character set, with a UUID shown as the example value. Its own description is four words long, a correlation id for the different services, which leaves the real operational question, how to generate one, propagate it across an aggregator and an operator, and log it consistently, entirely to whoever integrates the API. Treat it as a header worth logging from day one, not as a compliance requirement the specification hands anyone.

Pin a release tag rather than a default branch, for the reason stated above: every one of these repositories can revert or rewrite what its default branch contains before the next release is cut. This guide's own citations follow that rule, taken from a named release, r3.2, r3.3 or r4.2, never from a default-branch file that could read differently the next time this page is fetched.

How Pharos Production helps

Integrating CAMARA well is four decisions made once rather than once per API: a token strategy that defaults to three-legged wherever personal data is involved, a client that reads a ternary result and a nullable date as the specification actually defines them rather than as a boolean and a negative, an error handler that expects codes outside the documented list rather than failing closed on the unfamiliar ones and a release-tag pin that gets revisited on a schedule rather than left pointed at whatever tag happened to be current on the day the integration shipped.

Our telecom software development guide covers the wider platform this sits inside, and our eSIM provisioning integration guide covers the adjacent identity question of which SIM profile is active in the first place. Our telecom software development team builds the token handling, the error mapping and the operator-facing integration layer this guide describes, on top of whatever OSS or BSS stack a network already runs.

Sources: CAMARA Project, a Linux Foundation project, on camaraproject.org; the CAMARA API specification repositories on GitHub, NumberVerification, SimSwap, DeviceLocation, QualityOnDemand and IdentityAndConsentManagement, cited at their pinned release tags; the OpenID Foundation's CIBA Core 1.0 specification on openid.net. Read on 21 September 2026. Engineering guidance, not legal advice.

FAQ

Last updated: October 4, 2026

Quick answers to common questions about custom software development, pricing, process and technology.

Expand all Collapse all

Search FAQs

Popular

Type to filter questions and answers. Use Topic to narrow the list.

Showing all 6

• Does an integration need all four CAMARA APIs, or just one?

  Featured question. Copy link Copies a direct link to this answer to your clipboard.

  Almost never all four at once, in our experience at Pharos Production. The four solve different problems: Number Verification and SIM Swap are usually paired inside a sign-up or login flow to strengthen or replace an SMS one-time password, Location Verification fits a delivery, ride-hailing or geo-fenced compliance check and Quality on Demand fits a real-time media or gaming session that needs a temporary network guarantee rather than an identity check at all.

  A team that reaches for all four because they share one authorization model is usually solving one problem with four APIs instead of one API with the right shape for it. Start from the product question, not from the catalog.

• What happens if the operator on the other end of a request has not implemented the API this integration needs?

  Copy link Copies a direct link to this answer to your clipboard.

  The request fails, and this guide deliberately does not tell a reader which operators support which API, because that kind of coverage table goes stale within a release cycle and none of the sources read for this guide name a single operator. What the specification does support is planning for the gap: agree during onboarding, before any code ships, on which flow and which APIs an operator or aggregator actually exposes, and design the product path so a missing API degrades to a fallback, such as an SMS code, rather than to a hard failure the user sees.

• Is CIBA mandatory, or can an integration use an ordinary OAuth2 authorization code redirect instead?

  Copy link Copies a direct link to this answer to your clipboard.

  CIBA is one option among the flows CAMARA names, not a replacement for the authorization code flow. The authorization code flow still works wherever the consuming application can put the user through a browser redirect, which covers most web and app sign-in journeys.

  CIBA earns its complexity specifically where no redirect is possible on the device actually being verified, for example a background check tied to a different authentication device than the one the user is looking at. Choosing CIBA by default when a redirect would have worked adds an out-of-band channel and a polling loop for no benefit.

• How should a client handle an error code the specification does not document?

  Copy link Copies a direct link to this answer to your clipboard.

  Treat an unrecognized code as a distinct, loggable case rather than folding it into a generic failure path, because the specification states outright that its documented list is not exhaustive. Our practice at Pharos Production is to log the full ErrorInfo body, including the unfamiliar code, alert on a new code seen for the first time and only then decide whether the integration needs a specific handler for it.

  A client that maps every undocumented code to the same generic error message will misreport a partial network problem as a total one, or the reverse, and will not learn the difference until a user complains.

• Does GSMA Open Gateway change any of this?

  Copy link Copies a direct link to this answer to your clipboard.

  Nothing in this guide rests on that name, and it should not, on the evidence available. CAMARA's own site states only that it works in close collaboration with the GSMA Operator Platform Group to align API requirements and publish API definitions, which is the full extent of the GSMA relationship any source read for this guide can support.

  Nothing here describes a separate commercial program, a coverage guarantee or a distinct product under that name, because no source consulted named one. Build against the CAMARA API definitions themselves and treat any commercial packaging around them as a separate, operator-specific conversation.

• What is the practical difference between an aggregator and integrating an operator directly?

  Copy link Copies a direct link to this answer to your clipboard.

  CAMARA's own glossary defines the aggregator role as a party that aggregates several operators' APIs and exposes its own service on top of them, against an operator's own platform exposing its APIs directly. In our experience the trade lands on contracts and surface area rather than on the API contract itself, since both paths speak the same CAMARA definitions: an aggregator usually means one commercial relationship and one integration surface across several operators, at the cost of a middle party between the product and the network, while a direct integration means a separate relationship and a separate onboarding conversation per operator, in exchange for nothing standing between the product and the source of the answer.

  Neither path is specified as better; it is a sourcing decision, not an engineering one.

I work with startup founders who need a dedicated software development team but don’t want to gamble on hiring, random outsourcing, or opaque delivery.
Most founders face the same problem sooner or later.
Early technical and team decisions lock the product into tech debt, slow delivery, missed milestones and constant re-hiring. By the time this becomes visible, fixing it is already expensive.

As a CTO and software architect, I help founders design, build and run dedicated development teams that work as a true extension of the startup. Not as a black-box vendor.

My focus is on complex products where mistakes are costly:

• Web3 and blockchain platforms
• FinTech and regulated products
• High-load startup systems
• MVP → scale transitions

We don’t do body-shopping.
We don’t sell generic outsourcing.

Instead, we help founders:

• build the right team structure from day one
• keep technical ownership and transparency
• scale delivery without losing control
• avoid vendor lock-in and hidden risks

Teams are aligned with the product roadmap, business goals and long-term architecture. Not just short-term velocity.