Telco Score API

Telco scores are statistical models built on various MNO(Mobile Network Operator) data sources such as data and voice usage, top-up patterns, location and device data, and many more. Derived by the most advanced machine learning algorithms, the scores have significant predictive power and can be used as either standalone models or in combination with exiting internal Social-Demographic and/or Credit Bureau models. This is currently available for SMART and Globe mobile numbers.

Versions

We have several versions(models) of the Telco score for prepaid and postpaid customers. These distinct versions are developed using diverse loan product payment information. All scores are calibrated to the same scale.When clients come on board, they will receive product IDs associated with the chosen version. Each individual model will encompass a specific spectrum of scores and bands for both postpaid and prepaid numbers, contingent upon the Mobile Network Operator (MNO).

Example: Below is an example score and band range for SMART prepaid and postpaid customer for a telco score model.

SMART Prepaid Customer

• Score Range: 300 to 600

• Score Bands:

SCORE BAND	RISK LEVEL
1	Highest
2	Highest
3	High
4	High
5	Medium
6	Medium
7	Low
8	Low
9	Low
10	Low

SMART Postpaid Customer

• Score Range: 700 to 999

• Score Bands:

SCORE BAND	RISK LEVEL
21	High
22	Medium
23	Low

Note: The score bands and ranges may vary from the values provided above in certain models. Additionally, there are specific instances where default values can be assigned to the score bands. Clients will receive specific information about the score bands, ranges, and any special case values associated with the chosen model during the onboarding process. Below, an illustration is presented that showcases default values for special cases within one of the models.

Default value	Definition
-9	Sun cellular subscribers
-8	Smart broadband subscribers and others
-7	Smart prepaid and postpaid subscribers, registered before less than 10 days
-6	Smart prepaid subscribers without top-ups in the last 90 days

This section enumerates all values that could be returned in the error code field.

Code	HTTP Status	Message	Note
1111	500	General Error	Something on our side is wrong. We are looking into it
	422	Request Id not found	Request ID is missing in the request
	422	Mobile number format is not correct	Incorrect mobile number format in the request
	422	Product ids not found	Product ID is missing in the request
	422	Mobile number is not a valid SMART / Globe number	Globe mobile number is sent in the request with SMART product ID or SMART mobile number is sent in the request with Globe product ID.
	422	Product ids unknown id in the list	The product IDs do not exist

Authentication

Prerequisites

In order to obtain an API Token you first need to have client_id and client secret from the previous step.

Token Request Flow

To authenticate and obtain an OAuth token, follow the standard OAuth token request flow.

• POST API URL

Copy

https://sandbox-app.lenderlink.ph/oauth/token

• Grant Type

Use this grant type when the client is a server and does not require user authentication.

Copy

"grant_type": "client_credentials"

• Requesting the Access Token

To request the Access Token, submit a POST request to the API URL, including the following body parameters in JSON format:

Copy

{
    "grant_type": "client_credentials",
    "client_id": "your client id",
    "client_secret": "your client secret",
}
                                        

• Handling the Token Response

Upon successful validation, the authorization server will respond with an access token:

{
    "token_type": "Bearer",
    "expires_in": 86400,
    "access_token": "eyJ0eXAiOiJKasd10sJhbGciOiJSUzI1NiJ9.eyJhdWQiOiI5YTc4MzVm..."
}
                                        

• Token Lifespan

Access tokens have a limited lifespan of 86400 seconds. Once the token expires, you can obtain a new one.

Endpoint

The API endpoint for accessing the telco score is:

https://sandbox-app.lenderlink.ph/api/v1/telco/score

Request Parameters

The request should include the following parameters:

Parameter	Mandatory	Description
mobileNumber	Yes	The mobile number of the client for whom you want to generate the telco score. Format 639XXXXXXXXX
productIds	Yes	parameter is a semicolon-separated list of product codes that you want to use for the telco score. For Sandbox API testing, you can use "G;" for SMART and "GL1;" for Globe.
requestId	Yes	Identifier for the API request. It should be a unique value for each API call.

Response Parameters

The API response will contain the calculated telco scores for the mobile number sent in the request. The response will be in JSON format and will include the following fields:

Parameter	Type	Mandatory	Description
requestId	String	Yes	Unique identifier for the request.
transactionId	String	Yes	Unique system identifier for the transaction.
code	String	Yes	Operation code.
result	String	Yes	Operation result, indicating the success or failure of the request.
score	Object	Yes	An object containing score and band values in numeric format.

Example

POST Telco Score for SMART number

https://sandbox-app.lenderlink.ph/api/v1/telco/score

{
  "mobileNumber": "639XXXXXXXXX",
  "productIds": "G;",
  "requestId": "X123-AB45"
}

Example Response

{
  "requestId": "X123-AB45",
  "transactionId": "f2279c3df6eb4368a8ec31c0ca561c8a",
  "code": "0000",
  "result": "ok",
  "scores": {
    "G": [
      [
        "score",
        337
      ],
      [
        "band",
        1
      ]
    ]
  }
}

POST Telco Score for Globe number

https://sandbox-app.lenderlink.ph/api/v1/telco/score

{
  "mobileNumber": "639XXXXXXXXX",
  "productIds": "GL1;",
  "requestId": "X123-AB45"
}

Example Response

{
  "requestId": "X123-AB45",
  "transactionId": "9952685694bb4a33938fe4b1c3590874",
  "code": "0000",
  "result": "ok",
  "scores": {
    "GL1": [
      [
        "score",
        576
      ],
      [
        "band",
        10
      ]
    ]
  }
}