Why Verification APIs Return Different Results Than the Government Portal

Key takeaways

• A mismatch between an API result and a portal page is usually timing, scope, matching rules or input differences, not a defect in either.
• The StampMitra reference documents the response fields and a referenceId per call. It does not document the refresh schedule of each underlying source, nor whether a response was served from a cache. Ask support for specifics about your product rather than assuming.
• Every API result is a point-in-time answer. Treat it as true as of the moment of the call at best, and as of the source's last refresh at worst.
• The PAN response includes lastUpdatedAt, a date associated with the record. It is context, not a statement of when your call was made.
• Portals and APIs expose different fields. A portal may show a cancellation date or a filing status that the API response does not carry.
• Name comparison rules differ. A human reading two names sees the same person. A scoring function sees a number.
• Before investigating, rule out the boring causes: a typo, a different identifier, a different portal page, uppercase against mixed case.
• Capture the referenceId, the requestId if an error occurred, the exact input, the time of the call and the full response. Without them nobody can help you.
• Design your own system so each decision states how fresh its data must be, and re-check before high-impact actions.
• Sandbox returns sample data and will never show you this kind of difference. Do not use it as evidence in either direction.

What "different" usually looks like

Not all discrepancies are the same, and the cause depends on the kind. Sort yours first.

The families of cause are few: timing, source and refresh, caching, scope, matching rules and plain input mistakes. The next section takes them in turn.

The reasons results differ

1. Time has passed

The most common cause is the least interesting. Records change: a registration is suspended, a company is struck off, a name is updated. If the API call and the portal look were made at different moments, they can legitimately show different states. Ask two questions: when did the API call happen, and when did the person look at the portal? A gap of days, or even hours around a known event, can explain everything.

The fix is procedural. Record the time of every verification, show it wherever you display the result, and re-check before acting on an old one. "Verified on 12 October" is a different statement from "is active".

2. The sources are not the same, and each refreshes on its own schedule

A verification API sits between your system and underlying data sources. A portal sits between a person and the authority's own systems. Even when the authority is the same, the data the API reads and the data the portal page renders can come through different paths, with different refresh cycles. A change recorded in one place may take time to appear in the other.

What is documented: the StampMitra reference describes the request and response of each endpoint and notes that the verification is performed when you call. What is not documented: how often each source refreshes, or the exact path to the authority's record. For a specific product, ask support what the source is and how current it is, and write the answer into your own risk documentation.

3. Caching exists somewhere along the way

Caching is a normal, sensible engineering practice that makes systems fast and protects upstream services. It can exist at the data source, at the API, at a proxy, in your own application and in the browser. The effect is always the same: you see a recent copy, not the live record.

It matters to be honest about what you can and cannot know. You cannot tell from a single response whether it came from a cache. The StampMitra reference does not document cache behaviour or freshness headers for the verification endpoints. If your decision needs a guarantee of freshness, ask support what is guaranteed for that product, and design your own caching (see below) so that you are never the layer that makes the data older than your policy allows.

4. The API shows fewer fields than the portal

Portals are designed for people and show a rich page. An API returns a defined, narrower set. For a GSTIN, the StampMitra response carries the registration record (valid, the legal and trade name, gstinStatus, taxpayerType, dateOfRegistration, the jurisdictions and the addresses), while a portal's taxpayer page can show more, such as a cancellation date where one exists or a filing status. Seeing a field on the portal that the API does not return is a difference in scope, not a discrepancy.

5. The name comparison rules differ

A reviewer who sees "R Kumar" and "RAHUL KUMAR" concludes they are the same person. A scoring function returns a number below 100. A reviewer who sees "Ram Kumar" and "RAMKUMAR" may or may not agree with the score. Whenever the disagreement is about a name match, ask what each side compared and by what rule. The PAN and bank account endpoints return nameMatchScore and nameMatchResult, and their matching logic is not published. See how to verify a PAN and match the name for how to layer your own comparison on top.

6. The input was not the same

This is more common than anyone expects. A different character in a PAN or GSTIN, an extra space, lower case where upper case was expected, an old identifier copied from a letterhead, or a number belonging to a different registration of the same business. Before anything else, compare the exact string sent to the API with the exact string typed into the portal. Trim whitespace and upper-case both.

7. The portal page was a different page

Authorities run more than one lookup. A page that checks whether a number is valid, a page that returns a taxpayer's full details and a page that shows filing information can each be fed from slightly different data. Make sure the person who "checked the portal" used the equivalent function. Ask for a screenshot including the URL and time.

8. The words mean different things

"Valid" in an API response means a record matching the identifier was found. A portal might say "valid" while showing a status such as inactive. A status label on the portal may be worded differently from the API's registrationStatus or panStatus. Compare meaning, not just spelling, and when you cannot tell whether two labels are equivalent, treat the case as needing review.

9. The customer is looking at something else

Occasionally the difference is not between the API and a portal at all. A customer who says "the portal shows my GST as active" may have checked a different state's registration, a different PAN, or an older confirmation email. Ask them for the identifier and a screenshot, and run the check yourself.

What StampMitra documents, and what it does not

Being clear about the edges keeps conversations with customers and auditors honest.

When a question falls in the right-hand column, ask support and treat the written answer as the documentation. Do not fill the gap with an assumption in your policy.

Investigating a discrepancy, step by step

Work through these in order. Most cases resolve by step four.

1. Write down both observations with times. The API result (with its referenceId and the time of the call) and the portal observation (with a screenshot, its URL and the time).
2. Compare the exact inputs. The string you sent against the string typed into the portal. Remove whitespace and upper-case both.
3. Confirm you are comparing like with like. Same identifier, same kind of lookup, same registration (for GSTIN: the same state).
4. Look at the gap in time. If it is more than your policy tolerates, or there was a known change in between, re-run the API call and look again. The new call has a new referenceId, so keep both.
5. Check scope. Is the field the portal shows part of the API response at all? If not, the discrepancy is a scope difference.
6. Check the matching. If the dispute is about a name, compare the strings by your own normalised rules.
7. Only now suspect a data issue. If steps one to six leave a real, repeatable difference, collect the evidence below and ask support.

What to capture

// dispute-bundle.mjs
export function disputeBundle({ input, response, error, portalNote }) {
  return {
    capturedAt: new Date().toISOString(),
    endpoint: "POST /v1/verify/gstin",
    input,                                   // exactly what you sent, after trimming and upper-casing
    referenceId: response?.referenceId ?? null,
    requestId: error?.requestId ?? null,     // present in the error envelope on failures
    status: response?.registrationStatus ?? null,
    valid: response?.valid ?? null,
    lastUpdatedAt: response?.lastUpdatedAt ?? null, // PAN responses only
    portalNote,                              // what the person saw, where, and when
  };
}

A bundle like this is all support needs to look at a specific call. Never include the API key.

Reading dates in the response

Dates are where freshness questions concentrate, so be precise.

The PAN response carries lastUpdatedAt, which in the documented sample is 2023-04-01. It is a date associated with the record. It is not documented as the time of your call, nor as the time the source last refreshed. Use it as context, for example to notice that a very old date accompanies a status you are about to rely on, and do not treat it as a freshness guarantee.

The call itself has a time, which you know because you made it. Your own record of "verified at" is the one date you fully control. Store it with the referenceId, and display it wherever the result is shown.

The GSTIN, CIN and bank account responses do not carry a dedicated last-updated field in the documented shape. A CIN response includes incorporationDate, which is a fact about the company and not about the data. Do not confuse it with a freshness indicator.

Designing for freshness

Instead of asking "is the data fresh?", ask "how fresh must it be for this decision?". Different decisions have different needs.

The last row deserves emphasis. Re-running a verification when you are asked how you decided gives you today's answer, not the one you relied on. Keep the original record.

A freshness guard in code

A small function turns the table into behaviour. It refuses to use an old verification for a decision that needs a fresh one.

from datetime import datetime, timedelta, timezone

MAX_AGE = {
    "DISPLAY": timedelta(days=90),
    "ONBOARD": timedelta(hours=1),
    "PAYMENT": timedelta(hours=24),
    "INVOICE": timedelta(hours=24),
}

def usable(verification: dict, purpose: str, now: datetime | None = None) -> bool:
    now = now or datetime.now(timezone.utc)
    checked_at = datetime.fromisoformat(verification["checked_at"])
    return (now - checked_at) <= MAX_AGE[purpose]

def require_fresh(verification: dict, purpose: str, reverify):
    if verification and usable(verification, purpose):
        return verification
    return reverify()  # a new billable call with a new referenceId

The ages in the table are examples to show the mechanism, not recommendations. Set yours from your own risk appetite and cost. The point is that the number is written down, in one place, and can be argued about.

Caching on your side

You will be tempted to cache verification results to save calls and speed up screens. Done carefully it is fine. Done carelessly it manufactures the very discrepancy this guide is about.

If you cache nothing, you pay for every call and gain simplicity. If you cache, you also take responsibility for staleness. Either is defensible when it is deliberate.

Three scenarios, diagnosed

Rules are easier to trust once you have seen them applied. These cases use invented businesses and the investigation steps above.

Scenario one: "Active" against "Cancelled". A finance analyst opens the GST portal for a vendor and sees a cancelled registration. The onboarding system shows registrationStatus: Active from a check run six weeks earlier. Step one gives the answer before anything else: the API result is six weeks old, and the portal view is from today. Nothing is wrong. The policy gap is that the system showed "Active" without a date and did not re-check before the payment run. The fix is the freshness guard and a visible "verified on" date. A re-run today returns a new referenceId; the old and new records together tell the story of when the status changed.

Scenario two: a name that does not appear to match. A lender's reviewer compares the registered name returned for a PAN with the name on the borrower's agreement. The API returned a partial match. The reviewer sees "Rahul Suresh Kumar" on the agreement and "RAHUL KUMAR" in the response and judges them the same person. There is no data issue. The two views applied different comparison rules, and the system's threshold put the case in review rather than auto-accepting. That is the review lane doing its job. The fix, if there is one, is to calibrate the threshold using decisions like this one, as described in the PAN name guide.

Scenario three: a field the portal shows and the API does not. A compliance officer wants to know whether a vendor's registration is under a particular scheme, sees it on the portal and asks why the API response does not say. The API's GSTIN response is deliberately narrow and does not carry that field. This is scope, not discrepancy. The officer has two options: record the portal observation as a manual check with a screenshot and time, or ask the vendor for the registration certificate. Either belongs in the case file. Building the policy on a field the API does not return, and promising it in a requirements document, would be the real mistake.

None of the three needed support to resolve. The fourth kind, a repeatable difference after steps one to six with matching inputs, same-minute observations and equal scope, is the one to escalate.

What to tell your own users

How you display a verification decides how much trouble these differences cause. A few copy and design choices make them less likely.

Show when. Next to every verified badge, show the date and, in detail views, the time. "Verified 12 Oct" invites the right question ("has it changed since?"). A bare green tick invites the wrong belief ("it is verified, forever").

Say what was checked. "GST registration active at 12 Oct" is a more honest label than "GST verified". The first states a fact at a time. The second implies a permanent property.

Offer a re-check. Where a user is entitled to it, give a button that re-verifies and shows the new time. Make it rate-limited, since each press is a billable call.

Do not promise the portal and the API will match. If your help pages say your result "matches the government record", you have taken on the responsibility for every refresh gap. A truer sentence: "We check official records at the time you submit, and show you the date. Records can change afterwards."

Keep a way to submit evidence. A user who has a certificate or a screenshot should be able to attach it to a case, so a human can settle the disagreement. Most disagreements are settled with a document, not an argument.

What to write in your policy and risk register

Auditors and partner banks do not expect perfect data. They expect that you know the data's limits and have handled them. Three paragraphs in your policy cover most of it.

First, a statement of the data sources you rely on, in terms you can support: "We verify identifiers through the StampMitra verification API, which returns the record held by the underlying source at the time of the call. We rely on the response, store its reference, and re-verify according to the schedule below." If StampMitra support has given you specifics about a source's freshness, quote them with the date you received them.

Second, the freshness table from this guide with your own numbers, and the owner who approved them.

Third, the dispute procedure: who receives a disagreement, which evidence is captured, how a discrepancy is escalated to support and how it is recorded. If a person overrides a result, record who and why. Keep the original response unchanged.

A risk register entry might read: "Verification results may lag the authoritative record. Mitigation: freshness windows by decision type; re-check before payment; dated display; reviewer lane for disputed cases; evidence retention per policy." That is a risk you have named and bounded, which is what a reviewer wants to see.

A raw call, for the record

When investigating, it helps to reproduce the call by hand with a clean input, so nothing in your application code muddies the picture.

curl -i -X POST "https://api-b2b.stampmitra.in/v1/verify/gstin" \
  -H "Authorization: Bearer $STAMPMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"gstin":"07AAAAA1111A1Z1"}'

The -i flag prints the status line and headers along with the body, which is useful when you want to show support exactly what came back. Remove the key from anything you paste. Remember that a sandbox key returns sample data, so a reproduction made with sk_test_ proves nothing about a real record; use a production key and an identifier you are entitled to check.

Talking to a customer who says the portal disagrees

Your support team will meet this conversation weekly. A script keeps it calm and useful.

• Thank them and ask for the identifier they checked and a screenshot that shows the page and the time.
• Run the verification yourself with that identifier, and note the time.
• If your result and their screenshot differ, explain that the two views can be a few hours or days apart, and that you are re-checking.
• If the difference persists, ask for a document that settles it: a registration certificate, a company master record, a PAN card image, as your policy allows.
• Do not tell them which source is "right" unless you are sure. Tell them what each shows and what you need.
• Keep every artefact against the case: the screenshot, the referenceId, the time.

The tone matters. A customer whose registration was reinstated last week is not lying. They are ahead of a refresh cycle, and a polite re-check resolves it.

Escalating to support

When your own investigation ends with a repeatable difference, send support a message they can act on without a second round of questions.

1. The endpoint and the exact input (masked where appropriate).
2. The referenceId of the call, and its time.
3. The requestId if the call failed.
4. What the response said, copied from the stored record.
5. What the portal showed, with a screenshot, the URL and the time.
6. What you have ruled out (typo, different page, scope difference).
7. What you need: an explanation, a re-check on their side, or a statement about the source's freshness for that product.

Send it to [email protected] or through the support page. A message with these seven items gets a specific answer sooner than a general "the data is wrong".

When the portal is the right tool, and when it is not

Portals are the authority's own interface and are the right tool for a person confirming a single record, settling a dispute with a customer, or checking a field the API does not return. They have limits as a system component. They are designed for human use, typically with captchas and session handling, they do not give you a stable machine-readable contract, they offer no audit trail tied to your own transaction, and automating them may breach their terms. An API gives you a programmatic interface, a referenceId per call and a record you can store.

The practical pattern is to use both for what they are good at: the API for automated, audited decisions at scale, and the portal for human confirmation when a case is contested. When they disagree, treat the authority's own record as the thing you are ultimately trying to reflect, and treat both views as snapshots.

Why the sandbox cannot show you this

Sandbox returns sample data for every input: stable, synthetic, with invented names, and a roughly two in three chance of "valid" for inputs that are not magic values. It never touches a real record. That means two things for this topic. A sandbox result will never disagree with a portal because it has no real counterpart, so a clean sandbox comparison is meaningless. And a discrepancy you see in sandbox against a real portal page is expected, not a bug. The guide on sandbox vs production: what you can test lists what sandbox does prove, including how your code behaves when a response has an unexpected status.

Common mistakes

• Concluding the API is wrong without comparing the exact input strings.
• Concluding the portal is the only truth and ignoring the API's referenceId record.
• Re-running a verification to answer "how did you decide", which replaces the evidence with today's answer.
• Caching results by identifier alone, so a display-grade result is used for a payment.
• Treating lastUpdatedAt as the time of the call.
• Assuming a field missing from the API response means the data is missing, when it is outside the response's scope.
• Comparing names by exact equality and then blaming the API for a "mismatch".
• Using sandbox to prove or disprove anything about a real record.
• Sending support a screenshot without the identifier, time or referenceId.

What to do next

Start by making the time of every verification visible in your own screens, then add the freshness table to your policy with numbers your risk owner has agreed. For the structure of the identifiers whose registrations change, read PAN vs GSTIN vs CIN and How to verify a GSTIN programmatically. For what to store from each call so a later question can be answered from the record, read what to log and keep. The PAN product page and the GSTIN product page describe the two lookups most affected by refresh lag, the API reference lists the fields of every endpoint, and the pricing page shows what a re-check costs.

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-9K21P4",
  "verificationId": "VRF-4M8Q2T7XB9KD",
  "gstin": "29AAICP2912R1ZR",
  "GSTIN": "29AAICP2912R1ZR",
  "valid": true,
  "legalNameOfBusiness": "UJJIVAN SMALL FINANCE BANK LIMITED",
  "tradeNameOfBusiness": "UJJIVAN SMALL FINANCE BANK",
  "centerJurisdiction": "I-A RANGE",
  "stateJurisdiction": "GUWAHATI - A - 1",
  "dateOfRegistration": "2017-09-30",
  "constitutionOfBusiness": "Public Limited Company",
  "taxpayerType": "Regular",
  "gstinStatus": "Active",
  "lastUpdateDate": "2022-03-01",
  "natureOfBusinessActivities": [
    "Retail Business",
    "Supplier of Services",
    "Recipient of Goods or Services",
    "Office / Sale Office",
    "Others"
  ],
  "principalPlaceAddress": "First Floor 3512-DISPUR Prithivi Mansion opp. KFC building G.S. Road, Lachit Nagar Assam 781007",
  "principalPlaceSplitAddress": {
    "buildingName": "Prithivi Mansion",
    "street": "G.S. Road",
    "location": "Lachit Nagar",
    "buildingNumber": "3512-DISPUR",
    "district": "Guwahati",
    "state": "Assam",
    "city": "Dispur",
    "flatNumber": "First Floor",
    "latitude": "26.1445",
    "longitude": "91.7362",
    "pincode": "781007"
  },
  "additionalAddresses": [
    {
      "address": "Mirza Santipur NH-37 Dist-Kamrup Rural PS-Palashbari, PO  Mirza Kamrup Assam 781125",
      "splitAddress": {
        "buildingName": "",
        "street": "NH-37",
        "location": "Santipur, Mirza",
        "buildingNumber": "",
        "district": "Kamrup Rural",
        "state": "Assam",
        "city": "Palashbari",
        "flatNumber": "",
        "latitude": "26.0926",
        "longitude": "91.5069",
        "pincode": "781125"
      }
    },
    {
      "address": "N.A.C.C.I. Foundation 3559-Tezpur CHAMBER BHAWAN Binjraj Road, P. o. and P.S. - Tezpur, Dist. Binjraj Road, P. o. and P.S. - Tezpur, Dist. Sonitpur Assam 784154",
      "splitAddress": {
        "buildingName": "CHAMBER BHAWAN",
        "street": "Binjraj Road",
        "location": "Tezpur",
        "buildingNumber": "3559-Tezpur",
        "district": "Sonitpur",
        "state": "Assam",
        "city": "Tezpur",
        "flatNumber": "",
        "latitude": "26.6338",
        "longitude": "92.8006",
        "pincode": "784154"
      }
    }
  ],
  "message": "GSTIN Exists",
  "legalName": "UJJIVAN SMALL FINANCE BANK LIMITED",
  "tradeName": "UJJIVAN SMALL FINANCE BANK",
  "registrationStatus": "Active",
  "principalPlaceOfBusiness": "First Floor 3512-DISPUR Prithivi Mansion opp. KFC building G.S. Road, Lachit Nagar Assam 781007"
}

Frequently asked questions