Equifax Credit Score

Endpoint Overview

POST /api/v1/credit-report-v2/score

Description

The Credit Report V2 Score API enables you to retrieve comprehensive credit scores for individuals in India using either their PAN (Permanent Account Number) or Aadhaar identification. This endpoint provides real-time access to credit bureau data, delivering accurate credit scores that help assess an individual's creditworthiness and financial reliability.

This API integrates with Equifax, one of India's leading credit information companies, to provide standardized credit scores ranging from 300 to 900. The higher the score, the better the individual's credit profile. This service is essential for financial institutions, lending platforms, and businesses that need to evaluate credit risk before extending credit facilities.

Key Benefits

Real-time Credit Assessment: Instant retrieval of credit scores for quick decision-making

Dual Identification Support: Accepts both PAN and Aadhaar for flexible verification

Structured JSON Response: Easy-to-parse response format for seamless integration

Consent-based Verification: Compliant with regulatory requirements for user consent

Use Cases

Financial Services

Fintech & Digital Lending

E-commerce & Marketplace

Loan Origination: Quickly assess loan applicants' creditworthiness during the application process to determine eligibility and interest rates

Credit Card Issuance: Evaluate potential credit card customers to set appropriate credit limits and terms

Pre-approved Offers: Identify customers with good credit scores for targeted pre-approved loan or credit offers

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.app

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

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication (Format: `Bearer YOUR_JWT_TOKEN`)
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
name	string	Yes	Full name of the individual as per their ID document
id_number	string	Yes	The identification number - either PAN or Aadhaar number
id_type	string	Yes	Type of identification document. Accepted values: `pan` or `aadhaar`
mobile	string	Yes	10-digit mobile number of the individual
consent	string	Yes	User consent for credit check. Must be `Y` for yes
gender	string	Yes	Gender of the individual. Accepted values: `male`, `female`
report_type	string	Yes	Format of the report. Use `json` for JSON response

Example Request

{
    "name": "Rajiv Talwar",
    "id_number": "ABCPD1234F",
    "id_type": "pan",
    "mobile": "9876543210",
    "consent": "Y",
    "gender": "male",
    "report_type": "json"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Contains the credit report information
data.client_id	string	Unique identifier for the credit report request
data.name	string	Name of the individual as provided in the request
data.mobile	string	Mobile number of the individual
data.id_number	string	Identification number used for the credit check
data.id_type	string	Type of ID used (pan or aadhaar)
data.gender	string	Gender of the individual
data.credit_score	string	Credit score value (typically ranges from 300 to 900)
status_code	integer	HTTP status code of the response
success	boolean	Indicates whether the request was successful
message	string	Human-readable message about the request status
message_code	string	Machine-readable message code for the status

Example Successful Response

{
    "data": {
        "client_id": "equifax_credit_score_kfaLqQurYXCxmtDuzcic",
        "name": "Rajiv Talwar",
        "mobile": "9876543210",
        "id_number": "ABCPD1234F",
        "id_type": "pan",
        "gender": "male",
        "credit_score": "715"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Input

Consent Not Provided

Record Not Found

{
    "status_code": 400,
    "success": false,
    "message": "Invalid id_type. Must be 'pan' or 'aadhaar'",
    "message_code": "invalid_input"
}

This error indicates that one or more request parameters contain invalid values. Verify all required fields are properly formatted.

Integration Best Practices

Security Recommendations

Secure Token Storage: Store JWT tokens securely using environment variables or secure vaults; never hardcode tokens in your application code

HTTPS Only: Always use HTTPS endpoints to ensure encrypted data transmission

Token Rotation: Implement regular token rotation policies to minimize security risks

Rate Limiting: Implement appropriate rate limiting on your end to prevent abuse and manage API costs

Data Encryption: Encrypt sensitive user data (PAN, Aadhaar, mobile) in your database and during transmission

Audit Logging: Maintain comprehensive logs of all credit check requests for compliance and security auditing

User Experience Guidelines

Explicit Consent: Always obtain explicit user consent before fetching credit scores, displaying clear information about how the data will be used

Loading Indicators: Display appropriate loading states as credit score retrieval may take a few seconds

Error Handling: Provide user-friendly error messages that guide users on how to resolve issues (e.g., "Please verify your PAN number and try again")

Privacy Notice: Inform users that their credit score request will be recorded by the credit bureau

Transparent Communication: Explain what the credit score means and how it affects their application or eligibility

Retry Mechanism: Implement intelligent retry logic with exponential backoff for transient failures

Code Samples

cURL

Python

Node.js

Compliance and Legal Considerations

Credit Information Companies Regulation: This API complies with regulations set by the Reserve Bank of India (RBI) for credit information companies

User Consent Mandatory: You must obtain explicit written or digital consent from users before accessing their credit information, as required by Indian law

Data Privacy: Handle credit information in accordance with the Digital Personal Data Protection Act, 2023 and maintain strict data confidentiality

Purpose Limitation: Credit scores should only be used for legitimate purposes such as credit evaluation, and not for discriminatory practices

Data Retention: Maintain credit check records as per regulatory requirements, typically for a minimum period as specified by the credit bureau

Inquiry Impact: Be aware that credit inquiries may impact the individual's credit report; multiple inquiries in a short period may affect credit scores

Fair Lending Practices: Use credit scores as part of a fair and transparent lending decision process, not as the sole criterion

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/credit-report-v2/score' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Rajiv Talwar", "id_number": "ABCPD1234F", "id_type": "pan", "mobile": "9876543210", "consent": "Y", "gender": "male", "report_type": "json" }'

{ "data": { "client_id": "equifax_credit_score_kfaLqQurYXCxmtDuzcic", "name": "Rajiv Talwar", "mobile": "9876543210", "id_number": "ABCPD1234F", "id_type": "pan", "gender": "male", "credit_score": "715" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

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