What to Log and Keep From a Verification Call: Audit Trail Guidance

Key takeaways

• Distinguish operational logs (short-lived, for debugging) from audit records (structured, retained, for evidence). They have different contents, retention and access.
• The audit record should let you answer: what was checked, when, by whom, with what result, under which policy, and what was decided.
• Link to the call with the StampMitra referenceId (and requestId on failures) instead of copying the response body.
• Mask identifiers for display and logs (for example the first two and last two characters of a PAN, the last four digits of an account number). Hash identifiers you only need for matching.
• Never log API keys, full PANs, full account numbers, full response bodies or request bodies by default.
• StampMitra keeps request logs for your organisation, readable through GET /v1/logs, with retention that depends on your plan: 30 days on pay-as-you-go, 90 on Growth and 365 on Scale in the published plan data, and shorter on sandbox. They do not return the original response body, so your own record has to carry the decision.
• Retention is a policy decision. Sector rules can require KYC records to be kept for years, while data protection principles push towards deleting what you no longer need. Settle the period with your compliance owner and write it down.
• Make audit records append-only, restrict who can read them, and consider tamper evidence such as a hash chain.
• Re-running a verification to answer an audit question gives you today's answer, not the one you relied on. Keep the original record.

Logs and audit records are different things

Teams often use one word for two jobs. Separate them.

Operational logs flow into aggregators, error trackers and dashboards that many people can read and that often live with third parties. That is exactly why sensitive data does not belong there. The audit record lives in a controlled store. Neither is a substitute for the other: a debugging log is not evidence, and the audit record is a poor place to dump stack traces.

The questions an audit will ask

Design the record backwards from the questions you will be asked.

1. Who was verified, and how can we identify them without exposing the number?
2. What exactly was checked: which identifier, which endpoint?
3. When was the check made?
4. Who or what made it: which service, which user, which key?
5. What did the source say, at least in the fields the decision depended on?
6. What was the decision, and which rules led to it?
7. Which version of the policy was in force?
8. Did a person override the automated outcome, who, when and why?
9. Can we show the call really happened, independently of your database?
10. If we are asked to delete this person's data, what happens to this record?

Each question maps to a field or a mechanism below. If you cannot answer one from the record, either add the field or accept that you cannot answer the question, and say so in your policy.

A minimal verification record

The following schema covers the questions without storing the response body.

An example row:

{
  "id": "vr_01J9X2K8",
  "subject_id": "vendor_1042",
  "subject_kind": "GSTIN",
  "subject_masked": "07*********Z1",
  "subject_hash": "9b3f...e1",
  "endpoint": "POST /v1/verify/gstin",
  "environment": "production",
  "requested_at": "2026-10-29T09:41:07Z",
  "actor": "svc:onboarding-worker",
  "reference_id": "SMV-20260927-9K21P4",
  "request_id": null,
  "http_status": 200,
  "result": "valid",
  "facts": { "registrationStatus": "Active", "embeddedPanMatches": true, "nameCompare": "COMPATIBLE" },
  "decision": "PASS",
  "reasons": [],
  "policy_version": "vendor-checks@7"
}

Look at facts. It holds the three things the decision actually depended on and nothing else: the status, whether the embedded PAN matched, and the result of the name comparison. It does not hold the legal name, the principal place of business or the director list. If a later question needs more, the reference_id and the platform's own records are the route, subject to their retention.

What to mask, hash or never store

The pattern in the table is the same in every row: store a pointer, a result or a masked form. Store plaintext only where a rule demands it, and then in a field that is encrypted and read by few.

Masking and hashing in code

// mask.mjs
import crypto from "node:crypto";

export const maskPan = (pan) => (pan && pan.length === 10 ? `${pan.slice(0, 2)}******${pan.slice(-2)}` : "[invalid]");
export const maskGstin = (g) => (g && g.length === 15 ? `${g.slice(0, 2)}*********${g.slice(-2)}` : "[invalid]");
export const maskAccount = (a) => (a && a.length >= 9 ? `${"*".repeat(a.length - 4)}${a.slice(-4)}` : "[invalid]");

// Salted hash for duplicate detection. Keep the salt in a secret manager, not in the database.
export function subjectHash(kind, value, salt = process.env.AUDIT_HASH_SALT) {
  return crypto.createHmac("sha256", salt).update(`${kind}:${value.toUpperCase().trim()}`).digest("hex");
}

The same in Python:

import hashlib, hmac, os

def mask_pan(pan: str) -> str:
    return f"{pan[:2]}******{pan[-2:]}" if pan and len(pan) == 10 else "[invalid]"

def mask_account(acct: str) -> str:
    return "*" * (len(acct) - 4) + acct[-4:] if acct and len(acct) >= 9 else "[invalid]"

def subject_hash(kind: str, value: str) -> str:
    salt = os.environ["AUDIT_HASH_SALT"].encode()
    return hmac.new(salt, f"{kind}:{value.upper().strip()}".encode(), hashlib.sha256).hexdigest()

Use an HMAC with a secret key, not a bare hash. A bare SHA-256 of a PAN can be reversed by trying every possible PAN, since the space is small. A keyed hash with the key held outside the database cannot.

Where the StampMitra request logs fit

StampMitra records each of your API calls against your organisation, and you can read them with an API key. They are your independent evidence that a call happened, which answers audit question nine.

GET /v1/logs returns paginated items. Each carries an id, a createdAt time, an actorType, the service code such as pan.verify, and metadata. You can filter by from, to, service and status (success or failure), and page with limit (up to 200) and nextCursor.

curl -G "https://api-b2b.stampmitra.in/v1/logs" \
  -H "Authorization: Bearer $STAMPMITRA_API_KEY" \
  --data-urlencode "service=pan.verify" \
  --data-urlencode "from=2026-10-29T00:00:00.000Z" \
  --data-urlencode "to=2026-10-30T00:00:00.000Z" \
  --data-urlencode "limit=200"

Three points about what they are and are not.

They are an activity log, not a data store. The items identify the service and the time, and they do not return the original response body. That is why the decision and its facts must be in your own record.

Their retention depends on your plan. In the published plan data, log retention is 30 days on pay-as-you-go, 90 days on Growth and 365 days on Scale, and the sandbox plan has a shorter window. If your audit period is longer, export what you need on a schedule, and do not treat the dashboard as an archive.

They are keyed to time and service, not to your subject. When you need to prove a particular call happened, the referenceId stored in your own record and a time-window query on the logs together give you the proof. The errors, retries and idempotency guide shows a worked lookup.

Reconciling with the usage summary

GET /v1/usage/summary returns totals for the current billing period: totalApiRequests, callsByService, callsByPeriod and callsByDay. Compare these with the count of audit records you wrote for the same period and service. A platform count higher than yours means calls made without a record; a lower one means records for calls that were rejected before work. Monthly reconciliation is an audit control in its own right. It shows that your record is complete.

Retention: how long to keep what

There is no single right answer, and this guide will not give you a number. What it can do is lay out the forces.

The reconciliation is to separate what you keep. Keep the minimal audit record for the long period, since it holds masked or hashed subjects and normalised facts. Keep anything richer, such as encrypted names or uploaded documents, for the shortest period your rules allow. Delete operational logs on a short rotation.

A retention table in your policy might look like this, with your own periods filled in.

For what StampMitra itself retains, read its developer data retention and deletion schedule, developer privacy policy and data processing addendum. They describe StampMitra's practice and do not set yours.

A retention job

from datetime import datetime, timedelta, timezone

RETENTION = {  # filled in by you and your compliance owner
    "ops_log": timedelta(days=30),
    "audit_record": timedelta(days=365 * 5),
    "identity_blob": timedelta(days=365 * 5),
}

def sweep(db, now=None):
    now = now or datetime.now(timezone.utc)
    for table, keep in RETENTION.items():
        cutoff = now - keep
        n = db.delete_older_than(table, cutoff, respecting_legal_hold=True)
        db.log_event("retention_sweep", table=table, cutoff=cutoff.isoformat(), deleted=n)

The figures above are placeholders to show where the numbers go. They are not recommendations. Notice respecting_legal_hold: when a dispute or investigation is open, normal deletion must pause for the affected records.

Erasure requests and records you must keep

A person may ask you to delete their data. A rule may require you to keep a verification record. Both can be true at once, and the audit record design is what lets you honour each part.

The sensible handling is: delete what you are not required to keep (rich identity data, documents that no rule needs), keep what you are required to keep (the minimal audit record, with masked and hashed subject), and tell the person what you retained and why. Because the minimal record already holds a masked subject and a keyed hash instead of the plaintext, keeping it does the least possible harm. Decide this process in advance with your counsel, write it down, and make the deletion steps a runbook rather than a scramble. For the general framework see the Digital Personal Data Protection Act, 2023, and confirm how it interacts with your sector's retention rules.

Notice and consent

The record is only the back half. The front half is telling people what you collect and why. At the point where a person enters a PAN or a bank account, say what you will check, with whom the check is made, why, and how long you keep the result. That sentence is your purpose statement, and your audit record's field set should match it: if the notice says you keep a masked identifier and the outcome, do not quietly keep names and addresses as well.

Access control and encryption

An audit store is a high-value target, so treat it as one.

• Least privilege. A small, named group reads audit records. Engineers read operational logs but not the audit store by default.
• Logging reads. Record who viewed which audit records, since access to personal data is itself something to evidence.
• Encryption at rest and in transit. Use your platform's encryption, and a separate application-level key for any field that holds plaintext identifiers or names.
• Key separation. Keep the hash salt and any field-encryption keys in a secret manager, apart from the database.
• Backups. Backups inherit the data's sensitivity and its retention. Make sure a deletion in the source is reflected, within a stated period, in the backups.

Tamper evidence

An audit record is more convincing when you can show nobody has changed it. Two simple practices help.

Append-only storage. Do not update rows. Corrections and overrides are new rows that reference the old one. Enforce it with database permissions: the application role has insert and select but not update or delete on the audit table, and only a separate retention role can delete, with its own logging.

A hash chain. Each record includes the hash of the previous one, so a changed or removed row breaks the chain.

// chain.mjs
import crypto from "node:crypto";

export function sealRecord(record, previousHash) {
  const body = JSON.stringify(record, Object.keys(record).sort());
  const hash = crypto.createHash("sha256").update(`${previousHash ?? ""}|${body}`).digest("hex");
  return { ...record, prev_hash: previousHash ?? null, hash };
}

export function verifyChain(rows) {
  let prev = null;
  for (const row of rows) {
    const { hash, prev_hash, ...rest } = row;
    if (prev_hash !== prev) return { ok: false, brokenAt: row.id };
    const expected = crypto.createHash("sha256").update(`${prev ?? ""}|${JSON.stringify(rest, Object.keys(rest).sort())}`).digest("hex");
    if (expected !== hash) return { ok: false, brokenAt: row.id };
    prev = hash;
  }
  return { ok: true };
}

A chain does not stop someone with full database access from rewriting everything, but it makes quiet edits detectable, and publishing the latest hash somewhere outside the database (a signed daily note, a separate system) makes rewrites detectable too. It is a proportionate control for evidence you may need to defend.

Recording human decisions and overrides

Automated decisions are the easy part. The part that attracts questions is when a person intervened. For each override, record who, when, what the automated decision was, what the person chose, and the reason in a sentence of free text. Store it as a new row linked to the original. Require a reason, because "approved" with no reason is the record auditors dislike most.

Keep the reviewer's identity as a stable id, not only a display name, and record the role they acted in. If a second approver is required above a threshold, store both. When a policy changes, do not rewrite the history: the policy_version on each row tells the reader which rules applied at the time.

Recording failures, unknown outcomes and negative results

The record should be honest about what did not work.

• A negative result (valid: false) is a completed lookup. Record it as result: invalid with its referenceId. It is not an error.
• An error (400, 401, 402, 403, 429, 502) is recorded as result: error with the http_status, the error.code and the request_id. No referenceId exists for a rejected call.
• An unknown outcome (a timeout) is recorded as result: unknown, later resolved to valid, invalid or error once you have checked the logs. Keep the history. An auditor who sees unknown followed by a resolution learns that you handled the ambiguity.
• A retry is a new attempt. Keep it linked to the first through a shared subject_id and purpose, and never overwrite the earlier row.

Redaction at the edges of your stack

The best audit design is undone by a debugging line that prints a request body. Put redaction where logs leave your code.

// logger.mjs  (pino)
import pino from "pino";

export const logger = pino({
  redact: {
    paths: ["req.headers.authorization", "req.headers['x-api-key']", "*.pan", "*.gstin", "*.accountNumber", "*.name", "*.registeredName", "*.nameAtBank", "*.fatherName", "body", "response"],
    censor: "[redacted]",
  },
});

import logging, re

PAN = re.compile(r"\b[A-Z]{5}[0-9]{4}[A-Z]\b")
GSTIN = re.compile(r"\b[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z][1-9A-Z]Z[0-9A-Z]\b")
KEY = re.compile(r"\bsk_(?:live|test)_[A-Za-z0-9_]+\b")

class RedactFilter(logging.Filter):
    def filter(self, record):
        msg = record.getMessage()
        msg = KEY.sub("sk_***", msg)
        msg = PAN.sub(lambda m: m.group(0)[:2] + "******" + m.group(0)[-2:], msg)
        msg = GSTIN.sub(lambda m: m.group(0)[:2] + "*********" + m.group(0)[-2:], msg)
        record.msg, record.args = msg, ()
        return True

logging.getLogger().addFilter(RedactFilter())

Also check the other places that quietly capture data: error trackers that attach request bodies, APM tools that record query strings, reverse proxies that log bodies, and browser tools that capture form fields. Configure each to drop or mask the same fields. And never let a key into a screenshot, a ticket or a chat message.

Producing evidence for an audit

When the request arrives, you want a query, not a project.

-- All verification decisions for one vendor, newest first, with overrides
SELECT r.requested_at, r.subject_kind, r.subject_masked, r.result, r.decision, r.reasons,
       r.policy_version, r.reference_id, o.override_by, o.override_reason
FROM verification_records r
LEFT JOIN verification_overrides o ON o.record_id = r.id
WHERE r.subject_id = :vendor_id
ORDER BY r.requested_at DESC;

Pair the output with a one-page explanation of how the record is built: what is stored, what is masked, how it links to the platform's own logs through referenceId, how long it is kept and who can read it. That page does as much for an auditor as the data does. For a specific disputed call, hand over the referenceId, the time and the requestId if it failed, and ask support to look at the platform's side.

A worked example: one vendor, from onboarding to a payment dispute

Follow a fictional vendor, Sharma Traders, through a record trail to see how the pieces fit together.

Onboarding, March. The onboarding worker verifies the vendor's PAN. The audit table gains a row: subject_kind PAN, subject_masked AB******4F, the keyed hash, endpoint POST /v1/verify/pan, reference_id SMV-...-8F42K7, result valid, facts recording panStatus: VALID, holderTypeMatches: true and nameCompare: COMPATIBLE, decision REVIEW with reason NAME_COMPATIBLE_INITIALS_OR_MIDDLE, policy_version vendor-checks@7. No name, no father's name, no full PAN. A reviewer, Asha, approves after seeing a PAN card image. A second row, linked to the first, records override_by: user:asha, a time and the reason "card image shows middle name abbreviated in application".

The GSTIN and bank account checks add two more rows in the same shape. The bank row stores the last four digits of the account, the full IFSC, the utr in facts, and a normalised nameCompare against the verified PAN name.

A change, August. The vendor emails to say their bank details have changed. The finance system treats the request as a new account: it runs a new bank account verification, writes a new row with a new reference_id, holds the next payment, and records the callback to the vendor's known number as a manual step with the caller's id. The earlier row is untouched.

A dispute, November. A payment went to the new account and the vendor says it never arrived. The finance team opens the vendor's record and sees: the bank verification row from August (account ending in a given four digits, result valid, nameCompare EXACT), the hold and its release with two approvers, and the payment reference from the payments system. They send the bank the utr from the verification row, which identifies the penny-drop transfer, and the account's last four digits. They ask StampMitra support, through support, to confirm the platform's record of the call using the referenceId and the time.

Notice what the team did not do. They did not re-run the verification to "check again", which would have produced a new answer unrelated to the August decision. They did not search email for screenshots. They did not need the full account number in a log. The record answered the questions it was designed to answer, and the platform's own logs, within their retention for the plan, corroborated that the call happened.

Schema design: indexes, partitions and queries

An audit table grows without bound, which makes a few design choices matter.

Index what you query. The common lookups are by subject_id (everything about one vendor), by reference_id (find the record for a platform call), by subject_hash (duplicates and cross-vendor matches) and by requested_at (period reports and retention). Index each, and make reference_id unique within an environment.

Partition by time. Partition the table by month. Retention then becomes dropping a partition, which is fast and does not bloat the table, and reports for a period read only the partitions they need.

Keep facts small and versioned. The facts field is a flexible JSON document, which invites drift. Give it a schema version, validate it on write, and document the keys per subject_kind. A future reader should not have to guess what nameCompare meant in 2026.

Separate environments. Add environment to every row, and refuse to write production records from a sandbox key. A sandbox result in the evidence trail is worse than a missing record, because it looks real.

Do not store derived text. Reasons are codes, decisions are enums, results are enums. Free text appears only in override reasons. Codes can be counted and queried; sentences cannot.

Write in the same transaction as the decision. If the decision and the audit row can diverge, they will. Persist both together, or write the audit row first and treat the decision as derived from it.

Who owns the record

A trail without an owner decays. Name the roles.

Review the arrangement twice a year. Check that the schema still matches the notice, the retention job has been running, the reconciliation is within tolerance, and nobody outside the named group has read access.

After an incident

If a leak occurs, the record decides how bad it is. With masked and hashed subjects, a leak of the audit store exposes patterns and outcomes but not plaintext identifiers. With plaintext identifiers in application logs, a leak exposes everyone who was ever verified. Ask these questions in advance: which stores hold plaintext, who can read them, how long they keep it, and how fast you could list the affected people. A short runbook that answers them is worth more than a long policy nobody has read. StampMitra's incident and breach notification procedure describes its own process.

Checklist

1. Operational logs and audit records are separate, with different retention and access.
2. The audit record uses the minimal schema, with referenceId, masked subject, decision, reasons and policy version.
3. Full PANs, account numbers and response bodies are not in operational logs.
4. Hashes for matching are keyed (HMAC), with the key outside the database.
5. Audit rows are append-only, with overrides as new rows and a reason on each.
6. Retention periods are written down, approved by the compliance owner and enforced by a job that respects legal holds.
7. Erasure requests have a documented process that separates what is deleted from what must be kept.
8. Access to audit records is limited and logged.
9. Redaction filters are installed in loggers, error trackers and proxies.
10. A monthly reconciliation compares your record count with the platform's usage summary.
11. A report query exists that produces the audit evidence for one subject.
12. The platform's own log retention for your plan is known, and anything needed beyond it is exported.

Common mistakes

• Using one log stream as both debugging aid and audit evidence.
• Logging full request and response bodies "temporarily" and leaving it on.
• Hashing identifiers with an unkeyed hash that can be reversed by guessing.
• Storing the whole response so as to "have everything", and then holding names, addresses and director details nobody has a purpose for.
• Overwriting a record when a decision changes instead of adding a new row.
• Re-running a verification to answer an auditor, replacing the evidence with today's answer.
• Assuming the dashboard's request logs are an archive, when retention depends on your plan.
• Copying a retention period from a blog post, including this one, instead of setting it with compliance.
• Letting an API key into a log line, a screenshot or a ticket.
• Mixing sandbox records with production evidence, so a sample result is mistaken for a real check.

What to do next

Start by writing the minimal record schema and the masking helpers, since everything else hangs on them. Then install the redaction filters before the next deployment. Decide the retention table with your compliance owner. For the checks that produce the records, read Building a vendor onboarding flow and KYC vs KYB. For what to do about stale or disputed results, read why API results can differ from the government portal. The quickstart gets you a sandbox key. A PAN lookup is ₹5 per call and a bank account check is ₹4 per call on pay-as-you-go, which is a reminder that each record corresponds to a billable call; see the pricing page. Questions go to support.

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"
  }
}

Frequently asked questions