GSMA Open Gateway API Descriptions

Unlocking Connectivity: Comprehensive descriptions of GSMA Open Gateway APIs

The GSMA Open Gateway initiative launched with eight network APIs in 2023. Open Gateway portfolio of APIs has since continued to expand. All APIs can be found in the CAMARA repository here: https://github.com/camaraproject

Anti Fraud

API Product Family: Subscriber Identity 

Device Status

API Description

The API checks connectivity status for a user equipment. The API includes functionality to confirm whether the device is roaming and the country it is in, and also information on the connection status of the device, to confirm whether the device is reachable by data or SMS. Additionally, the API can be used in subscription mode, where the consumer will receive notifications if the status of the device changes.

https://github.com/camaraproject/DeviceStatus/blob/main/code/API_definitions/device-status.yaml

Use cases

  • Service delivery: a content provider may need to enforce territory restrictions for their content. For instance a broadcaster, streaming or gaming service may only have rights to broadcast a piece of content in their domestic market, or may want to deliver different services according to the country. Through the Device status API, the content provider can check that the end-user is located in the content provider domestic market.
  • Fraud prevention (e.g. banking, payments, commerce): a bank may query the API upon detecting a transaction from an unexpected country. The roaming information feeds into the bank risk decision engine and security measures are applied accordingly by the bank.
  • Regulatory compliance: a customer may need to be within a certain jurisdiction, or outwith others, in order for transactions to be authorized.
  • Tourism and hospitality: an international hotel franchise or a travel agency may want to personalize their service according to the country or to their customers displacements.
  • Remote control of machines and vehicles (e.g. Automated Guided Vehicles, drones, robotic arms, factory production lines): applications requiring remote control of machines or vehicles my require to be notified about their connectivity status to ensure their service and/or that they are properly manageable from the corresponding control point.

Benefits

  • Remote monitoring of IoT devices enables device management and performance.
  • Decreased fraud risk without additional friction for the user.
  • Personalization of services.
  • Control of the delivery of digital and physical services.

KYC Fill-in

API Description

This API provides the customer (API invoker such as 3rd party Service Provider) with the ability to request and receive the information for a particular user, which on file (and verified) by the user’s Mobile Network Operator in their own KYC records. The information can include phone number, name, postal code, address, birthdate, email address etc.

https://github.com/camaraproject/KnowYourCustomer/blob/main/code/API_definitions/kyc-fill-in.yaml

Use cases

  • One-click checkout (e-commerce), automatic form-fill for user’s information e.g. mobile phone number, birthdate, address, on registration (varied verticals)
  • Confirm recipient’s mobile number for sending e-goods and e-presents like SMS gift code
  • Check user’s age with birthdate information for e.g. alcohol and tobacco sale

Benefits

  • The Service Provider can optimise the user experience while capturing the accurate user information its service requires.
  • Simplified user experience increasing conversion for service providers at user registration
  • More accurate registration form information through avoiding data entry errors

KYC Match

API Description

This API provides the customer (API invoker such as 3rd party Service Provider) with the ability to compare the information the customer has for a particular user with that on file (and verified) by the user’s Mobile Network Operator in their own KYC records. The information can include phone number, name, postal code, address, birthdate, email address etc. No Personal Identifiable Information (PII) is returned.

https://github.com/camaraproject/KnowYourCustomer/blob/main/code/API_definitions/kyc-match.yaml

Use cases

  • User identity verification for any service provider checking new users and regular refresh.
  • Especially depending on Market/Country regulations, identity verification for compliance with regulations, e.g. KYC regulations in banking demanding check for new users and for regular refresh.

Benefits

  • The Service Provider can confirm the accuracy of the user information required by its service without inconveniencing the user. Mitigate risks related to different ways of identity fraud like the usage of synthetic identities.
  • Maximize the conversion rate and the quality of the onboarding procedures.
  • Avoids data entry errors and mitigates fraud by utilizing verified user information from the user’s Mobile Network Operator

Number verification

API Description

The API enables the seamless authentication of the mobile device by the mobile network. The developer requests a check of the phone number of the device being used to access its service. The API either confirms the comparison result (i.e. whether the user is using a device with the same mobile phone number as is declared), or returns the phone number.

https://github.com/camaraproject/NumberVerification/blob/main/code/API_definitions/number_verification.yaml

Use cases

  • App onboarding (banking app, social media, ride share, mobile wallet, …): SMS One Time Password is widely used to prove that the user is in possession of the mobile device associated with the mobile number used for registration. However it adds friction to the user journey. The application can instead request a seamless authentication of the mobile device via the API.
  • App login: in place of username/password, the application can request seamless authentication of the mobile device.
  • Application password reset: the user journey often relies on SMS One Time Password. As in the app onboarding use case, the application can instead request a seamless authentication of the mobile device via the API.

Benefits

  • Improved seamless and faster user experience, hence improved conversion rates & customer satisfaction
  • Lower risk of compromise (by social engineering or interception)

One Time Password (SMS)

API Description

The API delivers a short-lived one time password to a mobile phone number via SMS. The API then validates the code as input by the end-user into the service, in order to provide a proof of possession of the phone number.

https://github.com/camaraproject/OTPvalidationAPI/blob/main/code/API_definitions/one-time-password-sms.yaml

Use cases

  • Onboarding to digital service (banking, social media, gig economy, retail, …): SMS One Time Password (OTP) is used to prove that the user is in possession of the mobile device associated with the mobile number used for onboarding. This increases confidence for future uses of the mobile number and reduces instances of fake accounts creation.
  • High-value transactions: in order to reduce payment fraud, the user may be asked to enter the OTP code sent to their registered mobile number.
  • Account management e.g. password reset: to protect against account takeover, sensitive account management actions can be protected by requesting a second factor authentication by the end-user.

Benefits

  • End user familiarity.
  • Increased security over single-factor authentication (username/password) or in card-not-present scenarios.
  • Prevent fake accounts creation (bots).

Sim Swap

API Description

The API checks the last time that the SIM card associated with a mobile number (MSISDN) has changed. The response may be a timestamp or a yes/no for a defined period (e.g. last 24h). Additionally, the API can be used in subscription mode, where the consumer will receive notifications if the status of the SIM Swap changes.

Sim Swap: https://github.com/camaraproject/SimSwap/blob/main/code/API_definitions/sim_swap.yaml  
Sim Swap Subscription Notification: https://github.com/camaraproject/SimSwap/blob/main/code/API_definitions/sim-swap-notification-subscription.yaml  

Use cases

  • Fraud prevention in banking: a bank may query the API when a transaction appears suspicious. The SIM swap information feeds into the bank risk decision engine and security measures are applied accordingly by the bank. Also, strange behaviors or accumulation of SIM Swap notifications may help banks detect fraud scenarios in advance.
  • Fraud prevention for password reset (various sectors: e-commerce, social networks, etc.): password reset is often protected via a mobile verification e.g. SMS One Time Password. The online service provider may query the API to secure the mobile verification. A recent SIM swap may indicate a risk of account takeover fraud and the service provider can adapt the security measures accordingly.

Benefits

  • Increased security without additional friction for the user
  • Prevention of account takeover is a benefit for both the business and the end customer, since end customers are protected from being involved in uncomfortable situations.

Mobile Connectivity / VAS

API Product Family: Location

Device Location Verification

API Description

The API allows an application to check if a mobile device is in proximity of a given location. The API request contains the location to be checked and an accuracy range in km (between 2km and 200km). The API response indicates whether the location is within the accuracy range of the last known location of the MSISDN.

In its simplest version, the API can be used to verify a location expressed as latitude, longitude, and a radius. With the most recent version, the API can be used also to verify a location expressed as a postal code (ZIP code) or other well-known administrative code (district, arrondissement, town, region, etc.)

https://github.com/camaraproject/DeviceLocation/blob/main/code/API_definitions/location-verification.yaml

Use cases

  • Fraud prevention (banking, payments): a bank may query the API upon detecting a cash withdrawal or credit card use attempt from an unexpected location. The location verification feeds into the bank risk decision engine and security measures are applied accordingly by the bank.
  • Traffic management of drones: the Uncrewed Aircraft System Traffic Management or the drone operator can obtain drone location information from its GPS data, however this is vulnerable to jamming or spoofing. They can query the API to verify the drone location, e.g. for law enforcement purposes or to check compliance with approved flight plan.
  • Retail marketing: a retailer Edge Application may query the API to verify that a user is close enough to a physical location before pushing a notification to them. Using the postal code or admin code feature, they can verify their zones of influence and their characteristics using data related to those administrative divisions.
  • Protection of assets e.g. logistics, indoors factory tools (depending on available accuracy): the fleet manager can check if assets are in their expected location.
  • Special digital services in big events: the organizers of a big sports or entertaining event (football match, music festival, etc.) can provide their audience with special digital services in the place of the event: access to private web zone of the event, eligibility for special fan experiences, access to premium content during and after the event, etc.
  • Controlled delivery of services: content-based business (streaming, cloud gaming) and location-based business (delivery of food or other goods, etc.) can keep under control how and where their services are being delivered: eligibility to enjoy a content/game/service, control the transport by which the goods are being delivered, etc.

Benefits

  • Decreased fraud risk without additional friction for the user.
  • Independent and reliable verification of the location reported by a drone GPS.
  • Geotargeted marketing.
  • Personalization of services.
  • Control of the delivery of digital and physical services.

Geofencing

API Description

The API enables the subscription to geographical position changes. With this API, customers can create subscriptions for their devices to receive notifications when a device enters or exits a specified area. If the geofencing-state (getting in or out) of a device changes, the event subscriber will be notified back.

https://github.com/camaraproject/DeviceLocation/blob/main/code/API_definitions/geofencing.yaml

Use cases

  • Retail and e-commerce personalization and advertising: a retailer wants to launch personalization or advertising campaigns to its customers when they enter the area of influence of its department stores.
  • Tourism and other location-based services: travel agencies, airlines, hotel companies, etc. want to give personalized experiences when their customers enter specific areas where they can provide added value. E.g., an airline welcoming a traveller to the airport and reminding them the possibility of using the VIP room, a Public Administration giving tourism information to registered tourists.
  • Assets safekeeping and tracking: ensuring that assets (parcels, fleet, services of shared vehicles, IoT, etc.) enter the right areas in the right moments, or they do not leave the areas where they must be.

Benefits

  • New use cases are enabled based on network location information and the events and mobility of the devices. The subscription mechanism enabling geofencing allows developers to enhance their product with a push mode model, improving the resource’s usage and increasing the value of the information.

Location retrieval

API Description

This API provides the ability to retrieve a device location. The retrieved area depends on the network conditions at the subscriber’s location.

https://github.com/camaraproject/DeviceLocation/blob/main/code/API_definitions/location-retrieval.yaml

Use cases

Location Retrieval could be useful in scenarios such as: 

  • For use cases between mobile users when it is required to check proximity, we first need to retrieve mobile location of one of the mobile (with this Location Retrieval API)  and then check tge other mobile location (via Location Retrieval api). This is applicable for people-to-people payment for example. 
  • In logistic use cases, this API is used to retrieve container location by exception (when shipment is not at the expected place). This is particularly useful for tracking IoT device. 
  • Globally, it is worth noting that the Location Retrieval API is often requested as a complement to GPS tracking for sensitive based-location use cases as GPS could be spoofed on a phone. 

Benefits

  • Provide location service based on mobile network as complementary option of the GPS 

API Product Family: Network Quality / Optimisation 

Connectivity Insights

API Description

The API enables App Developers to define intents in the form of policy thresholds for QoS metrics against the device and the application service. The API service will alert the consumers if and when the thresholds set in the policy are breached. This API would be useful for applications that optimize user experience based on the user’s network experience.

https://github.com/camaraproject/ConnectivityInsights/blob/main/code/API_definitions/CAMARA%20Connectivity%20Insights%20API.yaml

Use cases

  • AR/VR based apps: AR/VR based applications, which have specific requirements of uplink throughput, downlink throughput, latency, etc., can define a network monitoring policy based on the application’s needs. This API supports receiving notifications when the network is not able to meet the application requirements, enabling the app to take intelligent corrective steps, such as calling the QoD API or adapting specific attributes within the application based on the current network conditions.
  • CV2X apps: CV2X apps, which could have very strict SLA requirements, can define the max tolerable latency in the application intents and receive notifications if the latency crossed the threshold. Having this insight enables the application in better decision making.

Benefits

  • Empowers application developers with insights into network performance data, enabling them to take the right decisions so that the end users of the application have an optimal user experience.

Mobile Quality on Demand

API Description

The Quality on Demand API enables application developers to modify the network configuration of their End Users cellular connectivity (QoD profile) during certain periods of time to build certain features of their application regardless of the telco network operator that is serving the End Users. The developer can discover the catalogue of available QoD profiles that describe the network configuration and choose the one that must be activated.

https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qod-api.yaml

Use cases

  • Media and entertainment (e.g. gaming, streaming): online gamers and viewers of real-time streaming media require a network with a high level of performance to ensure good user experience.  
  • Remote control of machines and vehicles (e.g. Automated Guided Vehicles, drones, robotic arms, factory production lines): applications requiring remote control of machines or vehicles require stable data throughput and low latency. The requirements may change dynamically (e.g. piloting a drone vs drone transmitting video data) or not (e.g. specialised robotic arm or remote maintenance).  
  • Computer vision and remote video processing: applications that require a to send a continuous video stream so that their backends can process it and generate a timely output: alarms and events in the case of computer vision and a produced video stream for their audience 

Benefits

  • Optimize client networking. With the QoD service, you can activate the best networking configuration that suits better to the needs of your applications in real time. Regardless, your application requires a short boost with high throughput or a temporal control on the maximum jitter or latency, there’s a QoD profile ready for you to activate. 
  • Seamless user experience: Clients will enjoy the enhanced services you build with the capabilities brought to you by the QoD service without even noticing their network has been modified. This allows you to upsell advanced features with the security they will not suffer undesirable network issues 
  • Improve client satisfaction: Reduce the number of customer complaints whose cause is the networking of your clients because you can control and monitor the network conditions and adapt to them whenever your applications are being used. This will light those dark situations when customers didn’t experience your application as they should, and you weren’t able to manage. 
  • Integrate once, run with any telco: With a standardized API, you can seamlessly integrate the QoD service into your applications just once, this is, without the need for custom implementations for each telco operator. This simplifies your development process and reduces your time-to-market. 
  • Quick and easy onboarding: With the QoD service, you can configure the network of your clients easily with only a couple of lines of code. You will not have to guess and discover the available networking capabilities of their clients and will focus on what matters more to your business. 

Fixed Connectivity

API Product Family: Network Quality / Optimisation 

Home Devices Quality On Demand (QoD)

API Description

This API enables application developers to modify the network configuration of their End Users WiFi connectivity (service classes) to build certain features of their application regardless of the telco network operator that is serving the End Users. The developer can discover, choose and activate the service class that fits best with the needs of the application.

https://github.com/camaraproject/HomeDevicesQoD/blob/main/code/API_definitions/home_devices_qod.yaml

Use cases

  • Real-time entertainment (e.g. streaming, gaming): these applications require low response times and high throughput. The Home Devices QoD API allows the application developers to activate a multimedia streaming service class to the relevant devices to improve their end users user experience
  • Communications and conferencing: these applications require to activate a real-time interactive service class that provides the best latency to guarantee the call quality and avoid dropped calls

Benefits

  • Optimize your clients’ networking. With the QoD service, you can activate the best networking configuration that suits better to the needs of your applications in real time.
  • Seamless user experience: Your clients will enjoy the enhanced services you build with the capabilities brought to you by the QoD service without even noticing their network has been modified.
  • Improve your clients’ satisfaction: Reduce the number of customer complaints whose cause is the networking of your clients because you can control and monitor the network conditions and adapt to them whenever your applications are being used.
  • Quick and easy onboarding: With the QoD service, you can configure the network of your clients easily with only a couple of lines of code.

Cloud & Edge

API Product Family: MEC (Mobile Edge Cloud) 

Simple Edge Discovery

API Description

The API allows an application to discover the nearest Edge-Cloud node for it to connect to (maybe telco edge cloud or hyperscaler edge cloud, whichever is required).

https://github.com/camaraproject/EdgeCloud/blob/main/code/API_definitions/Discovery/simple_edge_discovery.yaml

Use cases

  • All edge cloud use cases e.g. automotive, mixed/augmented reality, high resolution video streaming, cloud gaming, remote control of moving objects or vehicles: for an application deployed in telco edge cloud or hyperscaler edge cloud, the device needs to be informed of the Edge-Cloud node to access. The application queries the API and is informed of the nearest Edge-Cloud node to connect to. It can then perform a DNS lookup to route traffic to this node.

Benefits

  • Enables selection of and routing towards the nearest edge cloud node, generally optimising network performance by minimising propagation delay.
  • More accurate selection based on Operator network topology rather than geolocation.

Traffic Influence

API Description

For Services that have latency requirements, especially when they are deployed at the Edge of the network, covering specific geographical areas with specific Service instances (Edge Application Servers), the Traffic Influence API provides an intent-based interface to request the best possible latency.

https://github.com/camaraproject/EdgeCloud/blob/main/code/API_definitions/Traffic%20Influence/Traffic_Influence.yaml

Use cases

  • A Service is usually provided by a Cloud instance of an Application for Standard users. In a specific geographical area, the Service must instead be provided by an edge instance of the Application (EAS) for Premium users. The Application Function (AF) of the Service invokes the Traffic Influence API (exposed by the OP) to activate the appropriate routing at the Edge of the mobile network toward the local EAS Instance for the Premium Users. Premium Users access the service in that geographical area with the best user experience while Free users get a best effort service provided by the Cloud instances of the Service. 
  • A Service is provided in different geographical locations by Edge instances of an Application Server. The user Device has a session active with an optimal latency  configured for one Edge instance of the application. The Device moves from that Edge to another Edge location. The Service requests the network to guarantee an optimal connection between the Device and the Application Server Instance in the destination Edge. 

Benefits

  • The routing of the mobile traffic is optimised toward a local instance of an Edge application to get the optimal latency.

Payments

API Product Family: Payments and Charging 

Carrier Billing

API Description

The API allows an online merchant to enable the purchase of third-party digital goods and to request payment against the user’s Operator carrier billing system. The API enables several related operations to the purchase (triggering purchase and consulting information to follow up on fulfilment); and to the payment, in one step by requesting carrier billing payment or with additional steps to prepare the payment before confirming or cancelling it. The Operator takes care of the billing. Usually the payment amount is added to the user’s phone bill or deducted from their prepaid balance and funds are paid to the merchant by the Operator.

https://github.com/camaraproject/CarrierBillingCheckOut/blob/main/code/API_definitions/carrier_billing.yaml

Use cases

  • Mobile payments across media, gaming, mobile services, ticketing, content, and other digital services: when reaching checkout online, the user gets the option to pay by mobile. If chosen, the merchant requests payment via the Carrier Billing API. The payment amount is added to the user’s phone bill or deducted from their prepaid balance. The settlement from the Operator to the merchant takes place to cover all users’ payments over a defined period.

Benefits

  • Convenient and secure online payment solution for unbanked / underbanked users who cannot pay by credit card
  • Increased conversion for merchants