Credit Report (Experian)
creditConsumer credit report from Experian, pulled by mobile number with explicit borrower consent. SINGLE CALL — there is NO separate "send OTP" / OTP-initiation endpoint. The consent OTP is handled at YOUR end: send an OTP to the borrower’s registered mobile using your own OTP/SMS system, have them confirm it, then pass that same OTP here (in the `otp` field) as proof of consent. The OTP must be UNIQUE per request — reusing the same OTP for the same mobile is rejected as an invalid OTP. `device_type` and the internal name-lookup flag are set by API Sathi server-side, so you do not send them. Billed on SUCCESS only: a rejected OTP / device_ip / consent / timestamp returns a 4xx and is NOT charged. TIMING: bureau pulls are slow — typical 4-9s, p95 ~8.5s. Our upstream timeout is 15s, so set your client timeout to at least 20s. A client timeout below ~10s will surface as a failure on your side for calls we complete successfully. Timeouts are never charged.
POST /gw/v1/credit-report-v1/SLA p95: 9000 ms
Authentication
Pass your key in the X-API-Key header. Use a test_ key against the sandbox and a live_ key in production. Send an optional Idempotency-Key header to safely retry — the same key returns the same response for 24h.
X-API-Key: live_xxxxxxxxxxxx
Request
Endpoint: POST https://apisathi.in/gw/v1/credit-report-v1/
The trailing slash is required. /v1/credit-report-v1/ works; /v1/credit-report-v1 returns 404 Not Found. This applies to every product.
| Field | Type | Required | Constraints |
|---|---|---|---|
| otp | string | required | The consent OTP you generated + verified with the borrower at your end. Max 6 digits. Must be unique per request (a reused OTP for the same mobile is rejected). |
| device_ip | string | required | The borrower’s device IP (e.g. 203.0.113.10). Must be a valid IP. |
| last_name | string | required | Borrower last name |
| mobile_no | string | required | pattern: ^[6-9][0-9]{9}$ · Borrower mobile number (the one consent was taken on) |
| timestamp | string | required | Request time in DDMMYYYY-HH:MM:SS format, e.g. 24072026-14:30:00 |
| first_name | string | required | Borrower first name |
| consent_message | string | required | Consent text; MUST contain the words: I, authorize, Experian, credit, report. e.g. "I hereby authorize Experian to pull my credit report for loan eligibility purpose". |
| consent_acceptance | string | required | Must be "yes" — the borrower accepted consent. |
Code snippets
curl -X POST https://apisathi.in/gw/v1/credit-report-v1/ \
-H "X-API-Key: $API_SATHI_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"mobile_no":"9876543210","first_name":"Rahul","last_name":"Verma","consent_message":"I hereby authorize Experian to pull my credit report for loan eligibility purpose","consent_acceptance":"yes","otp":"534216","timestamp":"24072026-14:30:00","device_ip":"203.0.113.10"}'Response
| Field | Type | Required | Constraints |
|---|---|---|---|
| report | object | optional | — |
| message | string | optional | — |
| report_pdf | string | optional | — |
| report_xml | string | optional | — |
Sample response
{
"report": {},
"message": "sample",
"report_pdf": "sample",
"report_xml": "sample"
}Reading a 400
A schema rejection returns INVALID_REQUEST with a details array naming the exact field. Read it before guessing — it gives you the JSON path and what was wrong with it.
{
"error": {
"code": "INVALID_REQUEST",
"message": "Request body failed schema validation",
"details": [
{ "path": "/callback_url",
"message": "unexpected property 'callback_url' — this endpoint does not accept unknown fields" }
]
}
}Most endpoints reject unknown top-level fields outright, so an extra key you added for your own bookkeeping will fail the call. Enum errors list the accepted values, and a missing required field is named with its full path.
Error codes
| Code | HTTP | When |
|---|---|---|
| INVALID_INPUT | 422 | The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again. |
| INVALID_API_KEY | 401 | Missing, malformed, or revoked X-API-Key. |
| OUT_OF_SCOPE | 403 | API key is not scoped for this product. |
| INSUFFICIENT_BALANCE | 402 | Wallet balance is below the per-call sale price. Recharge and retry. |
| RATE_LIMITED | 429 | Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header. |
| PRODUCT_DEPRECATED | 410 | This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent. |
| ROUTER_NO_VENDOR | 503 | No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged. |
| VENDOR_AUTH_FAILED | 502 | Upstream vendor rejected our credentials (our config issue). Not charged. |
| VENDOR_ERROR | 502 | A genuine transient upstream error (the source was briefly unavailable). Safe to RETRY after a short backoff. Not charged. NOTE: this is NOT for bad input — invalid values return 422 INVALID_INPUT, not 502. |
| TIMEOUT | 504 | Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged. |
| result_code 101 — match found | 200 | The record was found. `verified: true`. Charged. |
| result_code 102 — invalid input | 200 | The source rejected the identifier as invalid. `verified: false`. Charged — the source billed us for the lookup. Do not retry the same value. |
| result_code 103 — no record found | 200 | The lookup ran and matched nothing. `verified: false`. Charged. This is a definitive answer, NOT an outage — do not retry. |
| result_code 106 — multiple records | 200 | More than one record matched. `verified: false`. Charged. Narrow the input to disambiguate. |
| result_code 104 / 105 — source failure | 502 | The upstream source failed or returned something unreadable. Returned as VENDOR_ERROR and NOT charged. This is the only case worth retrying, with backoff. |
OpenAPI 3.1
Generated from this product's request/response JSON Schemas.
{
"openapi": "3.1.0",
"info": {
"title": "API Sathi — Credit Report (Experian)",
"version": "1.0.0",
"description": "Consumer credit report from Experian, pulled by mobile number with explicit borrower consent.\n\nSINGLE CALL — there is NO separate \"send OTP\" / OTP-initiation endpoint. The consent OTP is handled at YOUR end: send an OTP to the borrower’s registered mobile using your own OTP/SMS system, have them confirm it, then pass that same OTP here (in the `otp` field) as proof of consent. The OTP must be UNIQUE per request — reusing the same OTP for the same mobile is rejected as an invalid OTP.\n\n`device_type` and the internal name-lookup flag are set by API Sathi server-side, so you do not send them. Billed on SUCCESS only: a rejected OTP / device_ip / consent / timestamp returns a 4xx and is NOT charged. \n\nTIMING: bureau pulls are slow — typical 4-9s, p95 ~8.5s. Our upstream timeout is 15s, so set your client timeout to at least 20s. A client timeout below ~10s will surface as a failure on your side for calls we complete successfully. Timeouts are never charged."
},
"servers": [
{
"url": "https://apisathi.in/gw/v1"
}
],
"components": {
"securitySchemes": {
"ApiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
"description": "Your live or test key, e.g. `live_xxxxxxxxxxxx`."
}
}
},
"paths": {
"/credit-report-v1": {
"post": {
"operationId": "creditReportV1",
"tags": [
"credit"
],
"summary": "Credit Report (Experian)",
"description": "Consumer credit report from Experian, pulled by mobile number with explicit borrower consent.\n\nSINGLE CALL — there is NO separate \"send OTP\" / OTP-initiation endpoint. The consent OTP is handled at YOUR end: send an OTP to the borrower’s registered mobile using your own OTP/SMS system, have them confirm it, then pass that same OTP here (in the `otp` field) as proof of consent. The OTP must be UNIQUE per request — reusing the same OTP for the same mobile is rejected as an invalid OTP.\n\n`device_type` and the internal name-lookup flag are set by API Sathi server-side, so you do not send them. Billed on SUCCESS only: a rejected OTP / device_ip / consent / timestamp returns a 4xx and is NOT charged. \n\nTIMING: bureau pulls are slow — typical 4-9s, p95 ~8.5s. Our upstream timeout is 15s, so set your client timeout to at least 20s. A client timeout below ~10s will surface as a failure on your side for calls we complete successfully. Timeouts are never charged.",
"security": [
{
"ApiKeyAuth": []
}
],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Optional. Same key returns the same response for 24h."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"mobile_no",
"first_name",
"last_name",
"consent_message",
"consent_acceptance",
"otp",
"timestamp",
"device_ip"
],
"properties": {
"otp": {
"type": "string",
"description": "The consent OTP you generated + verified with the borrower at your end. Max 6 digits. Must be unique per request (a reused OTP for the same mobile is rejected)."
},
"device_ip": {
"type": "string",
"description": "The borrower’s device IP (e.g. 203.0.113.10). Must be a valid IP."
},
"last_name": {
"type": "string",
"description": "Borrower last name"
},
"mobile_no": {
"type": "string",
"pattern": "^[6-9][0-9]{9}$",
"description": "Borrower mobile number (the one consent was taken on)"
},
"timestamp": {
"type": "string",
"description": "Request time in DDMMYYYY-HH:MM:SS format, e.g. 24072026-14:30:00"
},
"first_name": {
"type": "string",
"description": "Borrower first name"
},
"consent_message": {
"type": "string",
"description": "Consent text; MUST contain the words: I, authorize, Experian, credit, report. e.g. \"I hereby authorize Experian to pull my credit report for loan eligibility purpose\"."
},
"consent_acceptance": {
"enum": [
"yes",
"no"
],
"type": "string",
"description": "Must be \"yes\" — the borrower accepted consent."
}
},
"additionalProperties": false
},
"example": {
"mobile_no": "9876543210",
"first_name": "Rahul",
"last_name": "Verma",
"consent_message": "I hereby authorize Experian to pull my credit report for loan eligibility purpose",
"consent_acceptance": "yes",
"otp": "534216",
"timestamp": "24072026-14:30:00",
"device_ip": "203.0.113.10"
}
}
}
},
"responses": {
"200": {
"description": "Successful, normalized response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"report": {
"type": "object"
},
"message": {
"type": "string"
},
"report_pdf": {
"type": "string"
},
"report_xml": {
"type": "string"
}
}
},
"example": {
"report": {},
"message": "sample",
"report_pdf": "sample",
"report_xml": "sample"
}
}
}
},
"401": {
"description": "Missing, malformed, or revoked X-API-Key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"call_id": {
"type": "string"
}
}
}
}
}
}
}
},
"402": {
"description": "Wallet balance is below the per-call sale price. Recharge and retry.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"call_id": {
"type": "string"
}
}
}
}
}
}
}
},
"403": {
"description": "API key is not scoped for this product.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"call_id": {
"type": "string"
}
}
}
}
}
}
}
},
"410": {
"description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"call_id": {
"type": "string"
}
}
}
}
}
}
}
},
"422": {
"description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"call_id": {
"type": "string"
}
}
}
}
}
}
}
},
"429": {
"description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"call_id": {
"type": "string"
}
}
}
}
}
}
}
},
"502": {
"description": "Upstream vendor rejected our credentials (our config issue). Not charged.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"call_id": {
"type": "string"
}
}
}
}
}
}
}
},
"503": {
"description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"call_id": {
"type": "string"
}
}
}
}
}
}
}
},
"504": {
"description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"call_id": {
"type": "string"
}
}
}
}
}
}
}
}
}
}
}
}
}