Cibil Credit Score

Endpoint Overview

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

Description

The CIBIL Credit Report Score API provides instant access to credit scores powered by TransUnion CIBIL, India's first and most trusted Credit Information Company. This endpoint enables businesses to retrieve accurate CIBIL credit scores for individuals using their PAN (Permanent Account Number), facilitating comprehensive credit risk assessment and informed lending decisions.

CIBIL credit scores range from 300 to 900 and are widely recognized as the benchmark for creditworthiness evaluation in India. With a database covering over 600 million individuals, CIBIL provides the most extensive credit information repository in the country. This API offers seamless integration with CIBIL's robust infrastructure, ensuring reliable credit assessments while maintaining strict compliance with regulatory standards and consent requirements.

Key Benefits

India's Most Trusted Bureau: Access credit scores from CIBIL, the most widely used and recognized credit bureau by lenders across India

Comprehensive Coverage: Leverage CIBIL's extensive database covering 600+ million credit profiles for maximum data availability

Industry Standard Scoring: Utilize the credit score that over 90% of Indian lending decisions are based on

Gender-inclusive Assessment: Supports gender parameter for enhanced demographic analysis and inclusive financial services

Use Cases

Lending & Credit

Fintech & Digital Banking

Enterprise & Partnerships

Personal Loan Approval: Streamline personal loan processing by instantly accessing CIBIL scores to determine eligibility, loan amounts, and interest rates

Home Loan Assessment: Evaluate mortgage applicants using India's most trusted credit score for high-value lending decisions

Auto Financing: Make quick vehicle loan decisions based on comprehensive CIBIL credit profiles

Credit Card Issuance: Assess credit card applicants and determine appropriate credit limits using CIBIL's industry-standard scoring

Pre-approved Credit Offers: Identify customers with excellent CIBIL scores for targeted pre-approved loan and credit campaigns

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
pan	string	Yes	Permanent Account Number (PAN) of the individual - 10 alphanumeric characters
mobile	string	Yes	10-digit mobile number of the individual
name	string	Yes	Full name of the individual as per their PAN card (can be uppercase or mixed case)
consent	string	Yes	User consent for credit check. Must be `Y` for yes
gender	string	Yes	Gender of the individual. Accepted values: `male`, `female`

Example Request

{
    "pan": "ABCPD1234F",
    "mobile": "9999000900",
    "name": "RAJIV TALWAR",
    "consent": "Y",
    "gender": "male"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Contains the CIBIL credit report information
data.client_id	string	Unique identifier for the credit report request
data.name	string	Name of the individual as retrieved from CIBIL (typically uppercase)
data.mobile	string	Mobile number of the individual as provided in the request
data.pan	string	PAN number used for the credit check
data.gender	string	Gender of the individual as provided in the request
data.credit_score	string	CIBIL credit score value (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": "cibil_credit_score_lGzdvkNakDDseIbcCMkr",
        "name": "RAJIV TALWAR",
        "mobile": "9999000900",
        "pan": "ABCPD1234F",
        "gender": "male",
        "credit_score": "663"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Missing Consent

Invalid Gender

{
    "status_code": 401,
    "success": false,
    "message": "Invalid or expired Bearer token",
    "message_code": "unauthorized"
}

This error occurs when the JWT Bearer token is missing, invalid, or expired. Generate a new token using valid API credentials and retry the request.

Integration Best Practices

Security Recommendations

Token Security: Store JWT Bearer tokens securely in environment variables or secure vaults; implement token rotation policies every 24-48 hours

Encrypted Communication: Always use HTTPS endpoints; never transmit credit check requests over unsecured connections

PAN Data Encryption: Encrypt PAN numbers both at rest and in transit using industry-standard encryption algorithms (AES-256)

Access Logging: Maintain comprehensive audit logs of all CIBIL credit checks including user identity, timestamp, purpose, and results

Role-Based Access: Restrict credit score access to authorized personnel only using principle of least privilege

API Key Protection: Never expose API keys or JWT tokens in client-side code, mobile apps, or public repositories

Request Validation: Implement server-side validation for all input parameters to prevent injection attacks and malformed requests

Secure Storage: If storing credit scores, ensure database encryption and implement data retention policies compliant with regulations

User Experience Guidelines

Transparent Consent: Design clear consent flows explaining that CIBIL credit checks will be recorded as inquiries on the user's credit report

Real-time Validation: Validate PAN format (ABCDE1234F pattern) and mobile numbers client-side before API submission to reduce errors

Loading States: Display meaningful progress indicators during the 2-5 second processing time with messages like "Fetching your CIBIL score..."

Score Interpretation: Provide context about CIBIL score ranges (300-900) and what different score bands mean for loan eligibility

Error Communication: Use friendly, actionable error messages that guide users on next steps rather than technical jargon

Gender Selection: Offer inclusive gender options in your UI with clear labeling; map to API's male/female values appropriately

Privacy Messaging: Clearly communicate how credit score data will be used and stored, building user trust

Inquiry Impact Notice: Inform users that this credit check will appear on their CIBIL report as an inquiry

Mobile Optimization: Ensure forms work seamlessly on mobile devices with appropriate keyboard types for different input fields

Graceful Degradation: Handle "no credit history" scenarios thoughtfully, offering alternative verification methods if needed

Code Samples

cURL

Python

Node.js

Compliance and Legal Considerations

TransUnion CIBIL Compliance: This API operates in full compliance with TransUnion CIBIL's terms of service and Credit Information Companies (Regulation) Act, 2005

Reserve Bank of India (RBI) Guidelines: Adheres to RBI regulations governing credit information and fair lending practices in India

Explicit Consent Requirement: Indian law mandates obtaining explicit, informed, and verifiable consent from individuals before accessing their CIBIL credit information

Digital Personal Data Protection Act, 2023: Comply with data protection regulations for collection, processing, storage, and sharing of personal credit information

Credit Inquiry Recording: Each CIBIL score request is recorded as a "hard inquiry" on the individual's credit report, which may impact their credit score

Inquiry Impact Management: Multiple credit inquiries within short periods (30-45 days) can negatively affect credit scores; implement inquiry management strategies

Purpose Limitation: Credit information must be used exclusively for legitimate purposes such as credit assessment, lending decisions, or risk evaluation as authorized by law

Data Retention Requirements: Maintain audit logs and credit check records for regulatory compliance, typically 3-5 years for financial transactions

Fair Credit Reporting Practices: Use CIBIL scores as one component of a holistic, non-discriminatory credit evaluation process

PAN Protection: PAN is classified as sensitive personal information under IT Act, 2000; implement appropriate safeguards against unauthorized access or breaches

Consumer Rights: Inform users of their rights to access credit reports, dispute inaccuracies, understand score factors, and receive adverse action notices

Gender Data Sensitivity: Handle gender information with care and comply with evolving regulations on gender data collection and usage

Vendor Agreement: Ensure your organization has a valid agreement with Surepass and appropriate licenses to access CIBIL data

Regulatory Reporting: Be prepared to report credit data access and usage to regulatory authorities as required

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-cibil/score' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "pan": "ABCPD1234F", "mobile": "9999000900", "name": "RAJIV TALWAR", "consent": "Y", "gender": "male" }'

{ "data": { "client_id": "cibil_credit_score_lGzdvkNakDDseIbcCMkr", "name": "RAJIV TALWAR", "mobile": "9999000900", "pan": "ABCPD1234F", "gender": "male", "credit_score": "663" }, "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