KYC API for NBFC Loan Origination: A Lifecycle Guide

Key takeaways

• Think in lifecycle stages, not in endpoints: login, credit, pre-disbursal, post-disbursal refresh. Each stage buys different checks and each check has one decision attached to it.
• PAN at login, bank account just before disbursal, and entity registries (GSTIN, CIN, Udyam) at credit for business loans is a sound default order. Vehicle RC belongs to vehicle-backed products only.
• Every verification is a synchronous POST /v1/verify/<product> call. A negative answer is a completed and billable call, so a retry buys the same answer twice.
• Treat name-match output as a score you set thresholds on, with a human band in the middle. Never auto-reject on a single low score.
• You build your own queues, status updates and deduplication. Verification calls do not push webhooks, and referenceId is a transaction id, not an idempotency key.
• A typical two-product personal-loan file costs a few rupees at the published per-call rates, and the per-file arithmetic is shown below so you can swap in your own funnel.
• Retention and consent rules for loan records come from your regulator, your policy and your counsel. The storage guidance here is general.

Who this page is for, and what problem it solves

This page is written for three readers on the same team. The credit-operations head who owns turnaround time and error rates. The product manager who owns the borrower journey and the drop-off between "application started" and "loan disbursed". And the engineer who has to wire verification into a loan management system without turning every borrower mistake into a support ticket.

The problem is easy to state. A loan file carries many identifiers typed by humans: PAN, account number, IFSC, GSTIN, vehicle number. Each one can be mistyped, outdated, or deliberately wrong. Checking them by eye or by uploaded screenshot is slow, inconsistent between analysts and hard to audit. Checking them through an API makes the check fast and repeatable, and gives you a transaction id per check that you can attach to the file. What the API cannot do is decide whether the borrower is acceptable; it can only tell you what the source says about the identifier you sent.

How this differs from the fintech KYC guide

The fintech and NBFC guide is organised around the checks and how to sequence, retry and queue them. This page is organised around the loan itself: what each stage of origination needs, how a vehicle loan differs from an MSME loan, how partner-sourced files change the picture, and how to run the desk that works the exceptions. Read the other page for engineering patterns, and this one for the credit-operations design.

What RBI's KYC framework means for the design, in general terms

NBFCs are regulated by the Reserve Bank of India, and RBI's Know Your Customer Direction (issued in 2016 and updated since) is the instrument most lenders point to when they talk about KYC. In broad terms it expects a regulated entity to have a board-approved customer acceptance and identification policy, to categorise customers by risk, to identify and verify customers using prescribed methods, to monitor accounts, and to keep records. We are not going to summarise its clauses, because the current text and its amendments, not a vendor's summary, are what you answer to. Read it directly and ask your compliance officer which parts apply to which of your products.

What that means for an engineer is practical rather than legal. First, your system should be able to show, per customer, which checks ran, when, with what input and with what outcome. Second, the outcome of an API check should feed your policy, not replace it: the policy says which evidence is enough for which risk category, and the code implements the policy. Third, anything that touches identity beyond a registry lookup, such as live interviews or face matching, is outside what these endpoints do.

StampMitra does not claim any regulatory approval, and using these APIs does not make a lender compliant. It supplies data points with a transaction id. How those data points count under your policy is your decision.

Map the loan lifecycle to verification calls

Start with a table that your credit head, product manager and engineer can all point at. It lists the stage, the question, the call and the decision it drives.

Two details matter in practice. The stages are cumulative in cost, so the cheapest decisive call goes first and the application should fall out of the paid path as early as it can. And the "refresh" stage is a policy decision with a cost, not a technical default: re-running everything quarterly will cost more than it reveals.

Journey by loan product

A single "KYC flow" for all products is how teams end up paying for checks that cannot change the decision. Build one short journey per product and share the components.

Two-wheeler and other vehicle-backed loans

The collateral is a registered vehicle, so the RC check matters. Run PAN at login. At credit, call verify/rc with the vehicle number and compare the returned ownerName with what your product expects: for a new vehicle financed at the dealership the registration may not exist yet, and for a used vehicle the owner is often the seller, not the borrower. Read rcStatus, registrationStatus, rcExpiryDate and insuranceUpto and write the policy answer for each: an expired insurance date on a used vehicle might be a documentation condition, while a status other than active might be a stop. Run the bank-account check at pre-disbursal.

The RC endpoint sits in the premium price band and, like the driving-licence and passport endpoints, is a sensitive scope: expect to run it from an IP-allowlisted production key.

Salaried personal loans

This is the cheapest journey: PAN with name at login, bank-account with name just before disbursal. Employer and income verification are not registry lookups on this platform and live in your own underwriting. The only subtlety is that the name the applicant types on the form, the name on PAN and the name at the bank can all differ legitimately. Plan for that with thresholds and a review band rather than exact string equality.

MSME working-capital and business loans

Here the borrower is an entity. Which identifier you start from depends on the entity type. A company has a CIN, so verify/cin returns the company name, incorporation date, cinStatus, companyStatus and a list of directors with their DIN and designation. A GST-registered firm has a GSTIN, so verify/gstin returns legalName, tradeName, registrationStatus and the principal place of business. A micro or small enterprise may hold a Udyam number, and verify/udyam returns whether it was found, its status, the enterprise type and its organisation type. A proprietor can be resolved through the PAN: pan-to-gstin and pan-to-udyam list the registrations linked to a PAN, which is useful when the applicant gives you one number and you want to know what else exists. Then verify each signatory or guarantor as an individual, with PAN and bank.

Use the business verification guide for what each identifier proves and why none of them replaces the others.

Partner-sourced and co-lending files

When a file arrives from a sourcing partner, a DSA or a co-lender, you inherit their inputs but not their evidence. Decide in policy whether you re-run the checks on arrival or accept the partner's attached results. If you re-run, treat the partner's data as the "typed" value and your own call as the verification. If you accept their results, store the partner's reference next to yours and mark the origin of each check, so that an auditor can see which checks you ran yourself.

The workflow, step by step

The numbered sequence below is a reasonable default for a retail or MSME desk. Adapt the order to your policy. Each step names the endpoint and the decision.

1. Normalise and validate formats locally. Upper-case and trim the PAN, IFSC, GSTIN and vehicle number, and check the pattern: ten characters for PAN, eleven for IFSC, fifteen for GSTIN, nine to eighteen digits for an account number. The endpoints reject malformed input with a 400, but a call that never leaves your servers costs nothing and answers faster. Decision: ask the applicant to correct the field, or continue.
2. Verify PAN with the applicant's name. POST /v1/verify/pan with pan and name. Read valid, panStatus, type, registeredName, nameMatchResult and nameMatchScore. Decision: hard stop on valid: false after one re-entry opportunity; continue on a strong match; park a middling score for review. Check that type fits the product: an individual loan with a company PAN is a data problem worth a human look.
3. Branch by borrower type. Individuals continue to step 5. Entities go to step 4.
4. Verify the entity. cin, gstin or udyam as applicable, then pan-to-gstin or pan-to-udyam to cross-check the PAN against registrations. Read the status fields (cinStatus, companyStatus, registrationStatus, udyamStatus) and compare names. Decision: proceed only when the entity is active and the names are explainable; otherwise ask for the document set your policy specifies.
5. Vehicle-backed loans: verify the RC. verify/rc with vehicleNumber. Decision: owner and status checks against your product rules.
6. Credit decision. Not an API step. Your underwriting uses the evidence from steps 2 to 5 and whatever else your policy requires.
7. Pre-disbursal: verify the account. POST /v1/verify/bank-account with accountNumber, ifsc and name. Read valid, accountStatus, nameAtBank and nameMatchResult. Decision: release, hold or request alternative proof.
8. Write the evidence record. For each call store the product, referenceId, the time, the inputs you hashed or masked, the key fields of the response and the decision taken. This is what lets you reconstruct a file months later.
9. Schedule refresh. If your policy has time-bound checks, put them in a job queue with a date, a reason and a cost estimate.

Sample request and response: the pre-disbursal bank check

This is the call that most often saves a lender from a bad disbursal. The request carries the account number, IFSC and the borrower's name as on your file:

curl -X POST "https://api-b2b.stampmitra.in/v1/verify/bank-account" \
  -H "Authorization: Bearer $STAMPMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"accountNumber":"000123456789","ifsc":"ICIC0001234","name":"Ravi Kumar"}'

The documented response shape, with sample values, is:

{
  "referenceId": "SMV-20260927-3B71A0",
  "valid": true,
  "nameAtBank": "RAVI KUMAR",
  "bankName": "ICICI Bank",
  "utr": "017952100012345",
  "city": "Mumbai",
  "branch": "Andheri West",
  "micr": "400229002",
  "nameMatchScore": "100",
  "nameMatchResult": "GOOD_MATCH",
  "accountStatus": "ACCOUNT_IS_VALID",
  "accountStatusCode": "1",
  "ifscDetails": { "bank": "ICICI Bank", "ifsc": "ICIC0001234", "state": "Maharashtra" }
}

A small Node function shows how a team might turn this into a decision. The thresholds are placeholders for you to tune against your own data.

const BASE = "https://api-b2b.stampmitra.in";

async function verifyDisbursalAccount({ accountNumber, ifsc, name }) {
  const res = await fetch(`${BASE}/v1/verify/bank-account`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.STAMPMITRA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ accountNumber, ifsc, name }),
  });
  if (res.status === 429 || res.status === 502) return { decision: "retry_later", status: res.status };
  if (res.status === 402) return { decision: "ops_alert", reason: "wallet" };
  const body = await res.json();
  if (!res.ok) return { decision: "fix_input", requestId: body.error?.requestId, status: res.status };

  const score = Number(body.nameMatchScore);
  if (!body.valid) return { decision: "hold", reason: "account_not_valid", ref: body.referenceId };
  if (score >= 90) return { decision: "release", ref: body.referenceId };
  if (score >= 60) return { decision: "review", reason: "name_partial", ref: body.referenceId };
  return { decision: "hold", reason: "name_mismatch", ref: body.referenceId };
}

Decision table for a lending file

The same four outcomes recur at every stage, so give your desk one table to work from.

The last row is the one that gets lost in rushed integrations. A failed call is not a pass. Define in advance that no money moves on a file whose pre-disbursal check could not be completed, and make the system enforce it.

Five scenarios from the credit-operations desk

These are hypothetical cases. They show how the responses and the policy fit together.

The clean file

A salaried applicant enters a PAN and name. The PAN comes back valid with a strong match, and the file moves to credit. At sanction, the bank check returns a valid account with a strong name match and the loan is released. Two calls, two transaction ids, two decisions in the evidence record.

The name that does not match

The borrower's PAN shows a full name; the bank holds the account under initials and a surname. The score lands in the middle band. The system routes the file to the review queue with both names side by side and the two referenceId values. A reviewer confirms with the borrower, records the reason and clears the hold. No call is repeated.

The inactive registration

An MSME applicant gives a GSTIN. registrationStatus is not active. The desk does not decline on the status alone: it asks for the current registration document, notes the answer on the file and lets credit decide. The status field gave the desk a reason to ask a question, not the answer.

The upstream outage

During a month-end rush the PAN call starts returning 502. The service parks affected applications in a "verification pending" state, retries with capped backoff, and shows the applicant a message that checking is taking longer than usual. When the source recovers, parked files resume without a re-entry. Nobody gets an approval by default, and nobody gets a rejection for a platform error.

The duplicate application

The same PAN shows up on two applications within an hour, one through a partner and one direct. Because the service caches verified results by normalised PAN for the period your policy allows, the second application reuses the first result and does not trigger a second charge. It still goes to the desk, because duplicate applications are a risk signal in their own right.

Risk and review rules you can copy

The rules below are suggestions to adapt, not requirements and not advice. Tune every number against your own data and have your credit and compliance heads sign off the final version.

• Auto-continue when the PAN is valid, type fits the product and the name score is at or above your high threshold. A starting point for the high threshold is the low nineties, to be tuned with real mismatch samples.
• Review band for scores between a lower threshold, perhaps around the sixties, and the high threshold. Reviewers see both names, the status fields and the referenceId.
• Hard stop for an invalid PAN after one re-entry, an inactive entity without supporting documents, or a disbursal account that is not valid.
• Escalate to a senior reviewer when a second reviewer disagrees with the first, when the same account appears on more than one borrower, or when the same borrower appears with more than one PAN.
• Four-eyes on overrides. Any override of a hard stop needs a second approver and a written reason.
• No silent retries on negatives. The system may retry a 429 or a 502; it must not repeat a valid: false.
• Fail closed at disbursal. If the final account check is missing, failed or older than your freshness window, the release step is blocked.

Operating model: queues, roles and turnaround

A verification layer produces exceptions, and exceptions need an owner. A workable arrangement uses three queues. The first is the review queue for mismatches and partial scores, worked by credit-operations analysts. The second is the exception queue for hard stops that someone wants to override, worked by a senior analyst or a credit manager. The third is the platform queue for failed calls and wallet alerts, worked by engineering or the on-call operator.

For turnaround, set suggested targets by queue and revisit them with your own volumes: same business day for the review queue, shorter for the pre-disbursal holds because a borrower is waiting for money, and an alert-to-action target measured in minutes for wallet and outage alerts. Assign each file to one analyst at a time, and show the age of the oldest item at the top of the screen so that nothing waits silently.

Maker-checker applies to anything that changes a decision: the analyst who clears a mismatch should not be the one who approves its override. Give each role the minimum access it needs, and keep the API keys with the service, never with a person's browser.

What to store, and for how long

Store enough to reconstruct a decision, and no more. For each check: the product called, referenceId, the timestamp, the environment of the key, a masked or hashed form of the input, the response fields you used for the decision, the decision itself, the rule or threshold version in force, and the analyst and reason for any manual action. Avoid storing raw identity numbers in logs, and keep the full evidence record in the system that has access controls and an audit trail, not in application logs.

How long to keep it is not an engineering question. RBI's KYC framework, the anti-money-laundering rules that apply to regulated entities, the Digital Personal Data Protection Act, 2023 and your own policy all bear on retention, and the periods are measured in years that typically run from the end of the customer relationship. Confirm the exact periods and the deletion duties with your counsel and compliance officer, then encode them as retention classes in your system. StampMitra's own handling of data is described in its data retention and deletion schedule and data processing addendum.

On StampMitra's side you can also look back at what your account called: GET /v1/logs lists your organisation's request logs with filters for service and status, and GET /v1/usage/summary gives usage totals. Retention of those logs depends on the plan, as listed on the pricing page. Treat them as an operational aid, not your system of record.

What it costs: three portfolio sizes

Per-call prices come from the rate card on the pricing page. Here, PAN is ₹5 per call on pay as you go, the bank-account check is ₹4 and the vehicle RC check is ₹9. The Growth and Scale plans lower the standard and premium per-call rates and add a monthly plan fee; the bank-account rate is the same on every plan. All amounts exclude GST at 18%.

First, the cost of one file before GST, for a vehicle-backed loan that runs PAN, bank account and RC, and for a personal loan that runs PAN and bank account only.

Those are per file that completes every step. A funnel does not complete every step for every applicant, so the monthly model below uses an illustrative funnel: every application gets a PAN check, 30 percent reach a bank check at sanction, and 15 percent are vehicle loans that need an RC check. These percentages are assumptions to replace with your own. The three levels are 2,000, 10,000 and 50,000 applications a month.

For 2,000 applications: 2,000 PAN checks, 600 bank checks and 300 RC checks.

For 10,000 applications: 10,000 PAN checks, 3,000 bank checks and 1,500 RC checks.

For 50,000 applications: 50,000 PAN checks, 15,000 bank checks and 7,500 RC checks.

Reading the three tables: at the smallest volume the plan fees cost more than the per-call savings, so pay as you go or Growth is cheaper than Scale. As volume rises the lower rates win, and at the largest level the monthly spend is far above the level at which StampMitra suggests an Enterprise arrangement, so that is a conversation for the contact page rather than a plan choice. The tables assume GST applies to the plan fee as it does to usage; check your invoice for the exact treatment. Nothing is billed for calls that fail with a 4xx or 5xx error, because usage is recorded after a successful response, but a valid: false answer is a successful call. Wallet top-ups have a minimum, shown on the pricing page, and sandbox calls never debit the wallet.

Rollout: sandbox, pilot, production

Roll out in three steps and write down what "done" means for each.

Sandbox. Sign up for a key and build against the sandbox, where every call returns sample data that does not describe real people, and where specific test values give predictable outcomes. At the time of writing the sandbox responder returns a valid result for the PAN SNDBX0000A and an invalid one for SNDBX9999F; the GSTIN pair is 09SNDBX0000A1Z5 and 09SNDBX9999F1Z5. Any other input gets a stable but arbitrary outcome, so do not assert on it. Confirm the current test values in the dashboard before you write tests against them. Exit criterion: every row of the decision table above has an automated test, including the 402, 429 and 502 paths.

Pilot. Request production access, which depends on your organisation's KYC approval and the per-product production application, then switch the pilot cohort to production keys while the analysts keep checking by hand in parallel. Compare outcomes. Where the API and the analyst disagree, find out why before tightening any automatic rule. Use the sandbox versus production keys guide for the key mechanics and the IP allowlist.

Production. Widen the cohort in steps. Keep the manual review queue live, watch the metrics below and alert on wallet balance well before it reaches zero.

Metrics worth watching

• Auto-continue rate per product and per source channel. A sudden drop usually means a form or source problem, not worse borrowers.
• Review-band rate and age of the oldest item. The first shows the cost of your thresholds; the second shows whether the desk keeps up.
• Hard-stop rate by reason. Invalid PAN, inactive entity and invalid account are different problems with different fixes.
• Override rate and who performs overrides. A high override rate on one rule means the rule is wrong or the reviewers are tired.
• Error rate by code. Watch 402 (wallet), 429 (rate limit) and 502 (upstream) separately, with the requestId kept for every one.
• Cost per disbursed loan. Divide verification spend by loans actually disbursed, not by applications, so that the funnel is visible in the number.
• Repeat calls per PAN. More than one paid call for the same PAN in a window is a cache or deduplication bug.

Mistakes lenders make with verification APIs

• Treating "valid" as "approved". A valid PAN says the PAN exists in the source. It says nothing about creditworthiness or about who is sitting in front of you.
• Releasing money after a failed check. The wiring that retries and then proceeds to "continue anyway" is the most expensive bug in the lifecycle.
• One threshold for every product. A name-match score that is fine for a salaried loan may be too loose for a business account used for large disbursals.
• Exact string equality on names. Initials, ordering, transliteration and honorifics cause false mismatches. Use the score and a review band.
• Retrying negative answers. It costs money and returns the same result.
• Logging raw identifiers. Application logs spread personal data widely and are hard to purge.
• Ignoring the type of PAN. The type field distinguishes an individual from other holders; a company PAN on a personal loan is a reason to look.
• Copying sandbox assumptions into production. Sandbox data is synthetic and its limits differ; revalidate your handling with a small production cohort.
• No owner for the platform queue. Wallet alerts and outage alerts need a named person and a runbook.

Related APIs and guides

The endpoints used on this page are documented in the verification API reference: PAN, bank account, vehicle RC, GSTIN, CIN and Udyam, with the PAN to GSTIN resolver. For adjacent topics, read the bank account verification before payout page, the PAN verification guide, the errors and handling guide, and the vehicle RC guide. If you want to try the calls first, use the API playground with a sandbox key, or start from the quickstart. The full catalogue of industry pages is on the solutions page.

API reference at a glance

{
  "referenceId": "SMV-20260927-8F42K7",
  "pan": "ABCDE1234F",
  "type": "Individual",
  "valid": true,
  "registeredName": "RAHUL KUMAR",
  "fatherName": "SURESH KUMAR",
  "panStatus": "VALID",
  "panStatusCode": "E",
  "panStatusDescription": "Existing and valid PAN",
  "nameMatchResult": "MATCH",
  "nameMatchScore": "100",
  "aadhaarSeedingStatus": "y",
  "aadhaarSeedingStatusDescription": "Aadhaar linked",
  "lastUpdatedAt": "2023-04-01",
  "message": "PAN is Valid"
}

{
  "referenceId": "SMV-20260927-3B71A0",
  "valid": true,
  "nameAtBank": "RAVI KUMAR",
  "bankName": "ICICI Bank",
  "utr": "017952100012345",
  "city": "Mumbai",
  "branch": "Andheri West",
  "micr": "400229002",
  "nameMatchScore": "100",
  "nameMatchResult": "GOOD_MATCH",
  "accountStatus": "ACCOUNT_IS_VALID",
  "accountStatusCode": "1",
  "ifscDetails": {
    "bank": "ICICI Bank",
    "ifsc": "ICIC0001234",
    "micr": "400229002",
    "address": "Andheri West, Mumbai",
    "city": "Mumbai",
    "state": "Maharashtra",
    "branch": "Andheri West"
  }
}

{
  "referenceId": "SMV-20260927-3D71Q9",
  "regNo": "MH12AB1234",
  "registrationStatus": "VALID",
  "ownerName": "RAHUL KUMAR",
  "ownerFatherName": "SURESH KUMAR",
  "vehicleClass": "LMV",
  "vehicleManufacturerName": "MARUTI SUZUKI",
  "model": "SWIFT",
  "vehicleColor": "WHITE",
  "chassis": "MA3ERLF1S00123456",
  "engine": "K12MN1234567",
  "registrationDate": "2019-05-14",
  "rcStatus": "ACTIVE",
  "rcExpiryDate": "2034-05-13",
  "insuranceUpto": "2025-05-13",
  "isCommercial": false
}

Frequently asked questions