Device Identifier API

• Summary
• Introduction
• Relevant terms and definitions
• API functionality
• Further info and support
• Get Device Identifiers
  • postGet details about the specific device being used by a given mobile subscriber
  • postGet details about the type of device being used by a given mobile subscriber

API docs by Redocly

CAMARA Mobile Device Identifier API (0.1.0)

Download OpenAPI specification:Download

E-mail: contact@spryfoxnetworks.com License: Apache 2.0

Product documentation at CAMARA

Summary

The Mobile Device Identifier API returns details of the mobile device (also know as the UE, or User Equipment) currently being used by a specified mobile subscriber. The following information can be returned:

• A unique network identifier for the specific device itself (IMEI SV and IMEI)
• A network identifier for the device make and model (IMEI Type Allocation Code)
• Device manufacturer name and model

This information can be useful in a number of scenarios, such as the following:

• For insurance purposes, to automatically identify a device that a customer wishes to insure
• For security / fraud reasons, to establish that a customer is not using a device they claim to have broken or lost
• For service delivery reasons, to optimise content for a particular device or OS type

Introduction

Mobile devices are allocated a unique identity by the manufacturer, known as the International Mobile Equipment Identity, or IMEI. The current software version (SV) of the device can be appended to this, in which case the identifier is known as the IMEI SV. This identity is signalled to the mobile network when the device connects, both to confirm that the device is not blocked, and also allow device dependent network configurations to be implemented.

The IMEI is a 15 digit integer, and the IMEI SV is a 16 digit integer:

• The first 8 digits are known as the Type Allocation Code (TAC), and identify the manufacturer and model of the device
• The following 6 digits are the serial number of the device for that TAC
• For IMEI, the remaining digit is a check digit
• For IMEI SV, the remaining two digits are the software version

TACs are issued and managed by the GSMA, and can be queried using the GSMA IMEI database.

The mobile network associates this device identifier with the mobile subscription currently using the device. The mobile subscription is defined by the Subscriber Identity Module (SIM) currently active in the mobile device. This may be a removable SIM or an eSIM. In either case, it is possible for the association between the device identifier and subscription to change - for example, when a physical SIM is transferred to another mobile device.

The Device Identifier API allows the API consumer to obtain the IMEI and associated parameters for a specified mobile subscription identifier or equivalent. The mobile subscription can be identified using one of the following subscription identifiers:

• the subscription phone number (also known as MSISDN)
• the subscription network access identifier, which is a domain specific identifier typically allocated to devices that do not require voice / SMS connectivity
• the current IP address and port alloacted to the device, which must be an IPv6 or public IPv4 address

The API can be called by an application server or other 3rd party server to establish the identity of the device currently being used by the mobile subscription. The information returned will depend upon the consent that the end user (i.e. mobile subscription owner) has given for that information to be provided to the API consumer. For example, if the end user has not consented to any information about their device being given, then the API consumer will receive an error in reponse to their request. Otherwise, the information that the end user has consented to being given will be returned.

Relevant terms and definitions

Device Identifier API service endpoint

The URL pointing to the RESTful resource of the Device Identifier API.

Identifier for the mobile subscription

At least one identifier for the mobile subscription from the following four options:

• Phone number (i.e. MSISDN)
• Network Access Identifier assigned by the mobile network operator for the device
• IPv6 address
• IPv4 address

In scenarios where a primary MSISDN is shared between multiple devices, each of which has its own "secondary" MSISDN (e.g. OneNumber), the MSISDN passed by the API consumer will be treated as the secondary MSISDN, and hence the identifier returned will be that of the relevant associated device (such as a smartwatch). In such scenarios, the "primary" device (e.g. smartphone) is usually allocated the same primary and secondary MSISDN, and hence providing the primary MSISDN will always return the identity of the primary device and not any associated devices.

Authorization and authentication

CAMARA guidelines defines a set of authorization flows which can grant API clients access to the API functionality, as outlined in the document CAMARA-API-access-and-user-consent.md. Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.

It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control.

API functionality

The API defines two 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

To call either of these endpoints, the API consumer must first obtain a valid OAuth2 token from the token endpoint, which is then passed as an Authorization header. The API consumer must also pass at least one of the available mobile subscription identifiers in the body of the request.

Not all possible mobile subscription identifiers may be valid for a given network or implementation, and hence the API consumer should provide as many identifiers as are known to them. If the API consumer provides identifiers for different mobile subscriptions, the API may return an error, or it may take each identifier provided in the order specified above until it finds a valid subscription identifier.

If the authentication token is not valid, a 401 UNAUTHENTICATED error is returned

If the mobile subscription parameters contain a formatting error, a 400 INVALID_ARGUMENT error is returned.

If the mobile subscription cannot be identified from the provided parameters, a 404 NOT_FOUND error is returned.

If the end user has not consented to the API consumer getting access to the device identifier information, then a 403 PERMISSION_DENIED error is returned.

Otherwise, a JSON object is returned containing the data the 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
• 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

An example of a JSON response object is as follows:

{
   "lastChecked": "2024-02-20T10:41:38.657Z",
   "imeisv": "49015420323751800",
   "imei": "4901542032375181",
   "tac": "49015420",
   "model": "3110",
   "manufacturer": "Nokia"
}

Further info and support

(FAQs will be added in a later version of the documentation)

Get Device Identifiers

Get details about the specific device being used by a given mobile subscriber

Get details about the specific device being used by a given mobile subscriber

Authorizations:

openId

header Parameters

X-Correlator

string <uuid>

Request Body schema: application/json

Parameters to create a new session

non-empty

phoneNumber	string (PhoneNumber) ^\+?[0-9]{5,15}$ A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, optionally prefixed with '+'.
networkAccessIdentifier	string (NetworkAccessIdentifier) A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator.
	object or object (DeviceIpv4Addr) The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers). If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress. If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object) In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone.
ipv6Address	string <ipv6> (DeviceIpv6Address) The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix).

Responses

https://labs-api.spryfoxnetworks.com/qpcloud-monet-swagger/device-identifier/v0.1.0/retrieve-identifier

Request samples

• Payload

Content type

application/json

{

• "phoneNumber": "123456789",
• "networkAccessIdentifier": "123456789@domain.com",
• "ipv4Address": {

  • "publicAddress": "84.125.93.10",
  • "publicPort": 59765

  },
• "ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"

}

Response samples

• 200
• 400
• 401
• 403
• 404
• 405
• 406
• 429
• 500
• 502
• 503
• 504

Content type

application/json

{

• "lastChecked": "2024-02-20T10:41:38.657Z",
• "imeisv": "49015420323751800",
• "imei": "4901542032375181",
• "tac": "49015420",
• "model": "3110",
• "manufacturer": "Nokia"

}

Get details about the type of device being used by a given mobile subscriber

Get details about the type of device being used by a given mobile subscriber

Authorizations:

openId

header Parameters

X-Correlator

string <uuid>

Request Body schema: application/json

Parameters to create a new session

non-empty

phoneNumber	string (PhoneNumber) ^\+?[0-9]{5,15}$ A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, optionally prefixed with '+'.
networkAccessIdentifier	string (NetworkAccessIdentifier) A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator.
	object or object (DeviceIpv4Addr) The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers). If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress. If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object) In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone.
ipv6Address	string <ipv6> (DeviceIpv6Address) The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix).

Responses

https://labs-api.spryfoxnetworks.com/qpcloud-monet-swagger/device-identifier/v0.1.0/retrieve-type

Request samples

• Payload

Content type

application/json

{

• "phoneNumber": "123456789",
• "networkAccessIdentifier": "123456789@domain.com",
• "ipv4Address": {

  • "publicAddress": "84.125.93.10",
  • "publicPort": 59765

  },
• "ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"

}

Response samples

• 200
• 400
• 401
• 403
• 404
• 405
• 406
• 429
• 500
• 502
• 503
• 504

Content type

application/json

{

• "lastChecked": "2024-02-20T10:41:38.657Z",
• "tac": "49015420",
• "model": "3110",
• "manufacturer": "Nokia"

}