PAN Verification API
Popular
Confirm that a PAN is real, active and belongs to the customer in front of you. The check runs at capture, where a mismatch surfaces on the form while the customer can still fix it.
Overview
PAN verification confirms that a Permanent Account Number exists, is active, and belongs to the person or entity presenting it. Nearly every Indian financial workflow turns on a PAN at some point, because deduction, reporting and payout processes are keyed to it. An API check puts that confirmation inside your own form. Your application sends the PAN with the details you hold, and gets back a structured response it can act on. A mismatch shows on the page while the customer can still fix it, instead of surfacing in a batch weeks later. Basic, Advanced and Comprehensive coverage differ in how much of the record they show. Your service contract sets what each tier covers, and the fields that come back depend on the data source and the record.
- Category
- KYC Services
- Coverage
- PAN records available in India. Your service contract sets what each tier covers.
- Input
- A PAN, plus a customer-supplied name and date of birth where you need a match outcome
- Output
- PAN state, holder name, match outcome, and wider record details on the higher tiers. Fields vary by data source and record.
- Typical users
- Lenders and NBFCs, fintech and payment platforms, insurers, marketplaces, staffing and gig platforms, real estate
- Coverage note
- Limited to what the underlying record holds. The tier and the detail returned depend on 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 \
-H "X-Api-Key: $FINSOUR_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"input": {
"pan": "<pan>"
},
"options": {
"consent": {
"obtained": true,
"at": "2026-09-01T10:00:00Z",
"purpose": "kyc"
}
}
}'Node.js
const response = await fetch("https://gateway.staging.finsour.io/v1/identity/pan", {
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": true,
"at": "2026-09-01T10:00:00Z",
"purpose": "kyc"
}
}
}),
});
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",
headers={
"X-Api-Key": os.environ["FINSOUR_API_KEY"],
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"input": {
"pan": "<pan>",
},
"options": {
"consent": {
"obtained": True,
"at": "2026-09-01T10:00:00Z",
"purpose": "kyc",
},
},
},
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 | — | — |
data. | string or null | Always | — | — |
data. | string or null | Always | What the register says the PAN is for (for example PERSON), upper-cased as given (Release 1.1, C347). | — |
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 and NBFC: confirm an applicant PAN before a credit assessment
- Fintech and PSP: verify a merchant PAN before you enable payouts
- Insurance: confirm the proposer PAN on a new proposal
- Marketplaces: verify a seller PAN before the first payout cycle
- Staffing and gig platforms: check a worker PAN before deductions run
- Real estate: capture a verified PAN for a reportable transaction
What this service does
Goes further than a format check
Pattern validation catches a typo. It cannot tell you whether the PAN is active, or whether it belongs to the customer in front of you. That is the question this check answers.
Fields a PAN response can carry
The state of the PAN, the holder name held against it, and a match outcome for the details your customer gave you. Higher tiers can add the holder category, the Aadhaar linkage signal and wider record details. Which fields you get depends on the underlying data source and the record.
Corrections land while the customer is still there
A mismatch shown while the customer is on the form is a correction they make on the spot. The same mismatch found in a payout run becomes a support ticket, and your team then chases the stalled application and the reconciliation.
Three tiers on one integration
Basic, Advanced and Comprehensive coverage share the same workflow. A flow that starts with a state and name check can move to a fuller record later without being rebuilt around it.
How a check runs
Take the PAN and the consent
Capture the PAN in your own form alongside informed consent for the specific purpose, and keep the consent record joined to the request that follows it.
Send the PAN for verification
Submit the PAN, adding the customer-supplied name and date of birth where your flow needs a match outcome.
Read the state and the holder name
Your application receives the state of the PAN, the holder name, the match outcome and any further details your tier covers, all as structured fields.
Decide what happens next
Accept the identifier, show the customer a correctable mismatch while they are still on the page, or send an unresolved case to a reviewer. Give each outcome its own path.
Store the result with its timestamp
Save the outcome and the time of the check against the customer record. A later reviewer or auditor can then see what was verified and when. Re-check on events that change the record.
Questions
- What is a PAN verification API?
- An interface that lets you confirm a PAN inside your own application, instead of checking each one by hand. Your product sends the PAN and receives a structured response it can route on directly.
- What is the difference between the Basic, Advanced and Comprehensive PAN tiers?
- Basic confirms the PAN exists, reports its state and returns the holder name with a match outcome. Advanced adds the holder category, the Aadhaar linkage signal and further record details, and Comprehensive can show a registered address and contact details where available. Your service contract decides what each tier covers.
- Can I check that a PAN matches my customer's name?
- Yes. Send the customer-supplied name and date of birth with the PAN, and the response reports the outcome of the comparison. Your flow then acts on a match result instead of asking a person to compare two strings.
- Does the API show whether a PAN is linked to Aadhaar?
- The linkage signal comes with the Advanced and Comprehensive tiers, subject to your service contract and to what the underlying record holds. Treat it as a routing input the customer can resolve.
- Why check a PAN at capture instead of in a nightly batch?
- Because the person who can correct a mistyped or mismatched PAN is the customer still looking at the form. Found later, the same problem becomes a rejected payout, a deduction filed against an identifier that does not resolve, or a reconciliation your team has to chase.
- Do I need consent before I verify a PAN?
- Yes. A PAN is tied to a person's tax identity, which makes it sensitive personal information. Collect informed consent for the specific purpose before the check runs, keep that consent revocable, and hold what comes back only where you have a lawful reason.
Catalog entry last updated .