CIBIL_Credit_Report_V1 — Credit Bureau Report API

CIBIL_Credit_Report_V1 v1 live

Download as Markdownthe full page as a single .md file — for offline reading or as context for an AI assistant

Authentication

Every request must carry your API key in the X-API-Key header. Your key is issued to you separately by ops and is never shown in this document.

X-API-Key: <your-key>

Base URL

All endpoints are served through the gateway:

https://api.pehchaantech.com

Endpoints

POST /cibil-credit-report/v1

URL	`https://api.pehchaantech.com/cibil-credit-report/v1`
Timeout	35000 ms
Rate limit	60 req/min · 100000 req/day

Overview

Retrieve an individual’s TransUnion CIBIL credit bureau report: tradelines with balances, credit limits and month-by-month payment history, enquiries, the credit summary, and the CIBIL score with its reason codes. One call returns the whole report.

mobile_number, full_name, pan and consent_declaration are the ONLY accepted fields, and the first three are all required. The bureau matches on full_name and pan together, so a name that does not match the PAN’s registered name is the most common cause of a not_found on someone who does have a credit file. consent_declaration must exactly equal the required attestation text (see field descriptions below); it is YOUR confirmation that you obtained the individual’s consent before pulling their credit file, and is checked before any pull happens, so a missing/wrong value costs nothing.

Every response — success or not — uses the same envelope, so branch on the status field. There is NO pending state; every response is final. Latency is capped at 30 seconds, so set your client timeout to at least 35 seconds.

THE REPORT IS DEEPLY NESTED — plan for that rather than expecting a flat object. result wraps a further data object holding cibil_report_url and cibil_data, and the report proper sits about seven levels down. The score most integrations want is at result.data.cibil_data.get_customer_assets_response.get_customer_assets_success.asset.true_link_credit_report.borrower.credit_score.risk_score. Monetary and count values arrive as STRINGS, and the bureau uses "-1" to mean "not reported" rather than zero — treat it as absent, not as a real amount.

TREAT cibil_report_url AS A CREDENTIAL, NOT A DATUM. It is a live link that shows the individual’s full credit report without any further authentication, and it carries their PAN in the query string. Do not log it, forward it, or place it anywhere the individual themselves would not be authenticated. If you do not intend to show them their own report, drop the field on receipt.

BILLING: completed and not_found are both billable — the bureau was actually queried either way, and a thin-file individual with no record is a real, billed pull. invalid_input is NOT billable — a rejected request never reached the bureau. Validate inputs before calling (a malformed mobile number, PAN or name is rejected with 422 and costs nothing), don’t loop on not_found, and cache — two calls for the same individual are two charges. Note that a name which does not match the PAN’s registered name reads as not_found and bills like a hit.

This is a soft/consumer-initiated retrieval of the individual’s own credit information, made on their consent. It is not a lending decision service: the report is returned to you as data, with no score interpretation, recommendation or eligibility verdict attached.

Request example

{
  "pan": "ABCDE1234F",
  "full_name": "Rohit Kumar Sharma",
  "mobile_number": "9876543210",
  "client_ref_num": "onboard-7f3a2b",
  "consent_declaration": "I take consent to collection and processing of data"
}

Response example

{
  "result": {
    "data": {
      "cibil_data": {
        "get_customer_assets_response": {
          "response_status": "Success",
          "get_customer_assets_success": {
            "asset": {
              "type": "SingleCreditReport",
              "status": "Active",
              "true_link_credit_report": {
                "borrower": {
                  "credit_score": {
                    "risk_score": "780",
                    "score_name": "CIBILTransUnionScore3",
                    "population_rank": "15"
                  },
                  "borrower_name": {
                    "name": {
                      "forename": "ROHIT KUMAR SHARMA"
                    }
                  }
                },
                "inquiry_partition": [],
                "trade_line_partition": [
                  {
                    "trade_line": {
                      "date_opened": "2024-10-22",
                      "high_balance": "39186",
                      "creditor_name": "EXAMPLE BANK",
                      "current_balance": "11144"
                    }
                  }
                ]
              }
            },
            "credit_summary_data": {
              "inquires": "0",
              "credit_card_utilization": "3.31",
              "on_time_payment_history": "100",
              "oldest_credit_account_period": "21"
            }
          }
        }
      },
      "cibil_report_url": "https://myscore.cibil.com/CreditView/webtokenasset.page?enterprise=…&webtoken=…"
    }
  },
  "status": "completed",
  "success": true,
  "description": "Credit report retrieved successfully",
  "client_ref_num": "pehchaan-b5f08841d8f1"
}

Fields

Field Description

mobile_number Required. 10-digit Indian mobile number, first digit 6-9 (^[6-9]\d{9}$).

full_name Required. The individual’s full name as the bureau holds it. A letter, then letters, spaces, periods, apostrophes or hyphens; 100 chars max ("O’Brien", "Van Der Berg", "D. Kumar"). ONE field — do not send first_name/last_name.

pan Required. Permanent Account Number — 5 letters, 4 digits, 1 letter (e.g. ABCDE1234F). Case-insensitive; forwarded as sent.

consent_declaration Required. Must exactly equal "I take consent to collection and processing of data" — your attestation that you obtained the individual’s consent to pull their credit file. Not forwarded to the bureau. A missing or incorrect value is a free 422, before any pull.

client_ref_num Optional trace id; 6–64 chars of A-Z a-z 0-9 . _ -. Omit and the platform generates one. Each call is an independent pull, so use a FRESH value per attempt. Also returned in the X-Client-Ref-Num response header.

success true only when a report was delivered.

status Machine-readable outcome — branch on this (see Outcomes below).

result The credit report — present only when status = completed, otherwise null. NESTED: result.data holds cibil_report_url (a credential — see above) and cibil_data, under which get_customer_assets_response.get_customer_assets_success carries credit_summary_data and asset.true_link_credit_report — the latter holding borrower (with credit_score), trade_line_partition[] and inquiry_partition[]. Treat it as an OPEN structure: any sub-object or array can be empty or absent, monetary and count values arrive as STRINGS, "-1" means not reported rather than zero, and new fields may appear without notice. Read the paths you need defensively rather than validating against a fixed schema.

Field	Description
`mobile_number`	Required. 10-digit Indian mobile number, first digit 6-9 (^[6-9]\d{9}$).
`full_name`	Required. The individual’s full name as the bureau holds it. A letter, then letters, spaces, periods, apostrophes or hyphens; 100 chars max ("O’Brien", "Van Der Berg", "D. Kumar"). ONE field — do not send first_name/last_name.
`pan`	Required. Permanent Account Number — 5 letters, 4 digits, 1 letter (e.g. ABCDE1234F). Case-insensitive; forwarded as sent.
`consent_declaration`	Required. Must exactly equal "I take consent to collection and processing of data" — your attestation that you obtained the individual’s consent to pull their credit file. Not forwarded to the bureau. A missing or incorrect value is a free 422, before any pull.
`client_ref_num`	Optional trace id; 6–64 chars of A-Z a-z 0-9 . _ -. Omit and the platform generates one. Each call is an independent pull, so use a FRESH value per attempt. Also returned in the X-Client-Ref-Num response header.
`success`	true only when a report was delivered.
`status`	Machine-readable outcome — branch on this (see Outcomes below).
`result`	The credit report — present only when status = completed, otherwise null. NESTED: result.data holds cibil_report_url (a credential — see above) and cibil_data, under which get_customer_assets_response.get_customer_assets_success carries credit_summary_data and asset.true_link_credit_report — the latter holding borrower (with credit_score), trade_line_partition[] and inquiry_partition[]. Treat it as an OPEN structure: any sub-object or array can be empty or absent, monetary and count values arrive as STRINGS, "-1" means not reported rather than zero, and new fields may appear without notice. Read the paths you need defensively rather than validating against a fixed schema.

Errors

Code Meaning

completed (HTTP 200) — BILLABLE Report delivered in result — consume it.

not_found (HTTP 200) — BILLABLE "No credit record found for this individual" — the bureau holds no file matching these details. Common for a thin-file or new-to-credit individual, and also what a name/PAN mismatch looks like. Definitive; do NOT retry. Billed the same as a successful pull, because the bureau was actually queried.

invalid_input (HTTP 200) — not billable "Invalid request details" — the request was rejected before the bureau was queried. Re-check the details with the customer; do NOT retry unchanged.

failed (HTTP 502) — not billable "Source down — please retry later." Temporary upstream issue and the ONLY retryable status; retry with exponential backoff (~2 s, max 3 tries). Free, because the bureau never answered.

401 / 403 Missing or invalid API key, or the key is not granted this API.

422 Validation failed — malformed mobile number, name or PAN, a missing required field, missing/incorrect consent_declaration, or a field outside the contract. Never retry unchanged.

429 Rate limited — respect the Retry-After header.

503 / 504 Gateway protecting itself, or the call exceeded the 30 s budget — retry.

Code	Meaning
`completed (HTTP 200) — BILLABLE`	Report delivered in result — consume it.
`not_found (HTTP 200) — BILLABLE`	"No credit record found for this individual" — the bureau holds no file matching these details. Common for a thin-file or new-to-credit individual, and also what a name/PAN mismatch looks like. Definitive; do NOT retry. Billed the same as a successful pull, because the bureau was actually queried.
`invalid_input (HTTP 200) — not billable`	"Invalid request details" — the request was rejected before the bureau was queried. Re-check the details with the customer; do NOT retry unchanged.
`failed (HTTP 502) — not billable`	"Source down — please retry later." Temporary upstream issue and the ONLY retryable status; retry with exponential backoff (~2 s, max 3 tries). Free, because the bureau never answered.
`401 / 403`	Missing or invalid API key, or the key is not granted this API.
`422`	Validation failed — malformed mobile number, name or PAN, a missing required field, missing/incorrect consent_declaration, or a field outside the contract. Never retry unchanged.
`429`	Rate limited — respect the Retry-After header.
`503 / 504`	Gateway protecting itself, or the call exceeded the 30 s budget — retry.

Changelog

2026-07-27 Initial release: credit bureau report by mobile number, full name and PAN, with a required consent attestation field, uniform response envelope, and no pending state (every response is final).