How to Implement the Mono Telco Data API

What is the Mono Telco Data API?

The Mono Telco Data API allows businesses in Nigeria to securely access customers' telco data with their consent. This helps them retrieve an alternative source of data such as the users’ identity details, airtime and data balances, account information, airtime/data usage and borrowing history, and more. With this data, businesses can make more data-informed decisions and build financially relevant services for unbanked customers.

How does the Mono Telco Data API work?

The Mono Telco Data API functions through a series of steps that ensure secure access to the user's telco information. Here’s how the process works:

• On your app or website, the user will be prompted to login with their mobile phone number and select their mobile network provider, such as Airtel or MTN.

• Then they will be required to authorize access to their telco data by entering the verification OTP sent to their phone number.

• Once verified, a temporary token is exchanged for a permanent telco Account ID.

• Finally, the user’s telco account information such as their balances, transactions, and identity details will be successfully retrieved.

How your business can use the Mono Telco Data API

1. Credit scoring during loan applications: Financial institutions especially those targeting the unbanked can use the Telco Data API to access a user's telecom account details, including transaction history and account balances. This information can help them assess the creditworthiness of borrowers applying for loans, leading to more informed lending decisions.

2. Fraud detection in identity verification: By integrating the Telco Data API, companies can verify the identity and transaction history of their users. This can be particularly useful in detecting and preventing fraudulent activities.

3. Customer insights: Businesses can leverage the Telco Data API to gain insights into customer behaviour based on their telecom usage patterns and preferences. This information can be used for targeted or personalized services or promotions, enhancing customer engagement and loyalty.

Benefits of using the Mono Telco Data API

The Mono Telco Data API offer several advantages:

1. Streamlined access to data: It provides reliable access to a wealth of telco data points, from account balances to transaction history.

2. Enhanced security: The use of OTPs and secret keys ensures secure access to users’ sensitive information.

3. Real-time data retrieval: Developers can access up-to-date information, allowing for real-time data integration in their applications.

4. Data privacy: The process ensures that data is accessed only after the user has authorized it, maintaining user trust and compliance with privacy regulations.

5. Diverse application use: These APIs can be used in a variety of applications, from financial services to identity verification processes.

Best practices for implementing the Mono Telco Data API

Here’s what you should consider to ensure that you successfully integrate the Mono Telco Data API into your service:

1. Secure authentication process: You should implement a robust authentication mechanism when integrating the Mono Telco Data API. This involves securely handling the user's telco phone number and provider information, and correctly using the API's authentication endpoint to initiate the login process. Ensuring the confidentiality of the user's phone number and the integrity of the authentication process is crucial.

2. Accurate OTP verification: A critical step in the integration is the accurate handling of One-Time Password (OTP) sent to the user’s phone number. You must ensure that the OTP is correctly passed to the Telco verification API for authorization once received from the user. This step is vital for confirming user consent and accessing their telco data securely.

3. Efficient token management: The API integration process involves exchanging a temporary token for a permanent telco Account ID. You must implement an efficient token management system that securely stores and retrieves these tokens. Given that the authorization token expires after 10 minutes, it's important to manage these tokens promptly and securely to maintain a seamless user experience.

4. Error handling: Implementing robust error-handling mechanisms for these API calls is essential. This includes gracefully handling scenarios where data may not be available or when unexpected API responses are received, thereby ensuring a reliable and user-friendly application.

5. Rate limiting: This involves setting a threshold on the number of OTP requests that can be sent from a single IP address or user account within a specified time frame, thereby preventing abuse and spam. This rate-limit feature is important so that OTP requests are not abused or spammed.

How to implement the Mono Telco Data API into your product

We’ll be outlining how to implement the Telco Data APIs into your product. To get started, you need to ensure that you:

1. Create an account on Mono, if you don’t have one.

2. Submit all required business documents and complete the compliance process.

3. Create an app on the Mono dashboard and select connect as your product scope. Here’s how to create an app and choose your product scope.

4. Lastly, make sure you have your App keys. Here is a guide on how to generate your secret key on the Mono dashboard.

Note that you need your App secret key to make a call to any Mono endpoint. The mono-sec-key (secret key) is used in the headers to make a successful request.

Now, for this article, we will be showing you how to retrieve the user’s identity and balance information via the Telco Data API.

Step 1: Initiating authentication

To initiate an API call to the Telco authentication API, send a request to the designated URL. This request should include the user's phone number and their telco provider (e.g., Airtel, MTN) in the body. Additionally, incorporate your Mono secret Key in the request header for secure authentication.

Expected API response:

If this call is successful, you will receive a response with the session ID and form to be used in the next step.

Step 2: Verifying OTP

After obtaining the OTP sent to the user's phone, make a POST request to the Telco verification API. This request must contain the OTP for verification, while the session ID received from the response in the authentication step and your secret key is passed in the header.

Expected API response:

If this call is successful you will receive a code that must be exchanged for a permanent account ID.

Step 3: Acquiring an account ID

Next, pass the temporary token received from the OTP verification response with your secret key, exchanging it for a permanent telco Account ID. Keep in mind that the authorization token is only valid for 10 minutes.

Expected API response:

If this call is successful you will receive a permanent account ID that can be used to make a call to other account information endpoints.

Step 4: Retrieving identity information

To retrieve detailed identity data from a telco account, make a GET request to the designated URL as seen in the image below. Here, the Account ID retrieved earlier is passed as a path parameter along with the secret key in the headers to obtain the user's identity information.

Expected API response:

If this call is successful you will receive a response containing the user identity details like their full name, gender, and date of birth along with other details.

Step 5: Retrieving account balance

To retrieve an accurate telco account balance, make a GET request to the designated URL passing the Account ID retrieved earlier as a path parameter. Also, add the secret key in the headers to obtain the user's identity information as seen in the image below. Note that this process is also applicable to other details like transaction history. You can check our integration guide for more information about retrieving other account information.

Expected success response:

If this call is successful, you will receive a response containing the user’s balance i.e. main airtime balance, roaming bundle balance, data bundle balance, and much more.

For a seamless integration process, kindly note the following:

• We only currently support MTN and Airtel telco providers

• The session ID lasts for only 10 mins. After that, you will need to reinitiate a connection.

• The data from a newly ported phone number doesn’t migrate from the old telco provider. you are only able to see data from the current telco provider.

The Mono Telco Data API offers businesses and developers, a secure and efficient way to access an alternative source of data from users’ telco networks, opening up a wide range of financial possibilities and more inclusive services for these customers.

If you are interested in integrating the Mono Telco Data API into your product, you can sign up to get started or you can reach out to us via sales@mono.co. For more resources on integrating the Telco Data API, check out our API documentation and if you experience any issues, you can email us at integrations@mono.co, we will be happy to assist.