Add match-identifier endpoint

[ALIIQBAL786]

What type of PR is this?

Add one of the following kinds:

• enhancement/feature

What this PR does / why we need it:

Introduces a new POST /match-identifier endpoint to the Device Identifier API. This endpoint allows an API consumer to check whether a device identifier they provide (IMEI, IMEISV, or TAC) matches the one the network currently associates with a given mobile subscription, returning a simple boolean result (match: true/false) instead of exposing the actual device identifier.

This addresses data minimisation concerns — in use cases such as fraud prevention, device-based KYC, account takeover protection, and digital onboarding, partners only need a binary signal ("does this device match?") rather than the full IMEI/TAC/PPID. The new endpoint aligns with the match/verify patterns already established in other CAMARA APIs (e.g. SIM Swap, Device Status).

Which issue(s) this PR fixes:

Fixes #146

Special notes for reviewers:

The new endpoint reuses all existing shared components (Device, RequestBody, CommonResponseBody, DeviceResponse, error responses) — no duplication was introduced.
MatchRequestBody extends RequestBody via allOf, so the optional device object for 2-legged access tokens is inherited, not redefined.
The MatchResult schema only contains the match boolean; device and lastChecked come from CommonResponseBody, consistent with how DeviceIdentifier, DeviceType, and DevicePPID are composed in the other 200 responses.
No IMEI/TAC/PPID is exposed in the match response — only the boolean and optional metadata from CommonResponseBody.
The endpoint name /match-identifier is a working name and open to discussion.

Changelog input

 Added new POST /match-identifier endpoint to Device Identifier API, enabling boolean match verification of a provided device identifier (IMEI, IMEISV, or TAC) against the network's current association for a subscription, without exposing the actual device identifier in the response.

Additional documentation

The new /match-identifier endpoint is fully documented inline in the OpenAPI specification (device-identifier.yaml), including description, request/response schemas, examples for all supported identification methods (3-legged token, phone number, IP address, multiple identifiers), and integration with existing error handling. No separate documentation changes are required.

[AxelNennker]

Allow matching PPID

[AxelNennker]

Suggested change

	enum:
	enum:
	- PPID

[AxelNennker]

The API consumer would check that the PPID have associated with their end-user's account is the same as the last time.

[albertoramosmonagas]

Hi @AxelNennker, I understand the use case you’re describing, but from my side, that use case is already covered by the existing retrieve-ppid endpoint: the client stores the PPID and simply compares the new value with the one they had before. We don’t really need a new /match-identifier call for that.

The whole point of /match-identifier was to offer a PPID-free, data-minimising binding check for cases where the partner has an IMEI/TAC and only wants a yes/no answer from the network. If we allow PPID as a providedIdentifierType, this endpoint stops being that alternative and essentially becomes “verify my persistent token”.

I’d strongly prefer to keep providedIdentifierType limited to IMEI / IMEISV / TAC and rely on retrieve-ppid for PPID-based checks.

[AxelNennker]

Why should the whole-point be to provide a ppid free endpoint? PPID is the privacy respecting and data-minimizing alternative to the other identifier. "verify my token" is good.
Regarding access tokens, it is more secure to have a match-identifer access token on file compared to a retrieve-identifier access token. Storing IMEI/IMEISV makes then easier to steal and to use for tracking a sites that are not privacy respecting as sites that use PPID.

For example if the API consumer is selling phone insurance that is bound to the device identifier then they should use the PPID. We should reduce the use of IMEI etc to get to a more privacy friendly environment or charge 10 times for the IMEI compared to the PPID.

Globally unique, persistent identifiers esse delendam.

[albertoramosmonagas]

Thanks Axel, I really see your point: for use cases that need a long-lived device binding, PPID is clearly preferable to exposing raw IMEI/IMEISV. Your phone-insurance example fits exactly there, and from my side retrieve-ppid is the right tool in that scenario.

Where I think this endpoint is targeting a different class of use cases:

• In many fraud / ATO / KYC flows, partners explicitly do not want to store any persistent token at all (neither IMEI nor PPID). They already have an IMEI/TAC in their flow and only want to ask the network:

  “For this subscription and this device identifier, do you currently see the same device, yes or no?”

• In that context, a one-shot boolean is even more data-minimising than introducing a reusable PPID, even if PPID is better than IMEI when persistence is needed.

Also, the “verify my token” pattern for PPID is already possible today with retrieve-ppid + client-side comparison; the network doesn’t really add new semantics there.

That’s why, at least for this first version, I would keep /match-identifier scoped to IMEI/IMEISV/TAC only, and leave PPID verification to retrieve-ppid. That way we preserve a clear separation:

• PPID = persistent pseudonymous binding when you actually need it
• /match-identifier = PPID-free, point-in-time binding check for flows that only need a yes/no answer.

[ALIIQBAL786]

@AxelNennker, I guess there is no need for PPID in this endpoint.
As:

The “verify my token” pattern for PPID is already possible today with retrieve-ppid + client-side comparison; the network doesn’t really add new semantics there.

[AxelNennker]

Suggested change

	MatchDeviceByPhoneNumber:
	MatchDeviceByPhoneNumberProvidePPID:
	description: Matching device identifier by phone number and provided PPID
	value:
	device:
	phoneNumber: "+123456789"
	providedIdentifierType: "PPID"
	providedIdentifier: "b083f65ccdad365d7489fff24b6d5074b30c12b6d81db3404d25964ffd908813"
	MatchDeviceByPhoneNumber:

[albertoramosmonagas]

The PR currently defines 200 as: match (bool) + lastChecked from CommonResponseBody.

However, it does not explicitly differentiate between:

• false because the IMEI/TAC does not match,
• false because no device info is available,
• or cases where it should be 422 (not applicable) or 5xx (inconclusive/technical failure).

Do we want to reserve an optional field of type result (e.g., MATCH, MISMATCH, NO_DEVICE_INFO, INCONCLUSIVE) in CommonResponseBody or MatchResult, even though only MATCH/MISMATCH are currently used?

[albertoramosmonagas]

If not, at the very least, it must be made clear in the description of /match-identifier that:

• 404 = subscription not found
• 422 = subscription found but service not applicable (due to policy/segment, etc.)
• 200 + match=false = valid subscription and known device, but mismatch (not “no info”).

What do you think?

[ALIIQBAL786]

We should go with the second option B:

I'd recommend not introducing a result enum (MATCH, MISMATCH, NO_DEVICE_INFO, INCONCLUSIVE) at this stage for the following reasons:

CAMARA design minimalism, speculative fields create contract obligations before those scenarios are well-defined.

Boolean is sufficient, the endpoint answers a binary question; edge cases like "no device info" are error conditions, not match results.

Consistency, other CAMARA match/verify APIs (e.g., Number Verification) use plain booleans
Non-breaking extensibility, an optional enum can always be added later without breaking existing consumers.

[albertoramosmonagas]

Thanks Ali, I'm fine with going with option B and keeping minimal for now. If we treat “no device info” / “not applicable” strictly as error conditions rather than match outcomes, then I think it becomes even more important to spell out the HTTP mapping explicitly in the spec. Something along these lines would already solve my concern:

• 404 Not Found → subscription cannot be resolved from the device / token.
• 422 Unprocessable Content → subscription is resolved, but the service cannot provide a result in a deterministic way (e.g. no device info available for this line, or local policy/regulation prevents returning the information) – i.e. business / applicability issues, not technical ones.
• 200 with match = false → subscription resolved and device info available, comparison successfully performed, and the identifiers do not match (not “no info” / “not applicable”).

This keeps the response body minimal (just match + lastChecked), reserves false for a real mismatch, and aligns with your point that other match/verify APIs also rely on boolean + HTTP status to convey the outcome.

We can further reinforce this behaviour later on in the test suite, but having this mapping clearly stated in the description of /match-identifier would already give implementers a very concrete contract to follow.

[albertoramosmonagas]

One question: if we are using 3-legged, does it make sense to keep the phoneNumber here? I understand that this example would be for Multiple Identifiers? or just remove the phoneNumber?

[ALIIQBAL786]

Updated the descriptions of status codes