Skip to content

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

POSThttps://gateway.staging.finsour.io/v1/identity/pan

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

Scheme API key travels in the X-Api-Key header

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

Content type application/json

Headers

NameTypeRequiredDescriptionConstraints
Idempotency-KeystringRequiredA 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

NameTypeRequiredDescriptionConstraints
inputobjectRequiredThe details to check.—
input.panstringRequired—Matches ^[A-Z]{5}[0-9]{4}[A-Z]$. Exactly 10 characters
input.nameToMatchstringOptionalOPTIONAL (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
optionsobjectRequiredSettings for this call. This API requires consent.—
options.referencestringOptionalYour own reference for this call. It comes back unchanged as meta.reference.1 to 128 characters
options.consentobjectRequiredThe person's consent to this check.—
options.consent.obtainedbooleanRequiredSend true once the person has agreed to the check.Always true
options.consent.atstring (date-time)RequiredWhen the person gave consent.—
options.consent.purposestringRequiredWhat 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

Status 200 · content type application/json

NameTypePresentDescriptionConstraints
dataobjectAlwaysThe result of the check.—
data.foundbooleanAlways——
data.panstringAlways—Matches ^[A-Z]{5}[0-9]{4}[A-Z]$. Exactly 10 characters
data.maskedPanstringSometimesThe 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.namestring or nullAlways——
data.statusstring or nullAlways——
data.typestring or nullAlwaysWhat the register says the PAN is for (for example PERSON), upper-cased as given (Release 1.1, C347).—
data.nameMatchScorenumber or nullAlwaysHow 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.sourceobjectAlways——
data.source.fetchedAtstringAlwaysWhen 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

CodeStatusMeaningRetrying
API_VERSION_UNSUPPORTED400That API version is no longer supported.Do not retry automatically
IDEMPOTENCY_KEY_INVALID400That Idempotency-Key does not meet the required format.Do not retry automatically
IDEMPOTENCY_KEY_REQUIRED400An Idempotency-Key header is required for this request.Do not retry automatically
REQUEST_MALFORMED400The request could not be parsed.Do not retry automatically
AUTH_KEY_EXPIRED401The API key is not valid.Do not retry automatically
AUTH_KEY_INVALID401The API key is not valid.Do not retry automatically
AUTH_KEY_MISSING401No API key was presented.Do not retry automatically
AUTH_KEY_REVOKED401The API key is not valid.Do not retry automatically
INSUFFICIENT_BALANCE402The available balance is not enough for this request.Do not retry automatically
AUTH_IP_NOT_ALLOWED403This API key may not be used from this address.Do not retry automatically
ENTITLEMENT_MISSING403This organization is not entitled to that product in this environment.Do not retry automatically
ORGANIZATION_SUSPENDED403This organization is not active.Do not retry automatically
PRODUCT_NOT_AVAILABLE403That product is not available.Do not retry automatically
PRODUCT_RETIRED403That product has been withdrawn.Do not retry automatically
SCOPE_INSUFFICIENT403This API key does not carry the scope this product requires.Do not retry automatically
PRODUCT_NOT_FOUND404No such product.Do not retry automatically
IDEMPOTENCY_KEY_REUSED409That idempotency key was already used for a different request.Do not retry automatically
PRICE_UNAVAILABLE409No active price covers this product right now.Safe to retry
REQUEST_IN_PROGRESS409An earlier attempt with this key is still running.Safe to retry
SETTLEMENT_PENDING409This request is awaiting reconciliation by an operator.Do not retry automatically
API_VERSION_SUNSET410That API version passed its announced sunset date.Do not retry automatically
REQUEST_TOO_LARGE413The request body is too large.Do not retry automatically
UNSUPPORTED_MEDIA_TYPE415That content type is not accepted on this route.Do not retry automatically
CONSENT_REQUIRED422This product requires an explicit consent flag.Do not retry automatically
SANDBOX_FIXTURE_MISSING422No sandbox fixture exists for this input. Use a different test value.Do not retry automatically
UPSTREAM_REJECTED422The upstream source rejected the input.Do not retry automatically
VALIDATION_FAILED422The request payload is invalid.Do not retry automatically
CONCURRENCY_LIMIT429Too many simultaneous requests.Safe to retry
QUOTA_EXCEEDED429The allowance for this window is spent.Do not retry automatically
RATE_LIMITED429Too many requests.Safe to retry
INTERNAL_ERROR500An unexpected error occurred.Safe to retry
OUTCOME_UNCERTAIN502The outcome of this request is not yet known. Retry with the same Idempotency-Key.Do not retry automatically
UPSTREAM_UNAVAILABLE502The upstream source is unavailable. Retry shortly.Safe to retry
MAINTENANCE_MODE503The service is in a maintenance window.Safe to retry
NO_PROVIDER_AVAILABLE503No provider can serve this product right now.Safe to retry
SERVICE_OVERLOADED503The service is shedding load. Retry shortly.Safe to retry
UPSTREAM_TIMEOUT504The 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

ScopeLimitWindowAt the limit
Your API key, within your organisation's limitThe figure in X-RateLimit-LimitPer minute429 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

  1. 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.

  2. Send the PAN for verification

    Submit the PAN, adding the customer-supplied name and date of birth where your flow needs a match outcome.

  3. 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.

  4. 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.

  5. 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 .