From 530dbe74e4ab16bb436895dc7152d271abdaa6c5 Mon Sep 17 00:00:00 2001 From: Ali Iqbal Date: Thu, 12 Feb 2026 15:09:10 +0500 Subject: [PATCH 1/8] Add match-identifier endpoint --- code/API_definitions/device-identifier.yaml | 152 +++++++++++++++++++- 1 file changed, 151 insertions(+), 1 deletion(-) diff --git a/code/API_definitions/device-identifier.yaml b/code/API_definitions/device-identifier.yaml index e150022..c8b1de9 100644 --- a/code/API_definitions/device-identifier.yaml +++ b/code/API_definitions/device-identifier.yaml @@ -59,11 +59,12 @@ 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. @@ -71,6 +72,7 @@ info: - 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 @@ -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: + - Get 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: @@ -442,6 +490,39 @@ components: lastChecked: "2024-02-20T10:41:38.657Z" ppid: "b083f65ccdad365d7489fff24b6d5074b30c12b6d81db3404d25964ffd908813" + 200MatchIdentifier: + description: A match result has been determined for the provided device identifier + headers: + x-correlator: + $ref: "#/components/headers/X-Correlator" + content: + application/json: + schema: + required: + - lastChecked + - match + allOf: + - $ref: "#/components/schemas/CommonResponseBody" + - $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 headers: @@ -834,6 +915,40 @@ 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 device subscription identifier and the device identifier to match against + allOf: + - $ref: "#/components/schemas/RequestBody" + - type: object + required: + - providedIdentifierType + - providedIdentifier + properties: + providedIdentifierType: + $ref: "#/components/schemas/ProvidedIdentifierType" + providedIdentifier: + type: string + description: The device identifier value to match against + example: "4901542032375181" + + ProvidedIdentifierType: + type: string + enum: + - IMEI + - IMEISV + - TAC + description: Type of the provided device identifier + + 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 @@ -863,3 +978,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: + description: Matching device identifier by phone number and provided IMEI + value: + device: + phoneNumber: "+123456789" + providedIdentifierType: "IMEI" + providedIdentifier: "4901542032375181" + + 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: "49015420323751800" From dcf91a1d63dffe704935f9723c1f7a1656020c14 Mon Sep 17 00:00:00 2001 From: Ali Iqbal Date: Mon, 16 Feb 2026 14:47:35 +0500 Subject: [PATCH 2/8] Update code/API_definitions/device-identifier.yaml Co-authored-by: Alberto Ramos Monagas --- code/API_definitions/device-identifier.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/device-identifier.yaml b/code/API_definitions/device-identifier.yaml index c8b1de9..a50790d 100644 --- a/code/API_definitions/device-identifier.yaml +++ b/code/API_definitions/device-identifier.yaml @@ -991,7 +991,7 @@ components: device: phoneNumber: "+123456789" providedIdentifierType: "IMEI" - providedIdentifier: "4901542032375181" + providedIdentifier: "490154203237518" MatchDeviceByIPAddress: description: Matching device identifier by IP address and provided TAC From 52a142c90715a173874ad98d3eae941aef75306e Mon Sep 17 00:00:00 2001 From: Ali Iqbal Date: Mon, 16 Feb 2026 14:47:46 +0500 Subject: [PATCH 3/8] Update code/API_definitions/device-identifier.yaml Co-authored-by: Alberto Ramos Monagas --- code/API_definitions/device-identifier.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/device-identifier.yaml b/code/API_definitions/device-identifier.yaml index a50790d..ba11884 100644 --- a/code/API_definitions/device-identifier.yaml +++ b/code/API_definitions/device-identifier.yaml @@ -330,7 +330,7 @@ paths: description: Check if a provided device identifier matches the one the network currently associates with a given mobile subscription operationId: matchIdentifier tags: - - Get Device Identifiers + - Verify Device Identifiers security: - openId: - device-identifier:match-identifier From 2b8269911fc475fc92c9d8c9e2ee55c7a3a18a67 Mon Sep 17 00:00:00 2001 From: Ali Iqbal Date: Mon, 16 Feb 2026 15:59:19 +0500 Subject: [PATCH 4/8] fix: correct IMEI (15 digits) and IMEISV (16 digits) example values --- code/API_definitions/device-identifier.yaml | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/code/API_definitions/device-identifier.yaml b/code/API_definitions/device-identifier.yaml index ba11884..d37bcb3 100644 --- a/code/API_definitions/device-identifier.yaml +++ b/code/API_definitions/device-identifier.yaml @@ -80,8 +80,8 @@ info: ``` { "lastChecked": "2024-02-20T10:41:38.657Z", - "imeisv": "49015420323751800", - "imei": "4901542032375181", + "imeisv": "4901542032375180", + "imei": "490154203237518", "tac": "49015420", "model": "3110", "manufacturer": "Nokia" @@ -413,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" @@ -424,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" @@ -764,11 +764,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: | @@ -929,7 +929,7 @@ components: providedIdentifier: type: string description: The device identifier value to match against - example: "4901542032375181" + example: "490154203237518" ProvidedIdentifierType: type: string From 1db3078d7e0a0c979c61f774ab5521e4e42742da Mon Sep 17 00:00:00 2001 From: Ali Iqbal Date: Tue, 17 Feb 2026 11:57:03 +0500 Subject: [PATCH 5/8] Updated the descriptions of status codes --- code/API_definitions/device-identifier.yaml | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/code/API_definitions/device-identifier.yaml b/code/API_definitions/device-identifier.yaml index d37bcb3..fd7c527 100644 --- a/code/API_definitions/device-identifier.yaml +++ b/code/API_definitions/device-identifier.yaml @@ -491,7 +491,13 @@ components: ppid: "b083f65ccdad365d7489fff24b6d5074b30c12b6d81db3404d25964ffd908813" 200MatchIdentifier: - description: A match result has been determined for the provided device identifier + description: | + A match result has been determined for the provided device identifier. + + The meaning of match=false depends on the HTTP status code: + - 200 + match=true → Device identifier matches the network's record + - 200 + match=false → Device identifier does NOT match (subscription and device known, confirmed mismatch) + - 5xx → Technical issue; match determination inconclusive headers: x-correlator: $ref: "#/components/headers/X-Correlator" @@ -634,7 +640,7 @@ components: message: Client does not have sufficient permissions to perform this action. 404NotFound: - description: Not found + description: Subscription not found in network headers: x-correlator: $ref: "#/components/headers/X-Correlator" @@ -660,7 +666,7 @@ components: message: The provided identifier cannot be matched to a device. 422UnprocessableContent: - description: Unprocessable Content + description: Subscription found but service not applicable (policy/segment restrictions) headers: x-correlator: $ref: "#/components/headers/X-Correlator" @@ -1013,3 +1019,4 @@ components: publicPort: 59765 providedIdentifierType: "IMEISV" providedIdentifier: "49015420323751800" + From 1e765635f5cb70866afdff593c484011d2fa1422 Mon Sep 17 00:00:00 2001 From: Ali Iqbal Date: Tue, 17 Feb 2026 12:06:41 +0500 Subject: [PATCH 6/8] Fixed linting issues --- code/API_definitions/device-identifier.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/code/API_definitions/device-identifier.yaml b/code/API_definitions/device-identifier.yaml index fd7c527..89d3359 100644 --- a/code/API_definitions/device-identifier.yaml +++ b/code/API_definitions/device-identifier.yaml @@ -493,7 +493,6 @@ components: 200MatchIdentifier: description: | A match result has been determined for the provided device identifier. - The meaning of match=false depends on the HTTP status code: - 200 + match=true → Device identifier matches the network's record - 200 + match=false → Device identifier does NOT match (subscription and device known, confirmed mismatch) @@ -1019,4 +1018,3 @@ components: publicPort: 59765 providedIdentifierType: "IMEISV" providedIdentifier: "49015420323751800" - From ef50085e24015927ac8912885ffc585a3224c1cb Mon Sep 17 00:00:00 2001 From: Ali Iqbal Date: Tue, 17 Feb 2026 16:17:33 +0500 Subject: [PATCH 7/8] Added regex patterns --- code/API_definitions/device-identifier.yaml | 46 ++++++++++++++++----- 1 file changed, 35 insertions(+), 11 deletions(-) diff --git a/code/API_definitions/device-identifier.yaml b/code/API_definitions/device-identifier.yaml index 89d3359..34454f6 100644 --- a/code/API_definitions/device-identifier.yaml +++ b/code/API_definitions/device-identifier.yaml @@ -492,11 +492,14 @@ components: 200MatchIdentifier: description: | - A match result has been determined for the provided device identifier. - The meaning of match=false depends on the HTTP status code: - - 200 + match=true → Device identifier matches the network's record - - 200 + match=false → Device identifier does NOT match (subscription and device known, confirmed mismatch) - - 5xx → Technical issue; match determination inconclusive + 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. headers: x-correlator: $ref: "#/components/headers/X-Correlator" @@ -529,7 +532,13 @@ components: 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" @@ -639,7 +648,9 @@ components: message: Client does not have sufficient permissions to perform this action. 404NotFound: - description: Subscription not found in network + 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" @@ -657,7 +668,7 @@ 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 @@ -665,7 +676,14 @@ components: message: The provided identifier cannot be matched to a device. 422UnprocessableContent: - description: Subscription found but service not applicable (policy/segment restrictions) + description: | + Subscription found but the service cannot provide a deterministic match result. + 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" @@ -933,8 +951,9 @@ components: $ref: "#/components/schemas/ProvidedIdentifierType" providedIdentifier: type: string - description: The device identifier value to match against + 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 @@ -942,7 +961,11 @@ components: - IMEI - IMEISV - TAC - description: Type of the provided device identifier + 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: | @@ -1018,3 +1041,4 @@ components: publicPort: 59765 providedIdentifierType: "IMEISV" providedIdentifier: "49015420323751800" + From c58212d507ef8bc41edbff90808834bb6d83517e Mon Sep 17 00:00:00 2001 From: Ali Iqbal Date: Tue, 17 Feb 2026 16:19:36 +0500 Subject: [PATCH 8/8] Fixed linting issues --- code/API_definitions/device-identifier.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/code/API_definitions/device-identifier.yaml b/code/API_definitions/device-identifier.yaml index 34454f6..eb5e84d 100644 --- a/code/API_definitions/device-identifier.yaml +++ b/code/API_definitions/device-identifier.yaml @@ -1041,4 +1041,3 @@ components: publicPort: 59765 providedIdentifierType: "IMEISV" providedIdentifier: "49015420323751800" -