How to use the API reference

📘

To try out our APIs, visit the Sandbox.

An API reference is a comprehensive document that provides detailed information about an API (Application Programming Interface), including how to use its functions, methods, endpoints, parameters, and data structures. It serves as a guide for developers who want to integrate or interact with the API in their applications.

In our developers’ website, you will find also a simple tool that uses your real credentials to make test calls.

📘

If you do not have an application in the sandbox, go to the Developer Hub and sign up.

Before getting started

Purposes

Each API has a string called “purpose” that defines the intended use of that API. This is a predefined string, and it is necessary to specify it in order to obtain the first part of the credential authentication:

• SIM Swap: dpv:FraudPreventionAndDetection#sim-swap
• Number Verification: dpv:FraudPreventionAndDetection#number-verification-verify-read
• Device Location Verification: dpv:FraudPreventionAndDetection#device-location-read
• Device Status: dpv:FraudPreventionAndDetection#device-status-roaming-read
• QoD: dpv:GeneralQAPurpose#qod

Config the API Reference step by step

Step 1: Get the authorization code

For a faster and easier authorization it is recomended to use a CIBA. This CIBA is going to authorize an application to access a resource from the backend:

• login_hint: The phone number you own and provided when creating your application. If you are using the Sandbox, it is the number you provided when requesting access to production. If your application is a mock, you can enter any invented number that does not end with 9. The sintax is <id_type>:<id_value> (tel:+34666555432)
• purpose: The purpose string for the API you want to call. You can check the purpose by clicking on one of the test calls in this API reference. If not, you have a list in the Before Getting Started section of this page.
• credentials: The username is your client_id and your password is you client_secret. You can get both from the info in your aplication. If you are using a Sandbox app you have this information in My Apps page, clicking in your app.

When finished, you page will look similar to the image below.

Step 2: Get the access token

For this step, go to the Retrieve an access token secction. Because this tutorial is using the CIBA, you must copy the authorization code in the ACCESSTOKENCIBAREQUEST tab:

• grant_type: Select the option urn:openid:params:ggrant-type:ciba
• auth_req_id: The auth_req_id you get in response of the last step

When finished, you page will look similar to the image below.

Step 3: Make your calls

The API Reference is now prepared to make calls to the Open Gateway's APIs. Check that the credentials you made are just for one API because of the purpose. Everytime you change the API you are consuming, you must change the purpose.
The variable common to all APIs is the access_token you get in response of the last step, which should be placed in the authentication section.