PAN Advance API
New
Check a PAN's status with the name printed on the card, when the record last changed and whether it is linked to Aadhaar, before you rely on it for tax or lending.
Overview
A PAN can be valid in format and still be the wrong one to rely on. It may be inactive, it may not be linked to the holder's Aadhaar, or the name on it may not be the name your customer gave you. Lenders, payment platforms and payroll teams need those answers before a PAN goes onto a loan file, a payout account or a tax deduction. A photo of the card says none of them. Your application sends the PAN, and optionally the name you hold, and gets back the record's status, the holder's name and the name printed on the card, when the record was last updated, its Aadhaar link status and a name-match score, as structured data.
- Category
- KYC Services
- Coverage
- PANs issued in India. Your service contract sets what each check covers.
- Input
- PAN, plus the name you hold for a name-match score
- Output
- Status, holder type, holder name and name on card, last update date, Aadhaar link status, name-match score
- Typical users
- Lenders and NBFCs, fintech and payment platforms, payroll teams, insurers and brokerages
- Coverage note
- Limited to what the underlying record holds. Fields depend on the data source and your service contract.
The overview and the sections after the reference are the FinSour API catalog’s own record for this service, rendered unaltered.
Endpoint URL and method
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Authentication
Send your API key in this header on every call, from your own server: a key sent from a browser is refused. A key starting fs_test_ calls the sandbox and one starting fs_live_ calls production, at the same address. Create keys in the FinSour console.
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Request parameters
Headers
| Name | Type | Required | Description | Constraints |
|---|---|---|---|---|
Idempotency-Key | string | Required | A key you generate for each attempt. Sending the same key again returns the first answer instead of running the check twice; the same key with a different body is refused. | 8 to 255 characters. Matches ^[A-Za-z0-9._:-]+$ |
Body
| Name | Type | Required | Description | Constraints |
|---|---|---|---|---|
input | object | Required | The details to check. | — |
input. | string | Required | — | Matches ^[A-Z]{5}[0-9]{4}[A-Z]$. Exactly 10 characters |
input. | string | Optional | OPTIONAL (Release 1.1): a name to compare with the record's; the answer's nameMatchScore is the comparison. | Matches ^(?=.*[A-Za-z])[A-Za-z .'-]+$. 1 to 120 characters |
options | object | Required | Settings for this call. This API requires consent. | — |
options. | string | Optional | Your own reference for this call. It comes back unchanged as meta.reference. | 1 to 128 characters |
options. | object | Required | The person's consent to this check. | — |
options. | boolean | Required | Send true once the person has agreed to the check. | Always true |
options. | string (date-time) | Required | When the person gave consent. | — |
options. | string | Required | What the check is for, for example kyc. | 1 to 64 characters |
Request samples
cURL
curl -X POST https://gateway.staging.finsour.io/v1/identity/pan-advance \
-H "X-Api-Key: $FINSOUR_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"input": {
"pan": "<pan>"
},
"options": {
"consent": {
"obtained": "<obtained>",
"at": "<at>",
"purpose": "<purpose>"
}
}
}'Node.js
const response = await fetch("https://gateway.staging.finsour.io/v1/identity/pan-advance", {
method: "POST",
headers: {
"X-Api-Key": process.env.FINSOUR_API_KEY,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json",
},
body: JSON.stringify({
"input": {
"pan": "<pan>"
},
"options": {
"consent": {
"obtained": "<obtained>",
"at": "<at>",
"purpose": "<purpose>"
}
}
}),
});
console.log(response.status, await response.json());Python
import os
import uuid
import requests
response = requests.post(
"https://gateway.staging.finsour.io/v1/identity/pan-advance",
headers={
"X-Api-Key": os.environ["FINSOUR_API_KEY"],
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"input": {
"pan": "<pan>",
},
"options": {
"consent": {
"obtained": "<obtained>",
"at": "<at>",
"purpose": "<purpose>",
},
},
},
timeout=30,
)
print(response.status_code, response.json())Generated from the fields above. Replace each value in angle brackets with your own; the key is read from FINSOUR_API_KEY.
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Response schema
| Name | Type | Present | Description | Constraints |
|---|---|---|---|---|
data | object | Always | The result of the check. | — |
data. | boolean | Always | — | — |
data. | string | Always | — | Matches ^[A-Z]{5}[0-9]{4}[A-Z]$. Exactly 10 characters |
data. | string | Sometimes | The PAN in its display form — the first three and last two characters kept — from FinSour-Version 2026-11-01 (absent before it). Beside the full pan for one release; the full field is removed in the next version. | Matches ^[A-Z]{3}X{5}[0-9][A-Z]$ |
data. | string or null | Always | What the register says the PAN is for (for example PERSON), upper-cased as given; the vocabulary is undocumented. | — |
data. | string or null | Always | The holder's name as the register holds it. | — |
data. | string or null | Always | The name as the card prints it. | — |
data. | string or null | Always | The register's status word for the PAN (for example VALID), upper-cased as given. | — |
data. | string or any or null | Always | When the register last updated the PAN record. | — |
data. | string or null | Always | The register's word for the PAN's standing on the link with Aadhaar (for example OPERATIVE PAN), upper-cased as given. | — |
data. | string or null | Always | The title the register records (for example Kumari, Shri), as given (Release 1.1). | — |
data. | string or null | Always | The register's first, middle and last names, as it splits them (Release 1.1). | — |
data. | string or null | Always | — | — |
data. | string or null | Always | — | — |
data. | number or null | Always | How closely nameToMatch matches the name the record holds, 0 to 100, to two decimals; null when no name was sent. | Minimum 0. Maximum 100 |
data. | object | Always | — | — |
data. | string | Always | When the answer was fetched: RFC 3339 UTC with a Z, never an epoch or an IST offset. | Matches ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?Z$ |
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Error codes
| Code | Status | Meaning | Retrying |
|---|---|---|---|
API_VERSION_UNSUPPORTED | 400 | That API version is no longer supported. | Do not retry automatically |
IDEMPOTENCY_KEY_INVALID | 400 | That Idempotency-Key does not meet the required format. | Do not retry automatically |
IDEMPOTENCY_KEY_REQUIRED | 400 | An Idempotency-Key header is required for this request. | Do not retry automatically |
REQUEST_MALFORMED | 400 | The request could not be parsed. | Do not retry automatically |
AUTH_KEY_EXPIRED | 401 | The API key is not valid. | Do not retry automatically |
AUTH_KEY_INVALID | 401 | The API key is not valid. | Do not retry automatically |
AUTH_KEY_MISSING | 401 | No API key was presented. | Do not retry automatically |
AUTH_KEY_REVOKED | 401 | The API key is not valid. | Do not retry automatically |
INSUFFICIENT_BALANCE | 402 | The available balance is not enough for this request. | Do not retry automatically |
AUTH_IP_NOT_ALLOWED | 403 | This API key may not be used from this address. | Do not retry automatically |
ENTITLEMENT_MISSING | 403 | This organization is not entitled to that product in this environment. | Do not retry automatically |
ORGANIZATION_SUSPENDED | 403 | This organization is not active. | Do not retry automatically |
PRODUCT_NOT_AVAILABLE | 403 | That product is not available. | Do not retry automatically |
PRODUCT_RETIRED | 403 | That product has been withdrawn. | Do not retry automatically |
SCOPE_INSUFFICIENT | 403 | This API key does not carry the scope this product requires. | Do not retry automatically |
PRODUCT_NOT_FOUND | 404 | No such product. | Do not retry automatically |
IDEMPOTENCY_KEY_REUSED | 409 | That idempotency key was already used for a different request. | Do not retry automatically |
PRICE_UNAVAILABLE | 409 | No active price covers this product right now. | Safe to retry |
REQUEST_IN_PROGRESS | 409 | An earlier attempt with this key is still running. | Safe to retry |
SETTLEMENT_PENDING | 409 | This request is awaiting reconciliation by an operator. | Do not retry automatically |
API_VERSION_SUNSET | 410 | That API version passed its announced sunset date. | Do not retry automatically |
REQUEST_TOO_LARGE | 413 | The request body is too large. | Do not retry automatically |
UNSUPPORTED_MEDIA_TYPE | 415 | That content type is not accepted on this route. | Do not retry automatically |
CONSENT_REQUIRED | 422 | This product requires an explicit consent flag. | Do not retry automatically |
SANDBOX_FIXTURE_MISSING | 422 | No sandbox fixture exists for this input. Use a different test value. | Do not retry automatically |
UPSTREAM_REJECTED | 422 | The upstream source rejected the input. | Do not retry automatically |
VALIDATION_FAILED | 422 | The request payload is invalid. | Do not retry automatically |
CONCURRENCY_LIMIT | 429 | Too many simultaneous requests. | Safe to retry |
QUOTA_EXCEEDED | 429 | The allowance for this window is spent. | Do not retry automatically |
RATE_LIMITED | 429 | Too many requests. | Safe to retry |
INTERNAL_ERROR | 500 | An unexpected error occurred. | Safe to retry |
OUTCOME_UNCERTAIN | 502 | The outcome of this request is not yet known. Retry with the same Idempotency-Key. | Do not retry automatically |
UPSTREAM_UNAVAILABLE | 502 | The upstream source is unavailable. Retry shortly. | Safe to retry |
MAINTENANCE_MODE | 503 | The service is in a maintenance window. | Safe to retry |
NO_PROVIDER_AVAILABLE | 503 | No provider can serve this product right now. | Safe to retry |
SERVICE_OVERLOADED | 503 | The service is shedding load. Retry shortly. | Safe to retry |
UPSTREAM_TIMEOUT | 504 | The upstream source did not respond in time. | Safe to retry |
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Rate limits
| Scope | Limit | Window | At the limit |
|---|---|---|---|
| Your API key, within your organisation's limit | The figure in X-RateLimit-Limit | Per minute | 429 RATE_LIMITED, with Retry-After in seconds. Every answer past authentication carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. |
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Use cases
- Lending: confirming a borrower's PAN is active and Aadhaar-linked before underwriting
- Payments: checking the PAN on a merchant or payout account
- Payroll: confirming an employee's PAN before tax is deducted against it
- Insurance and broking: matching the PAN name with the proposal or account name
What this service does
Status, name and Aadhaar link in one answer
The PAN's status, the holder's name and the name printed on the card, the date the record last changed and whether it is linked to Aadhaar, where the record holds them.
A name-match score
Send the name the customer gave you with the PAN, and the response scores how closely it matches the record, so your rules can route a weak match to review.
Only the PAN is required
The request needs the PAN and nothing else. There is no card image to collect or read.
Consent recorded with the request
The check names a person to the data source, so it runs with the holder's consent for a stated purpose, recorded with the request.
How a check runs
Arrange access
Tell us where PAN checks fit in your onboarding or payroll process. We arrange access for your organization under the applicable service contract.
Collect the PAN and the holder's consent
Your form collects the PAN, the name the customer gives, and their consent for the stated purpose.
Send the PAN
Your application sends the PAN, with the name if you want a match score.
Read the record
Your application receives the status, names, last update date, Aadhaar link status and match score as structured data.
Accept, ask or review
Accept the PAN, ask the customer to correct it, or send the case to a reviewer, and store the result with the decision.
Questions
- What do I send for a PAN Advance check?
- The PAN. Add the name the customer gave you if you want a name-match score in the response.
- How is PAN Advance different from PAN Verification and PAN Profile?
- PAN Verification confirms a PAN and its holder name. PAN Advance adds the name printed on the card, when the record last changed, the Aadhaar link status and a name-match score. PAN Profile reads the wider profile, such as date of birth, gender, address and contact details.
- Does PAN Advance tell me if a PAN is linked to Aadhaar?
- Yes, where the record states it. A PAN that is not linked to Aadhaar can be treated as inoperative for tax purposes, so it is worth flagging before you rely on it.
- Do I need the holder's consent?
- Yes. The check names a person to the data source, so run it with the PAN holder's consent for a stated purpose and record that consent with the request.
- What does the name-match score mean?
- It shows how closely the name you sent matches the name on the record. Use a threshold that suits your risk, and send weak matches to a reviewer rather than refusing them automatically.
- How do I get access to the PAN Advance API?
- Start with Get API and tell us how PAN checks fit your process and what volumes you expect. We set up access under the applicable service contract.
Catalog entry last updated .