This API allows to check the last time that the phone (device) - phone number association has changed

Introduction

The Device Swap API performs real-time checks on the last Device Swap event, providing real-time information about whether the SIM card associated with a user's phone number has been transferred to a different physical device.

Device Swap information can be invaluable for enhancing security, fraud detection, and ensuring compliance with regulatory requirements in various applications, apart from providing useful information of device upgrade trends in user segments.

This API is used by an application to get information about a mobile line's latest Device Swap date. It can be easily integrated and used through this secured API and allows SPs (Service Providers) to get this information in an easy and secured way. The API provides management of 2 endpoints answering 2 distinct questions:

• When did the last Device Swap occur?
• Has a Device Swap occurred during the last n hours?

Relevant terms and definitions

Device Swap: A Device Swap is a process in which the association between a user's mobile phone number (MSISDN) and a device (IMEI) is created for the first time or changes for any reasons.

API Functionality

The Device Swap API provides a programmable interface for developers and other users (capabilities consumers) to request the last date of a device swap performed on the mobile line, or, to check whether a device swap has been performed during a past period.

The API provides 2 operations:

• POST retrieve-date: Provides timestamp of latest device swap for a given phone number. If no device swap has been performed, the API will return the first phone number usage in the device (the timestamp of the first time that the phone number was connected to the network, it is, the first time that the SIM is installed in the device) by default. It will return an empty string in case is not possible to retrieve the date (e.g. in case local regulations are preventing the safekeeping of the information for longer than the stated period, or in some edge error cases). In case no data is available in the operators records (e.g. no recorded event), API will return a 422 error.
• POST check: Checks if device swap has been performed during a past period (defined in the request with 'maxAge' attribute) for a given phone number, the API will return boolean response (true/false), indicating that the device has been swapped or not in the specified period. In case the phone number has never been installed in a device, or no data is available in the operators records (e.g. database error), API will return a 422 error.

So, when consuming this operation, the following scenarios will exist:

The API is consumed in 3-legged:

• If no phoneNumber is provided in the body, the API will return in the response the information of the phoneNumber that is associated to the access token.
• If the phoneNumber is provided in the body, the API will return in the response the information of that phone number if it matches the one associated to the access token.
• If the phoneNumber provided in the body does not match the one associated to the access token, the API will respond with HTTP 403 INVALID_TOKEN_CONTEXT.

The API is consumed in 2-legged:

• If no phoneNumber is provided in the body, the API will respond with HTTP 400 INVALID_ARGUMENT.
• If the phoneNumber is provided in the body, the API will return in the response the information of the phoneNumber provided in the body.

Resources and Operations overview

The API provides the following endpoints:

• An operation to retrieve last date in which the device of the end-user was swapped.
• An operation to check if the SIM of the end-user has been installed in a different device during a past period

Authorization and authentication

The "Camara Security and Interoperability Profile" provides details on how a client requests an access token. Please refer to Identify and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the Profile.

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.