Skip to content

Add match-identifier endpoint #151

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ALIIQBAL786 wants to merge 12 commits into
base: main
Choose a base branch
from
Open

Add match-identifier endpoint #151

Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
530dbe7
Add match-identifier endpoint
ALIIQBAL786 Feb 12, 2026
dcf91a1
Update code/API_definitions/device-identifier.yaml
ALIIQBAL786 Feb 16, 2026
52a142c
Update code/API_definitions/device-identifier.yaml
ALIIQBAL786 Feb 16, 2026
2b82699
fix: correct IMEI (15 digits) and IMEISV (16 digits) example values
ALIIQBAL786 Feb 16, 2026
1db3078
Updated the descriptions of status codes
ALIIQBAL786 Feb 17, 2026
1e76563
Fixed linting issues
ALIIQBAL786 Feb 17, 2026
ef50085
Added regex patterns
ALIIQBAL786 Feb 17, 2026
c58212d
Fixed linting issues
ALIIQBAL786 Feb 17, 2026
7ed5b1c
Update code/API_definitions/device-identifier.yaml
ALIIQBAL786 Mar 31, 2026
142f2d4
Update code/API_definitions/device-identifier.yaml
ALIIQBAL786 Mar 31, 2026
fc9764b
Merge branch 'camaraproject:main' into endpoint-branch
ALIIQBAL786 Mar 31, 2026
fbdab86
Update device-identifier.yaml
ALIIQBAL786 Mar 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
206 changes: 193 additions & 13 deletions code/API_definitions/device-identifier.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,27 +59,29 @@ info:

# API functionality

The API defines three service endpoints:
The API defines four service endpoints:

- `POST /retrieve-identifier` to get details about the specific device being used by a given mobile subscriber, including IMEI / IMEISV and the type of device
- `POST /retrieve-type` to get details only about the type (i.e. manufacturer and model) of device being used by a given mobile subscriber
- `POST /retrieve-ppid` to get a pseudonymised identifier for the specific device being used by a given mobile subscriber
- `POST /match-identifier` to check whether a device identifier provided by the API consumer matches the one the network currently associates with a given mobile subscription

To call any of these endpoints, the API consumer must first obtain a valid access token from the token endpoint, which is then passed as an Authorization header. When a 2-legged access token is used, the API consumer must also pass at least one of the available mobile subscription identifiers in the body of the request.

If the request is valid, the API response is a JSON object containing the data that the end user has consented to sharing with the API consumer.
- When calling endpoint `retrieve-identifier`, the response will always contain `imei`
- When calling endpoint `retrieve-type`, the response will always contain `tac`
- When calling endpoint `retrieve-ppid`, the response will always contain `ppid`
- When calling endpoint `match-identifier`, the response will always contain `match`
- Responses will also always contain a `lastChecked` field, indicating when the information provided was last confirmed to be correct
- Other response parameters are implementation dependent, and thus optional

An example of a JSON response object is as follows:
```
{
"lastChecked": "2024-02-20T10:41:38.657Z",
"imeisv": "49015420323751800",
"imei": "4901542032375181",
"imeisv": "4901542032375180",
"imei": "490154203237518",
"tac": "49015420",
"model": "3110",
"manufacturer": "Nokia"
Expand Down Expand Up @@ -322,6 +324,52 @@ paths:
"429":
$ref: '#/components/responses/429TooManyRequests'

"/match-identifier":
post:
summary: Check if a provided device identifier matches the one associated with the subscription
description: Check if a provided device identifier matches the one the network currently associates with a given mobile subscription
operationId: matchIdentifier
tags:
- Verify Device Identifiers
security:
- openId:
- device-identifier:match-identifier
parameters:
- $ref: "#/components/parameters/x-correlator"

requestBody:
description: Parameters to identify the mobile subscription and provide the device identifier to match
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MatchRequestBody"
examples:
Match Device By 3-Legged Access Token:
$ref: '#/components/examples/MatchDeviceBy3LeggedToken'
Match Device By Phone Number:
$ref: '#/components/examples/MatchDeviceByPhoneNumber'
Match Device By IP Address:
$ref: '#/components/examples/MatchDeviceByIPAddress'
Match Device By Multiple Identifiers:
$ref: '#/components/examples/MatchDeviceByMultipleIdentifiers'

responses:
"200":
$ref: '#/components/responses/200MatchIdentifier'
"400":
$ref: '#/components/responses/400BadRequest'
"401":
$ref: '#/components/responses/401Unauthorized'
"403":
$ref: '#/components/responses/403Forbidden'
"404":
$ref: '#/components/responses/404NotFound'
"422":
$ref: '#/components/responses/422UnprocessableContent'
"429":
$ref: '#/components/responses/429TooManyRequests'

components:
securitySchemes:
openId:
Expand Down Expand Up @@ -365,8 +413,8 @@ components:
description: Device identifier has been successfully retrieved when the device subscription was identified by a 3-legged access token or single device subscription identifier
value:
lastChecked: "2024-02-20T10:41:38.657Z"
imeisv: "49015420323751800"
imei: "4901542032375181"
imeisv: "4901542032375180"
imei: "490154203237518"
tac: "49015420"
model: "3110"
manufacturer: "Nokia"
Expand All @@ -376,8 +424,8 @@ components:
device:
phoneNumber: "+123456789"
lastChecked: "2024-02-20T10:41:38.657Z"
imeisv: "49015420323751800"
imei: "4901542032375181"
imeisv: "4901542032375180"
imei: "490154203237518"
tac: "49015420"
model: "3110"
manufacturer: "Nokia"
Expand Down Expand Up @@ -442,8 +490,55 @@ components:
lastChecked: "2024-02-20T10:41:38.657Z"
ppid: "b083f65ccdad365d7489fff24b6d5074b30c12b6d81db3404d25964ffd908813"

200MatchIdentifier:
description: |
A match result has been successfully determined for the provided device identifier.
HTTP Status Code Mapping:
- 200 + match=true → The provided identifier MATCHES the network's record
- 200 + match=false → The provided identifier does NOT match (subscription and device are known, confirmed mismatch)
- 404 → Subscription cannot be resolved from device/token
- 422 → Subscription resolved but no deterministic result available (policy/regulation/no device info)
- 5xx → Transient or technical failures (timeouts, upstream errors)
Note: match=false is ONLY returned when a definitive comparison has been performed.
Comment on lines +499 to +502
Copy link
Copy Markdown
Collaborator

@eric-murray eric-murray Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

422 does not necessarily mean that the subscription has been resolved. See my comments below.

My preference would be to only comment on the meaning of a status code in the description of that specific status codes, and not in the descriptions of other status codes. Otherwise, we risk conflicting descriptions.

Suggested change
- 404 → Subscription cannot be resolved from device/token
- 422 → Subscription resolved but no deterministic result available (policy/regulation/no device info)
- 5xx → Transient or technical failures (timeouts, upstream errors)
Note: match=false is ONLY returned when a definitive comparison has been performed.

Copy link
Copy Markdown

@albertoramosmonagas albertoramosmonagas Apr 1, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @eric-murray, I think that's a fair point. I agree that the 200MatchIdentifier description should only describe the meaning of the 200 response itself, and not restate the semantics of 404, 422 or 5xx, otherwise we risk duplication or conflicts with the specific status code definitions.

What I wanted to preserve is just the normative point that:

  • 200 + match = false is only returned when a definitive comparison has been performed and the identifiers do not match.

So I’m happy to simplify the 200 description accordingly, and move the broader status-code mapping either to the /match-identifier operation description and/or rely on the specific 404 / 422 / 5xx definitions plus the test cases to make the behaviour explicit.

200MatchIdentifier:
  description: |
    A match result has been successfully determined for the provided device identifier.
    - `match=true` means the provided identifier matches the network's current record.
    - `match=false` is only returned when a definitive comparison has been performed and the provided identifier does not match the network's current record.

WDYT?

Copy link
Copy Markdown
Collaborator

@Kevsy Kevsy Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

HI @albertoramosmonagas -

I think you can align the two descriptions for simplicity:

200MatchIdentifier:
  description: |
    A match result has been successfully determined for the provided device identifier.
    - `match=true` means the provided identifier matches the network's current record.
    - `match=false` means the provided identifier does not match the network's current record.

headers:
x-correlator:
$ref: "#/components/headers/X-Correlator"
content:
application/json:
schema:
required:
- lastChecked
- match
allOf:
- $ref: "#/components/schemas/CommonResponseBody"
Copy link
Copy Markdown

@albertoramosmonagas albertoramosmonagas Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Copy Markdown

@albertoramosmonagas albertoramosmonagas Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Copy Markdown
Author

@ALIIQBAL786 ALIIQBAL786 Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown

@albertoramosmonagas albertoramosmonagas Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

- $ref: "#/components/schemas/MatchResult"
examples:
Successful Match:
description: Device identifier match has been successfully determined when the device subscription was identified by a 3-legged access token or single device subscription identifier
value:
lastChecked: "2024-02-20T10:41:38.657Z"
match: true
Successful Non-Match:
description: Device identifier does not match when the device subscription was identified by a 3-legged access token or single device subscription identifier
value:
lastChecked: "2024-02-20T10:41:38.657Z"
match: false
Successful Match With Device Disambiguation:
description: Device identifier match has been successfully determined when a 2-legged access token and multiple device subscription identifiers were provided
value:
device:
phoneNumber: "+123456789"
lastChecked: "2024-02-20T10:41:38.657Z"
match: true

400BadRequest:
description: Bad Request
description: |
Invalid request syntax or malformed JSON.
This status is reserved for:
- Malformed JSON in the request body
- Invalid data types
- Invalid format (not matching required patterns)
Business validation errors should return 422 instead.
headers:
x-correlator:
$ref: "#/components/headers/X-Correlator"
Expand Down Expand Up @@ -553,7 +648,9 @@ components:
message: Client does not have sufficient permissions to perform this action.

404NotFound:
description: Not found
description: |
Subscription cannot be resolved from the provided device identifiers or access token.
The network cannot map the request to a known subscription.
headers:
x-correlator:
$ref: "#/components/headers/X-Correlator"
Expand All @@ -571,15 +668,22 @@ components:
enum:
- IDENTIFIER_NOT_FOUND
examples:
Device Cannot Be Found:
DeviceNotFound:
description: The provided identifier cannot be matched to a device known to the API provider
value:
status: 404
code: IDENTIFIER_NOT_FOUND
message: The provided identifier cannot be matched to a device.

422UnprocessableContent:
description: Unprocessable Content
description: |
Subscription found but the service cannot provide a deterministic match result.
Copy link
Copy Markdown
Collaborator

@eric-murray eric-murray Mar 30, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Of the four codes currently defined for the 422 status code, only SERVICE_NOT_APPLICABLE means that the device has been identified but processing cannot proceed. The example given in the introduction is that the phone number belongs to a landline, but it would also apply to other reasons, such as the local policy or regulatory reasons mentioned.

Also note that, if the reason is "temporary", then a 503 Service Unavailable status code should be used to indicate that the required result may be available later. However, we have not really discussed this, and there is a separate discussion in Commonalities on conveying "business outcomes" in a standardised way, so I would not explicitly add a 503 error to the OAS just yet.

For the remaining three code (UNSUPPORTED_IDENTIFIER, UNNECESSARY_IDENTIFIER and MISSING_IDENTIFIER), the device has not been definitively identified, either because the identifier provided is not supported, the identification is (potentially) ambiguous, or no identifier has been provided at all.

So this proposed update needs to be re-written.

Also, if you need to use the term "subscription", then be explicit and say "mobile device subscription". But better not to use the term at all in the error description if you can avoid it.

Copy link
Copy Markdown

@albertoramosmonagas albertoramosmonagas Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @eric-murray agreed, this is too narrow for the full set of 422 causes. You’re right that only SERVICE_NOT_APPLICABLE implies that processing cannot proceed even though the service context is otherwise valid (e.g. local policy/regulatory reasons, line type, etc.). For UNSUPPORTED_IDENTIFIER, UNNECESSARY_IDENTIFIER, and MISSING_IDENTIFIER, we cannot assume that the device / line has been definitively identified.

I also agree that we should avoid saying “subscription found” in the generic 422 description. I’d suggest rewriting it more generically, for example:

422UnprocessableContent:
  description: |
    The request is valid, but it cannot be processed due to business, identification, or applicability conditions.

and then leave the more specific meaning to the individual cause values / examples.

Also agreed on not introducing an explicit 503 in this PR for temporary cases until that is better aligned in Commonalities.

This status is used for business validation errors:
- MISSING_IDENTIFIER: 2-legged token provided without any subscription identifier
- UNNECESSARY_IDENTIFIER: 3-legged token provided with additional device identifier
- Service cannot provide deterministic result due to:
* No usable device information available for the subscription
* Local policy or regulatory restrictions prevent returning match information
headers:
x-correlator:
$ref: "#/components/headers/X-Correlator"
Expand Down Expand Up @@ -683,11 +787,11 @@ components:
imeisv:
type: string
description: IMEISV of the device
example: "49015420323751800"
example: "4901542032375180"
imei:
type: string
description: IMEI of the device
example: "4901542032375181"
example: "490154203237518"

DeviceType:
description: |
Expand Down Expand Up @@ -834,6 +938,47 @@ components:
pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$
example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"

MatchRequestBody:
description: Request body for match-identifier operation, containing an optional mobile device subscription identifier, and the physical device identifier to match against
allOf:
- $ref: "#/components/schemas/RequestBody"
- type: object
required:
- providedIdentifierType
- providedIdentifier
properties:
providedIdentifierType:
$ref: "#/components/schemas/ProvidedIdentifierType"
providedIdentifier:
type: string
minLength: 8
maxLength: 16
description: The device identifier value to match against. Must match the format constraints for the specified identifier type.
example: "490154203237518"
# Pattern will be validated based on providedIdentifierType

ProvidedIdentifierType:
type: string
enum:
Copy link
Copy Markdown
Collaborator

@AxelNennker AxelNennker Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
enum:
enum:
- PPID

Copy link
Copy Markdown
Collaborator

@AxelNennker AxelNennker Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown

@albertoramosmonagas albertoramosmonagas Feb 13, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Collaborator

@AxelNennker AxelNennker Feb 13, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown

@albertoramosmonagas albertoramosmonagas Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Collaborator

@AxelNennker AxelNennker Mar 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That API consumer do not need a "match" feature because they can do the match by using "retrieve" is true for e.g. numberverification as well and there we have the "/verify" endpoint. So, that argument does not have merit in my opinion. Also, some legislations make "match" easy and "retrieve" illegal - at least without consent or opt-out. So, "match" for PPID might be the only legal and simple feature in those markets.

Furthermore, to the argument that some API consumers already have the IMEI and can do the match themselves. Sure, if they can handle the consent and/or opt-out legal requirements in their market that is good for them. But CAMARA have to think globally and there matching PPID might be the solution for some markets and legislations.

Copy link
Copy Markdown

@albertoramosmonagas albertoramosmonagas Mar 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks Axel — I think your latest point is fair in one respect: there may indeed be markets where a match-style operation is legally easier to expose than a retrieve-style operation, including for PPID.

That said, I still think adding PPID into ProvidedIdentifierType is the wrong move for this PR. The reason is not that “PPID match can never be useful”; the reason is that it is a different feature with a different semantic and privacy profile:

  • The current /match-identifier proposal is scoped as a subscription–device binding check using device identifiers (IMEI / IMEISV / TAC).
  • PPID is a persistent pseudonymous binding mechanism. Matching a PPID is no longer a hardware/device-identifier check; it becomes a verification of a long-lived partner-scoped token.

So from my perspective, this is mainly a scope and clarity issue:

  • This PR solves:

    “For this subscription and this device identifier, does the network currently see the same device?”

  • A potential PPID match feature would solve:

    “Is this still the same partner-scoped pseudonymous binding as before?”

Those are related, but not the same contract. I also think it is better for CAMARA design to keep those primitives clearly separated:

  • retrieve-ppid → persistent pseudonymous binding
  • /match-identifier → point-in-time boolean check on device identifiers
  • any future PPID match capability, if the WG sees clear legal/market demand, should be discussed explicitly as a separate enhancement rather than being folded into this enum expansion.

So my suggestion would be:

  • keep ProvidedIdentifierType limited to IMEI | IMEISV | TAC in this PR,
  • and, if there is real interest in PPID matching for certain legislations/markets, open a separate issue for that use case with its own rationale and scope.

That way we keep this PR tight, interoperable and easy to explain, while still leaving the door open for a PPID-specific evolution later if the WG wants it.

Copy link
Copy Markdown
Collaborator

@rartych rartych Mar 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR proposes security scope: device-identifier:match-identifier, so following the logic of current API definition another endpoint /match-ppid with device-identifier:match-ppid scope can be considered if needed.

Copy link
Copy Markdown
Collaborator

@AxelNennker AxelNennker Mar 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That way we keep this PR tight, interoperable and easy to explain, while still leaving the door open for a PPID-specific evolution later if the WG wants it.

I think this PR is easier to explain if this PR handles all identifiers the same and not exclude one.

Copy link
Copy Markdown

@albertoramosmonagas albertoramosmonagas Apr 1, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @AxelNennker, I understand the appeal of having a single match operation that handles every identifier in the same way. That said, from my perspective that would actually make this PR harder to explain, not easier, because the identifiers are not semantically equivalent:

  • IMEI / IMEISV / TAC are device identifiers
  • PPID is a persistent partner-scoped pseudonymous token

So adding PPID here would not be a small enum extension; it would materially change the contract of this endpoint. At this stage, the PR has already been reviewed and refined around a narrower and clearer scope:

  • /match-identifier = point-in-time boolean check of a device identifier against the device currently seen for the subscription
  • retrieve-ppid = persistent pseudonymous binding retrieval
  • a future match-ppid capability, if the WG sees value in it, can be discussed separately

From Telefónica’s side, this is the scope we support for the current PR. If PPID were added into ProvidedIdentifierType, we would see that as a different feature that should be handled through a separate issue / endpoint discussion rather than through this PR.

So my suggestion would be to close this thread on the basis of the current scoped proposal, and, if there is still interest in PPID matching, open a separate issue for that specific capability.

- IMEI
- IMEISV
- TAC
description: |
Type of the provided device identifier. Format requirements:
- IMEI: 15 digits (pattern: ^[0-9]{15}$)
- IMEISV: 16 digits (pattern: ^[0-9]{16}$)
- TAC: 8 digits (pattern: ^[0-9]{8}$)

MatchResult:
description: |
The result of matching the provided device identifier against the network's identifier for the subscription
type: object
properties:
match:
type: boolean
description: True if the provided device identifier matches the one the network currently associates with the subscription
example: true

examples:
IdentifyDeviceBy3LeggedToken:
description: Empty JSON when device is identified by access token
Expand Down Expand Up @@ -863,3 +1008,38 @@ components:
publicAddress: "84.125.93.10"
publicPort: 59765
networkAccessIdentifier: "123456789@example.com"

MatchDeviceBy3LeggedToken:
description: Match identifier when device is identified by access token
value:
providedIdentifierType: "IMEI"
providedIdentifier: "4901542032375181"

MatchDeviceByPhoneNumber:
Copy link
Copy Markdown
Collaborator

@AxelNennker AxelNennker Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

description: Matching device identifier by phone number and provided IMEI
value:
device:
phoneNumber: "+123456789"
Copy link
Copy Markdown

@albertoramosmonagas albertoramosmonagas Feb 13, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Copy Markdown
Collaborator

@eric-murray eric-murray Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is an example request, and is only applicable if a 2-legged access token is being used (otherwise a 422 UNNECESSARY_IDENTIFIER would be returned).

So the example is valid for 2-legged access tokens, though I agree that might not be clear to all readers.

Copy link
Copy Markdown

@albertoramosmonagas albertoramosmonagas Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My question was mainly about readability for the spec reader: the example itself is valid for a 2-legged access token, but that may not be obvious at first glance, especially since other examples in the same section cover different identification patterns. Would it make sense to make that explicit in the example description, e.g. something like:

“Matching device identifier by phone number and provided IMEI (2-legged token example)”

That way we keep the example as-is, but make the intended usage clearer to readers.

providedIdentifierType: "IMEI"
providedIdentifier: "490154203237518"

MatchDeviceByIPAddress:
description: Matching device identifier by IP address and provided TAC
value:
device:
ipv4Address:
publicAddress: "84.125.93.10"
publicPort: 59765
providedIdentifierType: "TAC"
providedIdentifier: "49015420"

MatchDeviceByMultipleIdentifiers:
description: Matching device identifier by multiple subscription identifiers and provided IMEISV
value:
device:
phoneNumber: "+123456789"
ipv4Address:
publicAddress: "84.125.93.10"
publicPort: 59765
providedIdentifierType: "IMEISV"
providedIdentifier: "4901542032375180"
Loading