Skip to content

PAN Profile API

New

Read the profile held against a PAN, from date of birth and gender to address and Aadhaar link, to prefill and cross-check an onboarding form.

Overview

Behind every PAN is a profile: the holder's name, date of birth, gender, address and whether the PAN is linked to Aadhaar. Onboarding teams use that profile in two ways. It can prefill a form, so a customer confirms details instead of typing them. And it can cross-check what a customer typed, so a mismatch is caught before an account is opened. Your application sends the PAN, with the holder's consent, and gets back the profile the record holds as structured data. Which fields come back depends on the data source, the record and the service contract you select.

Category
KYC Services
Coverage
PANs issued in India. Fields depend on the record and your service contract.
Input
PAN, plus the name you hold for a name-match score
Output
Name and its parts, holder type, date of birth, gender, address, Aadhaar link and last four digits, email, mobile
Typical users
Lenders and NBFCs, fintech platforms, insurers, brokerages and wealth platforms
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

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

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-profile \
  -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-profile", {
  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-profile",
    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

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.typestring or nullAlwaysWhat the register says the PAN is for (for example PERSON), upper-cased as given; the vocabulary is undocumented.—
data.namestring or nullAlwaysThe holder's name.—
data.dateOfBirthstring or any or nullAlways——
data.genderstring or any or nullAlways——
data.addressobject or any or nullAlways——
data.maskedAadhaarNumberstring or any or nullAlwaysThe last four digits of the holder's Aadhaar number and nothing else of it.—
data.aadhaarLinkedboolean or nullAlwaysWhether the PAN is linked to the holder's Aadhaar; null when the record does not say.—
data.emailstring or any or nullAlwaysThe e-mail address the PAN record holds (Release 1.1). Returned live and never stored.—
data.phonestring or any or nullAlwaysThe ten-digit mobile number the PAN record holds (Release 1.1). Returned live and never stored.—
data.namePartsarray of stringsAlwaysThe holder's name as the register splits it, in its order; [] when it does not (Release 1.1).—
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: prefilling a loan application from the PAN profile
  • Insurance: cross-checking proposer details before a policy is issued
  • Broking and wealth: completing account-opening forms with fewer errors
  • Fintech onboarding: comparing a typed address with the PAN record

What this service does

  • The profile behind the PAN

    The holder's name and its parts, date of birth, gender, address, Aadhaar link status and the contact details the record holds, where it holds them.

  • Aadhaar shown as the last four digits only

    When the PAN is linked to Aadhaar, the response shows only the last four digits of the Aadhaar number, never the whole number.

  • Prefill and cross-check in one call

    Use the same answer to fill a form for the customer to confirm and to compare with what they typed.

  • A name-match score

    Send the name the customer gave you and the response scores it against the record.

How a check runs

  1. Arrange access

    Tell us where the PAN profile fits in your onboarding. We arrange access for your organization under the applicable service contract.

  2. Collect the PAN and the holder's consent

    Your form collects the PAN and the customer's consent to read their profile for the stated purpose.

  3. Send the PAN

    Your application sends the PAN, with the customer's name if you want a match score.

  4. Read the profile

    Your application receives the profile fields the record holds as structured data.

  5. Prefill, confirm and store

    Prefill or compare the form, let the customer confirm, and store only the fields your process needs.

Questions

What do I send to read a PAN profile?
The PAN, with the holder's consent. Add the name the customer gave you if you want a name-match score.
What fields can the PAN profile return?
The holder's name and its parts, the holder category, date of birth, gender, address, whether the PAN is linked to Aadhaar with the last four digits of the Aadhaar number, and the email address and mobile number the record holds. Fields depend on the record and your service contract.
Does the response include the Aadhaar number?
Only its last four digits, when the PAN is linked. The full Aadhaar number is never returned.
Do I need the customer's consent?
Yes. A PAN profile is personal data, so read it only with the holder's consent for a stated purpose, record that consent, and keep only the fields your process needs.
Should I use PAN Profile, PAN Advance or PAN Verification?
Use PAN Verification or PAN Advance when you need to know the PAN is valid, active and belongs to your customer. Use PAN Profile when you also want the person's details to prefill or cross-check a form.
How do I get access to the PAN Profile API?
Start with Get API and tell us how the PAN profile fits your onboarding and what volumes you expect. We set up access under the applicable service contract.

Catalog entry last updated .