Mule Score API

Endpoint Overview

POST /api/v1/mule-score/score

Description

The Mule Score API evaluates an individual's fraud risk and digital identity strength using their name, email, and mobile number. It provides a comprehensive profile including a risk score, digital footprint, UPI verification, employment history, and email legitimacy. This helps businesses make informed decisions about onboarding and risk management.

Key Benefits

Assesses fraud risk with a detailed scoring mechanism.

Confirms digital identity and activity over time.

Validates employment and UPI details for additional confidence.

Provides detailed analytics based on phone, email, and name history.

Use Cases

Banking & Financial Services

Fintech Platforms

E-commerce & Marketplaces

Evaluate loan applicants for fraud risk before disbursal.

Validate KYC and employment details during onboarding.

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	JWT Bearer token (e.g. `Bearer YOUR_TOKEN`)
Content-Type	Yes	Must be `application/json`

Request Body

Parameter	Type	Required	Description
mobile_number	string	Yes	The user's mobile number
email_id	string	Yes	The user's email address
name	string	Yes	The user's full name

Example Request

{
    "mobile_number": "8079038383",
    "email_id": "bishalrathore@gmail.com",
    "name": "BISHAL SINGH"
}

Process Response

Response Parameters

Parameter	Type	Description
client_id	string	Unique ID for this API call
name	string	Name of the user
email_id	string	Email used for verification
mobile_number	string	Mobile number used
mule_score	object	Fraud risk details including score and risk category
digital_identity_score	object	Digital presence score and historical footprints
upi_details	object	UPI ID and verification status
employment_details	object	UAN and employment verification
email_details	object	Email validity and metadata
status_code	number	HTTP status code
success	boolean	Whether the request was successful
message	string	API message
message_code	string	Internal message code

Example Successful Response

{
    "data": {
        "client_id": "mule_score_rsraYjppfYACqbGbejtJ",
        "name": "BISHAL SINGH",
        "email_id": "bishalrathore@gmail.com",
        "mobile_number": "8079038383",
        "mule_score": {
            "score": 824,
            "risk_category": "very_low_risk",
            "name_match_score": 62.0
        },
        "digital_identity_score": {
            "impact": "positive",
            "digital_identity_score": "518",
            "digital_footprint": "Medium",
            "travel_footprint": null,
            "fintech_approved": "3",
            "upi_vpa_count": "0",
            "age_band": "21 - 25 Years",
            "gender": "Male",
            "name_match_score": "62",
            "phone_first_seen_year": "2019",
            "email_first_seen_year": "2021",
            "phone_email_first_seen_year": "2021",
            "phone_email_last_seen_year": "2024",
            "phone_name_first_seen_year": "2020",
            "phone_name_last_seen_year": "2024",
            "email_name_first_seen_year": "2021",
            "email_name_last_seen_year": "2024"
        },
        "upi_details": {
            "impact": "positive",
            "full_name": "MR BISHAL SINGH RATHORE",
            "upi_id": "8079039393@pthdfc",
            "mobile_number": "8079038383"
        },
        "employment_details": {
            "impact": "positive",
            "uan": "101669824010",
            "employment_details": {
                "status": "V",
                "email_id": "bishalrathore@gmail.com",
                "dob": "2001-07-25",
                "gender": "M"
            }
        },
        "email_details": {
            "impact": "positive",
            "email": "bishalrathore@gmail.com",
            "status": "safe",
            "valid": true,
            "accepts_mail": true,
            "domain_age": 0,
            "username": "bishalrathore",
            "disabled": false
        }
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Token

Missing Fields

{
    "error": null,
    "message": "Your token is invalid. Please ensure that correct token is being used.",
    "status_code": 401,
    "success": false,
    "message_code": "invalid_token"
}

JWT token is missing, expired, or malformed.

Integration Best Practices

Security Recommendations

Always use HTTPS endpoints to secure your requests.

Store JWT tokens securely and avoid exposing them in client-side code.

Rotate API credentials periodically.

User Experience Guidelines

Validate user input before making the API call.

Display the risk category clearly in your UI.

Handle all possible error responses gracefully.

Code Samples

cURL

Python

Node.js

Related APIs

/api/v1/verify/email: Validates and checks metadata for an email.

/api/v1/verify/mobile: Checks phone number reputation and usage history.

/api/v1/verify/upi: Validates UPI ID and user name mapping.

Compliance and Legal Considerations

Ensure all usage of this API complies with applicable privacy regulations like GDPR or India’s DPDP Act. Collect user consent where required before processing personal data.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/mule-score/score' \ --header 'Content-Type: application/json' \ --data-raw '{ "mobile_number": "8079038383", "email_id": "bishalrathore@gmail.com", "name": "BISHAL SINGH" }'

{ "data": { "client_id": "mule_score_rsraYjppfYACqbGbejtJ", "name": "BISHAL SINGH", "email_id": "bishalrathore@gmail.com", "mobile_number": "8079038383", "mule_score": { "score": 824, "risk_category": "very_low_risk", "name_match_score": 62.0 }, "digital_identity_score": { "impact": "positive", "digital_identity_score": "518", "digital_footprint": "Medium", "travel_footprint": null, "fintech_approved": "3", "upi_vpa_count": "0", "age_band": "21 - 25 Years", "gender": "Male", "name_match_score": "62", "phone_first_seen_year": "2019", "email_first_seen_year": "2021", "phone_email_first_seen_year": "2021", "phone_email_last_seen_year": "2024", "phone_name_first_seen_year": "2020", "phone_name_last_seen_year": "2024", "email_name_first_seen_year": "2021", "email_name_last_seen_year": "2024" }, "upi_details": { "impact": "positive", "full_name": "MR BISHAL SINGH RATHORE", "upi_id": "8079039393@pthdfc", "mobile_number": "8079038383" }, "employment_details": { "impact": "positive", "uan": "101669824010", "employment_details": { "status": "V", "email_id": "bishalrathore@gmail.com", "dob": "2001-07-25", "gender": "M" } }, "email_details": { "impact": "positive", "email": "bishalrathore@gmail.com", "status": "safe", "valid": true, "accepts_mail": true, "domain_age": 0, "username": "bishalrathore", "disabled": false } }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Mule Score

Mule Score API#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Mule Score API

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples