DEV Community: Iurii Rogulia

What an MVP Actually Costs

Iurii Rogulia — Mon, 31 Aug 2026 10:01:01 +0000

You've decided to build the thing. You send the same brief to three developers, and the quotes come back thousands apart. One is a fraction of the others, and it's tempting to read that as the same product for less money.

It almost never is.

The cheapest quote is rarely the same work done cheaper. It's a different, smaller amount of work — one that produces something that demos well and falls apart the moment real customers touch it. The gap between the quotes isn't margin. It's the corners the cheap one is quietly cutting, and you're the one who pays to un-cut them later.

So before you pick a number, it's worth understanding what actually drives the cost of an MVP — and, more importantly, where cutting cost is smart and where it's a trap.

Where the Cost Actually Comes From

An MVP is not a pile of features priced by the unit. Most of the real cost sits in a few places founders don't see on the surface.

Scope. The single biggest driver, and the one most under your control. Every screen, every "while we're at it," every integration adds time. This is where a good builder earns their fee — by talking you out of things.
Data model. How your information is structured underneath. It's invisible in the demo and expensive to change after launch. Getting it roughly right early is cheap. Getting it wrong is a rebuild.
Correctness where it matters. Login that can't be bypassed, payments that charge the right amount, tax handled properly. This is careful, boring work, and it's a large part of any honest estimate.
The unglamorous 30%. Error handling, edge cases, the states nobody screenshots. A demo skips all of it. A product that survives contact with customers can't.

A cheap quote usually gets there by shrinking the last three. The scope looks the same on paper. What's missing is everything that doesn't show up in a five-minute walkthrough.

The Cheap MVP That Becomes an Expensive Rebuild

Here's the pattern I've watched play out more than once.

A founder pays for a fast, cheap build. It demos beautifully. The first users arrive. Then the bill for the corners comes due: two customers get charged twice because the payment flow was never made safe against a double-click. The data model can't represent a customer belonging to two companies, so a whole feature is impossible without restructuring the foundation. Nobody's logged out properly, so one account can see another's data.

None of these are visible in the demo. All of them surface in production, in front of real, paying, unhappy customers.

Now you rebuild — except it's worse than starting fresh, because you're also migrating live customer data, keeping the broken thing running, and rebuilding trust you already spent. The "savings" from the cheap quote get repaid with interest, plus the revenue you lost while the product was on fire.

The cheapest quote didn't save money. It moved the cost forward in time and made it larger. That's the trap.

What's Safe to Cut

Cutting scope is not the enemy. It's the whole point of an MVP — the minimum viable is right there in the name. The skill is cutting the right things.

Safe to cut, almost always:

Nice-to-have features. The admin dashboard, the settings nobody's asked for yet, the second onboarding flow. If a spreadsheet or a manual step gets you through the first three months, use the spreadsheet.
Polish that isn't load-bearing. Animations, a second theme, edge-case screens for situations you haven't hit yet.
Scale you don't have. Building for a million users when you have zero is paying today for a problem you'd be lucky to have.
Reversible decisions. Anything you can change later without touching the foundation is safe to defer. Ship the plain version, learn, then improve.

Cutting these isn't cheapness. It's focus. Every one of them can be added later without tearing anything down — which is exactly what makes them safe.

slug="mvp-development"
text="The hard part of an MVP isn't building features — it's deciding which ones don't get built yet. I help founders cut the deferrable scope hard while protecting the parts that are expensive to fix later."
/>

What You Must Never Cut

Then there's the short list of things where cutting cost doesn't save money — it just borrows it at a punishing rate. These are the load-bearing foundations. Skimp here and you don't get a cheaper MVP; you get a delayed rebuild.

Authentication and access control. Who can log in, and what each account is allowed to see and do. Get this wrong and one customer sees another's data — the kind of incident that ends a young product. This is not a feature to bolt on later. It shapes everything above it.
Payment correctness. If you take money, the amounts must be right, charges must not fire twice, refunds must actually refund, and tax must be handled properly. I once built a whole SaaS billing layer from scratch — mandates, proration, dunning, EU VAT — because payment correctness isn't optional the moment real money moves. A payment bug isn't a bug report. It's a chargeback, a furious customer, and sometimes a legal problem.
The data model. The structure your information lives in. This is the one thing that's genuinely hard to change after launch, because by then it's full of real customer data. You don't need the final version. You need one that won't have to be demolished when you add the second obvious feature. A little thought here at the start is the cheapest insurance you'll ever buy.

Notice what these have in common: they're all invisible in a demo and ruinously expensive to fix after customers arrive. That's exactly why a cheap quote is happy to shave them, and exactly why you shouldn't let it.

How to Read the Quotes

You don't need to evaluate the code to avoid the trap. You need to ask what the cheap number is leaving out. A few questions do most of the work:

How are payments made safe against double-charging and failure? A confident, specific answer means they've thought about it. A shrug means you're paying for the fix later.
What happens when the data model needs to change after launch? You want to hear that it's been designed to grow, not that "we'll deal with it then."
What's explicitly not in this scope? The best answer is a builder who has already cut things and can tell you exactly what and why. Silence here is the cheap quote hiding its corners.

A quote that's cheap because it cut nice-to-haves is a good deal. A quote that's cheap because it cut authentication, payment correctness, or a sane data model is a loan against your future — one you'll repay as a rebuild, at the worst possible time, in front of your first real customers.

The right MVP spends nothing on what you can add later, and refuses to save money on what you can't. That's the line worth paying for.

If you're staring at two quotes that are thousands apart and can't tell which corners the cheap one is cutting, that's a conversation worth having before you sign. Let's read them together.

Vendor Bank Account Change Fraud: Detect the Forged Bank-Letter PDF

Iurii Rogulia — Mon, 31 Aug 2026 10:00:40 +0000

Originally published at htpbe.tech. The version on htpbe.tech stays in sync with the latest detection algorithm — refer to it for the canonical text.

A supplier you already pay sends an email: their bank has changed, please update the remittance details. Attached is a PDF on bank letterhead — an “updated banking details” confirmation, or a voided check, or a signed account-verification letter. Your AP analyst calls the number on file, the contact confirms, the change goes into the vendor master. Three weeks later the real supplier asks where their money went. It went to the fraudster’s account, and the PDF that authorized the change was edited after the bank issued it.

This is vendor bank account change fraud, and it sits in a blind spot that callback procedures do not cover. The controls every AP team runs — phone confirmation, email approval, a second signer — test whether the request is plausible. None of them test whether the document attached to the request was modified after it was created. HTPBE reads the submitted PDF’s structure and returns a verdict on exactly that question.

This is not BEC invoice fraud — it’s the vendor master

It is worth separating two frauds that get lumped together, because the document, the moment of attack, and the control gap are different.

Business email compromise invoice fraud targets a single payment. The fraudster intercepts or spoofs a real invoice, swaps the remittance bank account in the PDF, and sends it through a compromised or look-alike email thread. The damage is one invoice. We cover that case in detail in BEC invoice fraud detection and the broader invoice fraud in accounts payable playbook.

Vendor bank account change fraud is upstream of any invoice. It targets the vendor master record itself. Instead of editing one invoice, the fraudster changes the standing bank details attached to a supplier, so that every future payment to that vendor — this month’s and next year’s — routes to the attacker. The supporting document is not an invoice. It is a bank-issued confirmation: a letter from the supplier’s bank, a voided check, an account-ownership letter, a SEPA or ACH mandate. One forged PDF can redirect a payment relationship worth millions over its lifetime.

Same forensic question (was this PDF edited after issue?), different document and different point in the workflow. Treat them as two checks at two gates: one at invoice intake, one at any vendor bank-detail change.

The economics make the vendor-master version the more dangerous of the two. A redirected invoice loses you one payment, and the discrepancy often surfaces fast — the supplier chases the unpaid invoice within the payment cycle. A redirected vendor master loses you every payment until someone notices, and the discrepancy can hide for months, because the legitimate supplier keeps invoicing and you keep paying — just to the wrong account. By the time the real vendor escalates a string of “missing” payments, several cycles of money may already be gone and unrecoverable. The forged bank letter at the change gate is a higher-leverage target for the fraudster, which is exactly why it deserves a dedicated check.

Why AP controls miss the forged bank letter

Standard vendor-change controls are built around social-engineering resistance, and they are good at it:

Callback verification — call the supplier on a number from the master record, not from the request email.
Email confirmation — require written sign-off from a known contact.
Dual approval — a second person authorizes the master-data change.
Change-notification holds — freeze the first payment after any bank-detail change for a cooling-off window.

Every one of these evaluates the request. Did a believable person ask, through a believable channel, with a believable reason? A determined fraudster can pass all four. Compromised supplier inboxes mean the callback reaches a number the attacker controls. Spoofed look-alike domains satisfy the email check. And the attached bank letter is, to the human eye, perfect: real letterhead, real account-holder name, a plausible new account number, a signature, a date.

What no control in that list does is open the PDF and ask how it was built. The analyst reads the document; they do not examine the file structure underneath it. That structure is where the edit lives. A genuine bank confirmation comes out of the bank’s own system — a core-banking platform, a statement generator, an institutional document service. A forged one is a real bank letter that someone opened in a desktop or online PDF editor, changed the account number on, and re-saved. The save operation rewrites the file in ways the bank’s system never would, and those changes survive email and stay in the bytes you receive.

There is a reason this gap is structural rather than a training problem you can fix with a sharper analyst. A human reviewer is matching the document against business context: is this a supplier we know, is the contact someone we recognize, does the new account look like a normal account. All of that lives at the content level — the words and numbers on the page. The evidence of tampering does not live on the page. It lives in the file’s internal structure: which software wrote it, how many times it was saved, and what its internal timestamps say about when it was made versus when it was last changed. You cannot see that by reading the letter more carefully, because it is not in the letter. It is underneath the letter, and reading it requires parsing the PDF’s structure — which is exactly what an automated check does and a manual review cannot.

What the fraudster changes, and what it leaves behind

The visible change is small: an account number, a sort code or routing number, sometimes the account-holder name. Visually it is indistinguishable from the genuine field. The act of making that change, though, leaves structural evidence inside the PDF. Described in plain terms, without a how-to:

The software that generated the file stops matching the issuer. Every PDF records which software produced it. A bank’s confirmation letter carries the fingerprint of the bank’s institutional system. When a fraudster opens that letter in a consumer or online editor and saves it, the file now carries the editor’s identity instead of — or alongside — the bank’s. An institutional bank letter that reports it was last saved by a free online PDF tool did not come from the bank that way.

The document gains an edit history it should not have. A PDF issued once by an automated system is a single clean generation. Editing and re-saving appends a new revision layer to the file; the file now records that it was created, then changed, then saved again. Multiple revision layers on a document that claims to be a freshly issued bank confirmation mean it was reopened and altered after issue.

Internal timestamps disagree. A document carries an internal record of when it was created and when it was last modified. On a genuine one-shot bank letter these are effectively the same moment. When the modification record postdates the creation record, the file is telling you it was edited after it was made — on a bank confirmation, after the bank issued it.

A signed letter shows changes after signing, or a missing signature. Some bank confirmations carry a digital signature. If the content was altered after that signature was applied, the file records that the signed region no longer matches what is on the page. In other cases the original carried a signature that the fraudster’s save operation stripped, leaving the residue of a signature that was removed.

The account number itself was overlaid. Sometimes the fraudster does not rebuild the page — they patch a single field, dropping a new account number on top of the original using a desktop editor. That targeted character-level overlay is a different fingerprint from a full re-save, and it points straight at the field that was changed.

None of these require the original document. HTPBE compares the submitted file against how genuinely issued institutional documents are constructed — not against a copy you do not have.

What the API returns on a forged bank-change letter

HTPBE is a two-step call. You POST the PDF’s URL to /v1/analyze and get back an id; you GET /v1/result/{id} for the verdict. The result is a flat object — a status, the named modification_markers, and a modification_confidence of certain, high, or none. There is no numeric risk score; the markers name what was found.

Here is a representative result on a vendor bank-change letter. The supplier’s genuine bank confirmation was opened in a desktop editor, the IBAN was swapped to an attacker-controlled account, and the file was re-saved before being attached to the change request:

{
  "id": "ck_4f2a9c1e-7b3d-4e8a-91c2-0d6e5f8a7b34",
  "status": "modified",
  "modification_confidence": "certain",
  "modification_markers": [
    "HTPBE_DATES_DISAGREE",
    "HTPBE_EDITING_TOOL_FINGERPRINT",
    "HTPBE_MULTIPLE_REVISION_LAYERS",
    "HTPBE_CHARACTER_OVERLAY_EDIT"
  ],
  "creator": "Institutional Banking Platform",
  "producer": "Desktop PDF Editor",
  "has_digital_signature": false,
  "creation_date": 1755302400,
  "modification_date": 1755734400
}

Read it in business terms. HTPBE_DATES_DISAGREE — the file’s own modification timestamp postdates its creation timestamp; the letter was edited five days after it was made. This is the strongest marker present, and it produces certain confidence: the document is internally inconsistent about its own age in a way that a one-shot bank letter never is. HTPBE_EDITING_TOOL_FINGERPRINT — the file carries the fingerprint of a known desktop PDF editing tool, which has no place in a bank’s issuance pipeline. HTPBE_MULTIPLE_REVISION_LAYERS — the document was generated, then modified, then saved again, rather than issued once and untouched. HTPBE_CHARACTER_OVERLAY_EDIT — a targeted character-level overlay sits on the page, the signature of a single field patched rather than the whole document rebuilt.

The verdict is modified with certain confidence. In practice that is a routing signal: hold the vendor-change request, do not commit it to the master, and escalate to a verified out-of-band confirmation with the bank or the supplier’s known finance contact — through a channel the fraudster cannot have compromised. The forensic check produces evidence; your vendor-management policy decides the action.

Other documents in the same workflow throw different combinations. A signed account-verification letter altered after signing surfaces HTPBE_POST_SIGNATURE_EDIT; one whose signature was stripped surfaces HTPBE_SIGNATURE_REMOVED. A letter whose institutional generator identity was deliberately spoofed to look like it came from the bank surfaces HTPBE_PRODUCER_IDENTITY_FORGED. You route on the verdict, not on memorizing which marker means what.

What inconclusive means here — and why it is still useful

A third verdict matters as much as modified. If the submitted PDF was built in consumer software — written in Word, exported from a browser, printed to PDF — HTPBE returns inconclusive. The file was assembled by a tool that does not preserve the structural history needed to prove the document is intact. That is not a detector failure. It is information.

For a vendor bank-detail change, inconclusive is a red flag in itself, because of what you expected. A real bank does not send your supplier’s confirmation as a Word document or a print-to-PDF. If you asked for a bank-issued confirmation of a new account and the file comes back inconclusive because it was produced in a word processor, the document is not what it claims to be — regardless of whether anyone tampered with it afterward. Treat inconclusive on a document that should be institutionally issued the same way you treat a missing document: insufficient to authorize a change. Route it to the same manual-verification queue as modified, for a different reason.

intact is the only verdict that lets a bank-change request proceed on the document’s own merits — and even then your callback and dual-approval controls still apply. HTPBE removes one specific failure mode (a forged or tampered file passing as genuine); it does not replace the rest of your process.

Honest limits: what this check does not do

Structural PDF forensics answers one question — was this file modified after it was created, and does its construction match a genuine institutional issuer? It is decisive on that question and silent on others. Be clear about the boundary:

It does not validate the account. HTPBE cannot tell you whether the IBAN on an intact letter actually belongs to your supplier. A document can be structurally pristine and still name the wrong account if the fraud happened before the PDF was generated. Confirmation-of-payee and bank-account-verification services answer that question; HTPBE answers a different one. Run both.
It does not catch a born-forged document. If a fraudster builds a fake bank letter from scratch in a tool that issues clean, single-generation files — never editing an original — there is no post-creation edit to detect. The file may be entirely fabricated yet structurally consistent. That is why inconclusive matters: a fabricated letter built in consumer software lands there, and a fabricated letter that claims an institutional origin it cannot back up surfaces an identity-forgery marker. But a clean synthetic letter is the boundary of what structural analysis sees, and we say so plainly.
It does not verify content truth. HTPBE does not read the letter and decide whether the sort code is real or the signatory is authorized. It checks the file’s integrity, not the facts it asserts.

The value is that the largest category in practice — a real bank document edited to swap an account number — is exactly what structural forensics catches cold, and it is exactly the category callbacks and dual approval cannot see.

Integrating the check into vendor onboarding and change requests

The check belongs at two gates: new-supplier onboarding (when the first bank details are captured) and any subsequent bank-detail change request. In both cases the trigger is the same — a supporting document arrives that will authorize where money goes. Run the check before the change touches the vendor master.

Three steps:

Capture the document at intake. When a supplier-onboarding form or a bank-change request comes in with a PDF, store the file and obtain a URL the API can fetch.
Call HTPBE before committing the change. One synchronous analyze-and-result call per document. Gate the master-data update on the verdict.
Route on the verdict. modified and inconclusive go to a manual-verification hold; intact proceeds into your existing callback and dual-approval flow.

import requests

API = "https://api.htpbe.tech/v1"
HEADERS = {"Authorization": f"Bearer {HTPBE_API_KEY}"}

def check_bank_change_doc(pdf_url: str, vendor_id: str) -> dict:
    # Step 1: submit the PDF for analysis
    submit = requests.post(
        f"{API}/analyze",
        headers=HEADERS,
        json={"url": pdf_url},
        timeout=15,
    )
    submit.raise_for_status()
    check_id = submit.json()["id"]

    # Step 2: retrieve the verdict
    result = requests.get(
        f"{API}/result/{check_id}",
        headers=HEADERS,
        timeout=15,
    ).json()

    # Persist the check_id against the vendor record for audit
    log_vendor_change_check(vendor_id, check_id, result["status"])

    status = result["status"]
    if status == "modified":
        hold_bank_change(vendor_id, result["modification_markers"])
    elif status == "inconclusive":
        # Bank confirmation should be institutionally issued, not built in
        # consumer software — treat as insufficient to authorize a change.
        hold_bank_change(vendor_id, ["non_institutional_origin"])
    # status == "intact": continue into callback + dual-approval flow

    return result

Store the id against the vendor master record. If a payment to that supplier is later disputed or clawed back, the forensic report is retrievable as a permanent audit trail showing exactly which structural signals triggered — or did not trigger — the hold. That record matters for internal investigation, for insurance claims on a fraudulent-payment loss, and for any dispute with the bank.

The full request and response reference, error codes, and the test scenarios that return synthetic deterministic results are on the API page. The broader accounts-payable workflow — where this check sits alongside invoice intake and altered expense-receipt detection — is laid out on the accounts-payable use-case page. Volume pricing for vendor-management platforms and shared-service centers processing thousands of onboarding and change documents a month is on the pricing page.

Who should run this check

If you own vendor master data, supplier onboarding, or procurement fraud controls, this is your gap. The personas who feel it most directly:

Accounts payable and shared-service leads who process supplier bank-detail changes and have watched a callback-verified change still turn out to be fraud.
Procurement and vendor-management teams standing up onboarding for new suppliers, where the first bank details are captured from a document you have no prior record of.
Finance fraud and controls functions building a defense-in-depth program around payments — structural document forensics is the layer that sits under callbacks and dual approval, checking the artifact those controls trust.
Developers on procure-to-pay, vendor-management, or onboarding platforms who want to embed a per-document integrity check at the bank-detail gate. The API is self-serve: a key, two calls, a verdict.

Callbacks confirm that someone asked for the change. Dual approval confirms that two people signed off. Neither confirms that the bank letter authorizing the new account was not edited after the bank issued it. That last question is the one a forged-PDF fraudster is counting on you not to ask — and it is the one HTPBE answers from the file’s own bytes.

VIES Uptime, Measured — 28 Member States, One Sample Every 15 Minutes

Iurii Rogulia — Mon, 31 Aug 2026 09:00:43 +0000

Originally published at vatnode.dev. The version on vatnode.dev is the canonical source — refer to it for the latest content.

{/*
RECOMPUTE BEFORE PUBLISHING — every figure below comes from one script run.

python3 vies-report.py > report.txt

Numbers currently in this file are from a 5-day window (2026-08-06 → 2026-08-11),
548 samples per state. They must be replaced with the 30-day run taken on or
after 2026-09-06. Figures to update, in order of appearance:

description frontmatter ......... aggregate availability
"What we measure" ............... window length, samples/state, total samples
Chart 1 ......................... full block, paste verbatim from script
aggregate + zero-miss count ..... paragraph under Chart 1
Germany section ................. DE %, missed count, hour profile chart
Ireland section ................. IE %, outage window, missed count
Latvia section .................. LV %, hour profile chart, missed count
"What this does not measure" .... window length restated

If a claim is not in the script output, it does not belong in this post.
*/}

The European Commission runs an endpoint that reports whether each member state's VAT validation backend is reachable right now. It answers "is Germany up". It keeps no history, so it cannot answer the question that actually changes your code: "is Germany reliably down at the time my nightly job runs".

So we started sampling it every 15 minutes and keeping every sample. This is what the 28 member states look like once you have history.

The aggregate number is useless

Across every member state and every sample, VIES was available 98.71% of the time.

That number is true and it is worthless. Nothing in your system consumes "VIES". Your system consumes Germany, or Ireland, or Latvia, and those three behave nothing like each other and nothing like the average.

What we measure

Source: the Commission's own GET /taxation_customs/vies/rest-api/check-status, which returns a per-country availability string.
Interval: one sample per member state every 15 minutes, 96 per state per day.
Coverage: 28 codes — the EU-27 plus XI (Northern Ireland). Greece appears as EL, following VIES rather than ISO 3166.
Window in this post: 5 days, 548 samples per state, 15,344 samples total.
Rule: only the literal string Available counts as up. Every other state the Commission reports — including strings we have not seen before — counts as down rather than being silently dropped.

Two caveats before the charts. They bound everything that follows.

This is the Commission's self-report, not an independent probe. It is what VIES believes about its own member states. It can disagree with what an actual checkVat call does, and it can lag a member state going down.

And the history is short. Five days is enough to establish a pattern that repeats daily. It is not enough to claim an annual uptime figure, and this post does not.

Availability by member state

DE  ████████████████████████░░░░   83.94%     88 missed
LV  █████████████████████████░░░   88.87%     61 missed
IE  ███████████████████████████░   95.44%     25 missed
BE  ████████████████████████████   98.91%      6 missed
MT  ████████████████████████████   98.91%      6 missed
EE  ████████████████████████████   99.45%      3 missed
IT  ████████████████████████████   99.64%      2 missed
RO  ████████████████████████████   99.64%      2 missed
CZ  ████████████████████████████   99.82%      1 missed
DK  ████████████████████████████   99.82%      1 missed
NL  ████████████████████████████   99.82%      1 missed
PT  ████████████████████████████   99.82%      1 missed
SE  ████████████████████████████   99.82%      1 missed
AT  ████████████████████████████  100.00%      0 missed
BG  ████████████████████████████  100.00%      0 missed
CY  ████████████████████████████  100.00%      0 missed
EL  ████████████████████████████  100.00%      0 missed
ES  ████████████████████████████  100.00%      0 missed
FI  ████████████████████████████  100.00%      0 missed
FR  ████████████████████████████  100.00%      0 missed
HR  ████████████████████████████  100.00%      0 missed
HU  ████████████████████████████  100.00%      0 missed
LT  ████████████████████████████  100.00%      0 missed
LU  ████████████████████████████  100.00%      0 missed
PL  ████████████████████████████  100.00%      0 missed
SI  ████████████████████████████  100.00%      0 missed
SK  ████████████████████████████  100.00%      0 missed
XI  ████████████████████████████  100.00%      0 missed

15 of 28 member states missed nothing at all. Of the 198 unavailable samples in the whole dataset, 174 belong to three countries. The distribution is not a bell curve with a long tail. It is a handful of specific backends with specific problems, and everyone else is fine.

Which means the useful question is never "how reliable is VIES". It is "what does this member state do, and when".

Germany: switched off every night

DE
  00:00  ░░░░░░░░░░░░░░░░░░░░░░░░    0.00%  n=24
  01:00  ████████████████████████  100.00%  n=22
  02:00  ████████████████████████  100.00%  n=23
  03:00  ████████████████████████  100.00%  n=23
  04:00  ████████████████████████  100.00%  n=24
  05:00  ████████████████████████  100.00%  n=24
  06:00  ████████████████████████  100.00%  n=23
  07:00  ████████████████████████  100.00%  n=24
  08:00  ████████████████████████  100.00%  n=23
  09:00  ████████████████████████  100.00%  n=22
  10:00  ████████████████████████  100.00%  n=24
  11:00  ████████████████████████  100.00%  n=25
  12:00  ████████████████████████  100.00%  n=23
  13:00  ████████████████████████  100.00%  n=25
  14:00  ████████████████████████  100.00%  n=24
  15:00  ████████████████████████  100.00%  n=24
  16:00  ████████████████████████  100.00%  n=21
  17:00  ████████████████████████  100.00%  n=20
  18:00  ████████████████████████  100.00%  n=20
  19:00  ████████████████████████  100.00%  n=20
  20:00  ████████████████████████  100.00%  n=20
  21:00  ███████░░░░░░░░░░░░░░░░░   27.27%  n=22
  22:00  ░░░░░░░░░░░░░░░░░░░░░░░░    0.00%  n=24
  23:00  ░░░░░░░░░░░░░░░░░░░░░░░░    0.00%  n=24

Germany is available in every single sample between 01:00 and 20:00 UTC, and unavailable in every single sample between 22:00 and 00:59 UTC. The 21:00 hour is the boundary: 27% available, so the window opens somewhere around 21:40 UTC.

That is roughly 21:40–01:00 UTC, and it occurred on all five nights — weekends included. Germany's 83.94% is not flakiness. It is a scheduled shutdown, and it is the single largest contributor to the aggregate.

We do not know why. The Commission's endpoint reports state, not reason, and we found no published maintenance calendar for it. What matters for your code is that the window is predictable, and predictable downtime is the easy kind.

Ireland: one outage, one block

Ireland's misses are not spread out. Every one of them falls inside a single contiguous stretch: Monday 22:00 UTC through Tuesday 04:00 UTC, unavailable in every sample from 23:00 to 03:59, partially available at the two edges. Outside that block, Ireland missed nothing.

Six hours, once, in five days. That is 95.44%, and it is a different failure from Germany's. Nothing about Monday night predicts next Monday night. An unplanned outage looks like a step function and then it is over.

If you build a retry schedule from Ireland's 95.44%, you will build the wrong thing. The number describes an event, not a rhythm.

Latvia: degrades under load

LV
  00:00  ████████████████████████  100.00%  n=24
  01:00  ████████████████████████  100.00%  n=22
  02:00  ████████████████████████  100.00%  n=23
  03:00  ████████████████████████  100.00%  n=23
  04:00  ████████████████████████  100.00%  n=24
  05:00  ████████████████████████  100.00%  n=24
  06:00  ████████████████████████  100.00%  n=23
  07:00  ████████████████████████  100.00%  n=24
  08:00  ████████████████████████  100.00%  n=23
  09:00  ████████████████████░░░░   81.82%  n=22
  10:00  █████████████████████░░░   87.50%  n=24
  11:00  ██████████████████████░░   92.00%  n=25
  12:00  █████████████████░░░░░░░   69.57%  n=23
  13:00  ██████████████████░░░░░░   76.00%  n=25
  14:00  █████████████░░░░░░░░░░░   54.17%  n=24
  15:00  ████████████░░░░░░░░░░░░   50.00%  n=24
  16:00  ███████████░░░░░░░░░░░░░   47.62%  n=21
  17:00  ██████████████████████░░   90.00%  n=20
  18:00  ████████████████████████  100.00%  n=20
  19:00  ████████████████████████  100.00%  n=20
  20:00  ████████████████████████  100.00%  n=20
  21:00  ██████████████████████░░   90.91%  n=22
  22:00  ███████████████████████░   95.83%  n=24
  23:00  ████████████████████████  100.00%  n=24

Latvia is clean overnight — every sample from 23:00 through 08:00 UTC came back available — and then falls apart across the working day, bottoming out at 47.62% availability at 16:00 UTC, early evening local time. It never goes fully down for a whole hour and it never stays up for one either.

This is the shape that breaks naive retry code. Germany you route around. Ireland you wait out. Latvia will answer if you ask again in ten minutes, and it will refuse if you ask again in ten seconds — but a fixed exponential backoff cannot tell those apart, so it burns its whole budget inside the same degraded minute and gives up.

Three states, three failure modes, one aggregate number covering all of them.

What VIES actually returns when it fails

Availability is only half the problem. The other half is that the SOAP API's failure modes are underdocumented, and several of them are not really failures.

The fault strings are the useful part. VIES answers a failed checkVat with a SOAP fault whose faultstring is a bare code. MS_UNAVAILABLE means that one member state is down. SERVICE_UNAVAILABLE means the Commission's own gateway is. MS_MAX_CONCURRENT_REQ and GLOBAL_MAX_CONCURRENT_REQ are rate limits, per-state and global. INVALID_INPUT is a malformed number. Treating these as one generic error throws away every signal you need: three of them say "retry later", one says "retry somewhere else", one says "never retry this".

Not every fault is a code. Pass a requester country that is not an EU member state and production VIES answers with a human-readable Invalid Requester member state instead of a documented code. Pass an invalid requester VAT under a valid country and you get the exact INVALID_REQUESTER_INFO string. Same class of error, two different response formats, and only one of them is in the docs. If you match on exact codes only, the first one falls through to your generic 502 handler.

--- is not an address. VIES fills unavailable name and address fields with a literal three-hyphen placeholder. It is a string, it is truthy, and it will end up rendered in your UI and stored in your database as a company name unless you normalise it to null.

checkVat and checkVatApprox disagree about field names. The plain call returns name and address. The approx call returns traderName, and an address that may arrive flat as traderAddress or split across traderStreet, traderPostcode and traderCity. Same data, three shapes, depending on the member state.

A mandatory field can be empty. checkVatApprox returns a requestIdentifier — the consultation number, the Commission-issued evidence that a check took place, the thing you keep next to the invoice when a tax authority asks you to prove you validated a customer. The schema declares it mandatory. It is also schema-legal to return it as an empty string. A response can therefore be simultaneously valid, successful, and useless as evidence. Fail loudly on that rather than storing the empty string and finding out during an audit.

Why national registers are a worse fallback than they look

The obvious move when a member state's VIES node is down is to ask that country's own register directly. It works, but only for some countries, and the reason is not technical.

A national VAT register and a national company register answer different questions. Poland's MF, Romania's ANAF and the Czech ARES dic status expose the VAT register itself — asking them "is this VAT number registered" gets you the same answer VIES would have given. Those are real fallbacks.

Finland's PRH, France's SIRENE, Denmark's CVR, Sweden's Bolagsverket, the Dutch KVK, the Belgian CBE are company registers. A company can be listed and active there without being VAT-registered at all — below the threshold, on a small-business exemption, or exempt by activity. Some of them exclude sole traders entirely. Deriving valid: true from "the company exists in the register" produces false positives precisely when you are least able to check them, which is during an outage. We use those sources to enrich a result, never to decide one.

Germany is the interesting case. The BZSt runs eVatR, which looks like the answer to Germany's nightly window. It is not: it only answers a German business asking about a foreign VAT number. Confirming a German number through it requires an entitlement we do not hold, and every request we made returned evatr-0006, not authorised. Germany's nightly window has no fallback. You wait, or you queue.

What to do with this

Track availability per country, not globally. A single circuit breaker in front of VIES opens because Latvia is having an afternoon and stops you from validating the other 27.
Do not schedule German validation between 21:00 and 01:00 UTC. If your nightly batch runs at midnight UTC, it currently fails every German number, every night, and the fix is a cron expression.
Make backoff per-country and jittered. Latvia's shape needs minutes of spacing, not seconds. Retrying four times in ninety seconds is four failures.
Distinguish "unavailable" from "invalid". They are different words in the response and they must be different words in your database. A number that could not be checked is not a number that failed the check — and treating an outage as an invalid VAT ID is how you accidentally charge a B2B customer domestic VAT.
Queue, don't block. Nothing in a checkout flow should sit on a synchronous call to a service that is switched off for three hours a night.

What this does not measure

The limits, plainly:

It is the Commission's self-report. We sample what VIES says about its member states, not what a checkVat call returns. An independent probe would be a stronger instrument, and it is the obvious next thing to build.
The window is 5 days. Long enough to establish that Germany's window repeated on every night observed. Not long enough for a monthly or annual figure, and we make no such claim.
Ireland's 95.44% is one event. A single six-hour outage in a short window produces a percentage that looks like a reliability rating and is not one. The same is true in reverse for the 15 states at 100%: five clean days is not a guarantee.
Availability is not correctness. A member state can be up and still return a stale or wrong answer. We do not measure that here.

Reproduce it

The data behind every chart is public and unauthenticated:

curl -s https://api.vatnode.dev/v1/vies-status | jq '.uptime'

That returns the per-country uptime, the sample counts, and the weekday × hour heatmap the charts are built from. There is a rendered version at vatnode.dev/vies-status, updated continuously, and the underlying Commission endpoint is at ec.europa.eu/taxation_customs/vies/rest-api/check-status if you would rather sample it yourself.

The first chart in this post is the whole of this script, standard library only:

import json, urllib.request

url = "https://api.vatnode.dev/v1/vies-status"
data = json.load(urllib.request.urlopen(url))

for u in sorted(data["uptime"], key=lambda u: u["uptime30d"] or 0):
    up = u["uptime30d"] or 0
    filled = round(up * 28)
    missed = round(u["sampleCount"] * (1 - up))
    print(f"{u['countryCode']}  {'█' * filled}{'░' * (28 - filled)}"
          f"  {up * 100:6.2f}%  {missed:>4} missed")

The hour-of-day charts come out of the same document: data["countryHeatmaps"]["DE"] is a list of weekday × hour cells, each with an availability fraction and a sample count. Group by hourUtc, weight each cell by its samples, and you have the German profile above.

If you want the retry and fallback behaviour described here without building it, that is what vatnode does.

Structured Logging in Next.js with Pino (Request IDs to stdout)

Iurii Rogulia — Fri, 28 Aug 2026 10:00:59 +0000

A request failed in production at 02:14 and the only thing you have is console.log("error", err) somewhere in a route handler. You cannot tell which user hit it, which path, how long it took, or whether the three log lines you found even belong to the same request. That is the situation structured logging exists to prevent.

I run this site on a self-hosted VPS with Coolify — no platform log aggregation doing the work for me. Every request produces one JSON line on stdout, carries an ID I can grep for, and never prints a secret. This is the exact setup, straight from the codebase — not a toy example.

Why Structured, Not Strings

console.log gives you strings. Strings are fine until you need to answer a question like "show me every 500 on /api/contact in the last hour that took over a second." You cannot query a string. You end up writing fragile regexes against your own log format.

Structured logging means every log line is a JSON object with named fields:

{
  "level": "info",
  "time": "2026-08-21T00:14:03.921Z",
  "pid": 42,
  "service": "http",
  "requestId": "a1f3...",
  "method": "POST",
  "path": "/api/contact",
  "status": 200,
  "ms": 84,
  "msg": "[iurii.rogulia.fi] POST /api/contact 200 84ms"
}

Now the question is a filter: level=error AND path="/api/contact" AND ms>1000. Any log processor — jq locally, or a hosted backend if you add one later — can answer it. The msg field stays human-readable so you can also just eyeball the stream during development.

The point isn't the tool. It's the shape. Decide on your fields once, emit them everywhere, and every future question becomes a query instead of an archaeology project.

The Logger

Pino is a fast JSON logger for Node. The whole configuration is nine lines:

// lib/logger.ts
import pino from "pino";

export const logger = pino({
  level: process.env.LOG_LEVEL ?? "info",
  base: { pid: process.pid, service: "http" },
  msgPrefix: "[iurii.rogulia.fi] ",
  timestamp: pino.stdTimeFunctions.isoTime,
  formatters: { level: (label) => ({ level: label }) },
});

Every choice here earns its place:

level from an env var — default info, but I can drop to debug in one deploy without touching code. Levels below the current one are compiled out, so logger.debug() calls cost almost nothing in production.
base adds pid and service to every line automatically. In a multi-process or multi-service setup you can tell log streams apart without threading the value through every call.
msgPrefix tags the human-readable message. Useful when the same log backend collects several apps.
timestamp: isoTime writes ISO-8601 with a Z suffix instead of pino's default epoch milliseconds. Machine-sortable, timezone-unambiguous, and it matches what I'd want to paste into an incident timeline.
formatters.level logs the level as its string label ("info", "error") instead of pino's default numeric code. I'd rather read level:"error" than memorize that 50 means error.

Pino writes to stdout. That's deliberate — in a container, the application should not care where logs go. It writes lines to stdout, and the platform (Docker, Coolify, whatever collects the stream) decides on rotation, shipping, and retention. The twelve-factor rule holds: treat logs as an event stream, not a file the app manages.

One ID Per Request

A single request touches middleware first, then a route handler. If each of those logs independently with no shared identifier, you cannot reconstruct what happened. The fix is a request ID minted once and propagated.

In Next.js 16, middleware lives in proxy.ts (renamed from middleware.ts — I covered that migration here). This runs on every matched request:

// proxy.ts
import { NextRequest, NextResponse } from "next/server";
import { randomUUID } from "node:crypto";
import { logger } from "@/lib/logger";

export default function proxy(request: NextRequest) {
  const requestId = request.headers.get("x-request-id") ?? randomUUID();
  const path = request.nextUrl.pathname;
  const ua = request.headers.get("user-agent") ?? "";

  if (!shouldSkip(path, ua)) {
    logger.info(
      {
        requestId,
        method: request.method,
        path,
        ip: getIp(request),
        ua,
      },
      `${request.method} ${path}`
    );
  }

  const res = NextResponse.next();
  res.headers.set("x-request-id", requestId);
  return res;
}

Two things carry the whole design:

Generate or pass through. request.headers.get("x-request-id") ?? randomUUID(). If an upstream proxy or the client already set an x-request-id, we honor it. If not, we mint one. This is what lets an ID survive across service boundaries — a reverse proxy in front, or a client that wants to correlate its own request with your logs, sets the header once and every hop reuses it.

Echo it back. res.headers.set("x-request-id", requestId). The response carries the ID back to the caller. Now a user reporting a bug can hand you the ID from their network tab, and you grep one string to find their exact request. That one behavior turns "it broke sometime this afternoon" into a five-second lookup.

The IP extraction is worth its own function, because behind a proxy request.ip is the proxy, not the user:

function getIp(req: NextRequest): string {
  return (
    req.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ??
    req.headers.get("x-real-ip") ??
    "unknown"
  );
}

x-forwarded-for is a comma-separated chain; the first entry is the original client. Fall back to x-real-ip, then to "unknown" so the field is always present. Never a null field to trip up a downstream query.

Skip the Noise

Logging every request sounds thorough until your log stream is 90% favicon fetches and uptime pings. The skip list keeps signal high:

const UPTIME_UA_RE = /SentryUptimeBot|uptime|healthcheck|pingdom|statuscake|betteruptime/i;

function shouldSkip(path: string, ua: string): boolean {
  if (UPTIME_UA_RE.test(ua)) return true;
  if (path === "/api/health" || path === "/health") return true;
  if (path === "/favicon.ico" || path === "/robots.txt" || path === "/sitemap.xml") return true;
  if (/\.(svg|ico|png|jpg|jpeg|webp|js|css|map|woff2?|ttf)(\?|$)/.test(path)) return true;
  return false;
}

The path-based rules are obvious: static assets, favicon, robots, sitemap — none of these are interesting when you're debugging a real request. The extension regex catches them in bulk, with (\?|$) so a query string doesn't defeat the match.

The user-agent rule is the non-obvious part, and it comes from a real problem. Uptime probes hit real pages. SentryUptimeBot pings /, which is your homepage — you cannot filter it by path without also silencing real visitors. So health checkers get matched by User-Agent instead. Miss this and every 30-second uptime ping becomes a log line, and your actual traffic drowns.

One caveat: filtering by User-Agent is a signal-to-noise decision, not a security control. A UA is trivially spoofed, so this is fine for "stop logging my own monitoring" and wrong for anything that needs to be trustworthy. Keep it in the right category.

Wrap the Route Handlers

Middleware logs that a request arrived. It does not log the outcome — status code and latency are decided inside the route handler, after middleware has already returned NextResponse.next(). For that you wrap the handler:

// lib/with-log.ts
import { logger } from "@/lib/logger";

export function withLog<C>(
  routeName: string,
  handler: (req: Request, ctx: C) => Promise<Response>
): (req: Request, ctx: unknown) => Promise<Response> {
  return async (req: Request, ctx: unknown) => {
    const start = Date.now();
    const requestId = req.headers.get("x-request-id") ?? crypto.randomUUID();
    try {
      const res = await handler(req, ctx as C);
      const ms = Date.now() - start;
      logger.info(
        { requestId, method: req.method, path: routeName, status: res.status, ms },
        `${req.method} ${routeName} ${res.status} ${ms}ms`
      );
      return res;
    } catch (err) {
      const ms = Date.now() - start;
      logger.error(
        { requestId, method: req.method, path: routeName, status: 500, ms, err },
        `${req.method} ${routeName} 500 ${ms}ms: ${(err as Error).message}`
      );
      throw err;
    }
  };
}

Usage is a one-liner around the handler:

// app/api/contact/route.ts
export const POST = withLog("/api/contact", async (req) => {
  // ...handle the request
  return Response.json({ ok: true });
});

What this buys:

Latency on every route. start is captured before the handler runs, ms computed after. You get timing for free on both the success and failure paths.
Errors logged, then re-thrown. The catch logs at error level with the caught err, then throws. It does not swallow the error — Next.js and Sentry still see it and produce the correct 500. The wrapper is an observer, not an owner. Swallowing here would be the classic mistake: a logged error that never reaches your error tracker, so the alert never fires.
The same request ID. withLog reads x-request-id from the request headers — the same header middleware stamped upstream — so the middleware line and the handler line share an ID. ?? crypto.randomUUID() is a defensive fallback for the rare path that doesn't pass through middleware.

There is deliberate duplication here: both proxy.ts and with-log.ts do header ?? randomUUID(). That is not an accident to refactor away. They run in different runtimes — middleware in the edge/proxy layer, the handler in the Node runtime — and coupling them through a shared import to save four lines trades a real boundary for false tidiness. Two honest reads of the same header beat one clever abstraction.

The <C> generic keeps the wrapper type-safe: your handler declares its own context type (route params, for instance), the wrapper accepts unknown from Next.js at the boundary and casts once, inside, where the shape is known.

Never Log a Secret

This is the rule that has no exceptions, and structured logging makes it easier to hold — because you log named fields, not "everything in this object."

The failing patterns are always the same:

// don't
logger.info({ headers: Object.fromEntries(req.headers) }, "incoming"); // Authorization, cookies
logger.info({ body }, "payload"); // passwords, tokens, PII
logger.error({ err, config }, "boom"); // config often holds API keys

The moment you log a whole req, a whole request body, or a whole config object, you have almost certainly written an Authorization header, a session cookie, a password field, or an API key into a log line that will sit in a stream for as long as your retention allows.

The discipline that prevents it:

Allowlist fields, never dump objects. Log req.method and req.nextUrl.pathname, not req. Every field in the examples above is named on purpose — requestId, method, path, status, ms, ip, ua. Nothing is a blind spread.
Log the outcome, not the payload. For the contact form I log that a submission happened and whether it succeeded. I do not log the message, the email, or the name. The status code answers the operational question; the content is none of the log's business.
Errors are the trap. err is safe to log — but if you catch and log a whole config or the arguments that caused the failure, secrets ride along inside the error context. Log the message and stack, not the surrounding state.
Be careful with query strings. A path like /reset?token=... puts a secret in the path field. If your routes carry sensitive query params, strip them before logging.

Structured logging doesn't magically redact anything. It just means the default is a short list of named fields instead of a firehose — and a short list is something you can actually audit.

What You End Up With

Put together, every request through this site produces:

One middleware line — request ID, method, path, IP, user-agent — for anything that isn't a static asset or an uptime probe.
One handler line — the same request ID, plus status and latency — for any route wrapped in withLog.
A response header carrying the ID back to the caller.

When something breaks, the path is: get the x-request-id from the response (or the reporter), grep it, and read the two or three lines that describe exactly what happened and how long each part took. No SSH, no guessing which log lines belong together, no regex against unstructured strings.

None of this is a large amount of code — a nine-line logger, a middleware function, and a wrapper. That's the point. Observability isn't a platform you buy; it's a shape you commit to and apply consistently. Error tracking (I use Sentry here) tells you that something failed. Structured logs tell you the sequence — what the request was, how long it took, and where in the flow it went wrong. You want both, and this is the log half.

slug="technical-consultation"
text="Running a Next.js app in production and can't reconstruct what happened when a request failed? Reviewing observability — logging, request tracing, error tracking — is exactly the kind of consultation I do."
/>

Further reading:

Health Check Endpoint in Node.js: Liveness vs Readiness — the other half of knowing your service is alive
Next.js 16 proxy.ts Migration: From middleware.ts — why middleware moved and how the file above got its name
Idempotency Keys for API Retries — correctness under retries, where a shared request ID also earns its keep
pino documentation
The Twelve-Factor App — Logs

Fake Tax Return and Transcript Fraud: The PDF Forensic Layer 4506-C Misses

Iurii Rogulia — Fri, 28 Aug 2026 10:00:45 +0000

Originally published at htpbe.tech. The version on htpbe.tech stays in sync with the latest detection algorithm — refer to it for the canonical text.

A borrower applies for a mortgage and uploads a copy of last year’s Form 1040 along with an IRS tax return transcript. The adjusted gross income on the transcript tracks the 1040. The wage and Schedule C lines reconcile. The taxpayer name, the filing status, and the IRS header formatting all look right. Your processor reviews the file against the income checklist, finds the tax documents complete and internally consistent, and clears it to move the loan forward while the 4506-C request goes out to the IRS.

Every step of that review was done correctly. And the income on those tax documents could still be inflated.

The reason is that the manual review confirms whether the numbers on the page are plausible and self-consistent. It was never built to confirm whether the PDF itself was edited after it left the tax-preparation software or the IRS. Those are two different questions. A borrower who downloads a real 1040 or transcript, opens it in an editor, and types a larger AGI over the original defeats the second question entirely — while passing the first, and while the lender waits days for the IRS pull that would have caught it.

This article walks through how lenders verify tax documents today, exactly where the 4506-C and IVES process leaves a timing gap, and the structural PDF forensic layer that flags an altered 1040 or forged transcript the moment it lands — before the IRS comes back. It is written for underwriting and risk operations teams at mortgage and consumer lenders, with a short integration section at the end for the people who wire it in.

How Lenders Verify Tax Documents Today

Tax-document verification is one of the most disciplined controls in lending, because tax income drives the debt-to-income ratio for self-employed and variable-income borrowers, and the DTI drives the approval. No single document carries the decision. Underwriters stack several checks and look for them to agree.

Read the 1040 against the income picture. The underwriter confirms total income, adjusted gross income, and the supporting schedules — Schedule C for self-employment, Schedule E for rental, Schedule B for interest and dividends. The figures are checked against the application, the borrower’s stated occupation, and any paystubs or profit-and-loss statements in the file. Numbers that do not reconcile across the documents get flagged.

Compare the borrower’s copy to the IRS transcript. Many lenders ask the borrower to supply an IRS tax return transcript or a tax account transcript alongside their own 1040 copy. The transcript restates the key lines the IRS has on record, so a borrower-supplied 1040 that disagrees with the transcript is a problem the underwriter is trained to catch.

Pull the transcript directly through 4506-C and IVES. This is the strongest control. Through a signed IRS Form 4506-C, the lender authorizes an Income Verification Express Service (IVES) participant to request tax transcripts straight from the IRS. Because the transcript comes from the IRS rather than from the borrower, it is one of the few checks a forger cannot tune in advance. When the 4506-C transcript comes back and matches the documents in the file, the income is corroborated by a source the borrower never touched.

Reconcile against other income documents. The tax return is cross-checked against W-2s, 1099s, bank statements, and paystubs already in the file. A 1040 that contradicts the borrower’s own pay history or deposit record is a flag the underwriter follows up.

Each of these is a genuine, valuable control. Stacked together they catch a great deal of fraud: clumsy fakes, income that doesn’t reconcile, returns that contradict the transcript. The question is not whether this process works. It is what it was built to verify — and where the uploaded PDF slips between the controls, specifically in the window before the IRS pull clears.

The Timing Gap the 4506-C Leaves Open

The 4506-C transcript pulled directly through IVES is the right answer to tax-document fraud whenever it applies, and it would be dishonest to suggest otherwise. When the IRS transcript comes back and matches, the income is confirmed by a source the borrower never handled — there is nothing the borrower could have edited. Keep it. HTPBE does not replace the 4506-C.

But the 4506-C process has timing and coverage boundaries, and tax-document fraud concentrates exactly at those boundaries.

The IRS pull takes time. A 4506-C request routed through an IVES participant does not return instantly. Turnaround commonly runs from a couple of days to over a week, and it lengthens during peak filing season, after IRS system outages, or when a transcript is not yet available. In that window, the loan is moving and decisions are being made on the borrower’s own uploaded copies.
Current-year income isn’t on file yet. A transcript reflects returns the IRS has already processed. For a recently filed return — or current-year income that hasn’t been filed at all — the IRS does not have the data yet, so the underwriter leans on the borrower-supplied 1040 and schedules to fill the gap.
Pre-approval and early underwriting run ahead of the pull. To keep the loan moving and give the borrower a rate, lenders often issue pre-approvals and early conditions on the documents in hand — before the 4506-C transcript has cleared. The altered PDF does its work in that interval.
Transcript mismatches need a reason to be investigated. When a transcript and a borrower copy disagree, someone still has to notice it, escalate, and investigate. A forger who edits both the 1040 copy and a borrower-supplied transcript image to agree with each other removes the easy contradiction that would have triggered the escalation in the first place.

In every one of these cases, the lender is back to a human reviewing an uploaded 1040 or transcript PDF — the exact scenario where a content review can’t see an edit. The 4506-C removes the document from the equation for the borrowers and timelines it covers. For everyone else, and for the days before the pull clears, the document is the evidence, and its integrity goes unchecked. KYC and identity platforms do not fill this gap either: they confirm who is applying — ID match, watchlist, face check — not whether a submitted tax PDF was altered.

The One Thing the Review Doesn’t Check

Read the verification list again and notice the common thread: every control either confirms the numbers on the page are plausible and self-consistent, or reaches outside the document to the IRS. When the 4506-C path has not yet cleared and the underwriter is left with the uploaded file, all that remains is a content review — and a content review asks one question: “Do these tax figures fit together and look like a real return?”

It never asks the other question: “Was this file edited after the tax software or the IRS produced it?”

That is the gap a careful forger exploits. Consider the most common tax-document fraud in lending:

The borrower downloads their real 1040 PDF from their tax-preparation software, or pulls a genuine tax return transcript from their IRS online account.
They open it in a desktop or online PDF editor.
They type a higher adjusted gross income over the original, adjust the wage or Schedule C lines so the totals still add up, and recompute the dependent figures so the return reconciles internally.
They re-save and upload it as their income documentation.

The result is a document built on the IRS’s or the tax software’s real template, in the right fonts, with the right header formatting — and, critically, the forger had every chance to make the edited numbers internally consistent. They can raise the AGI and adjust the supporting lines so the arithmetic still works. They can pick a figure that supports the DTI they need without making it look implausible. A patient borrower produces a file that passes every content check on the underwriter’s list, because the content was tuned specifically to pass those checks — and it does so days before the 4506-C transcript that would have contradicted it arrives.

Doctored IRS transcripts work the same way. A borrower starts from a real transcript pulled from their IRS account, edits the AGI, total income, or taxable income lines, and exports a clean-looking page. On screen, an edited figure looks exactly like an original one — the editor renders it in the same font, at the same position. The human eye has nothing to catch. And because the borrower can edit both their 1040 copy and a transcript image to agree, the cross-check that was supposed to catch the lie is satisfied.

This is why tax-document and income fraud is so persistent. Industry studies have long put the share of income documents submitted to lenders that are fabricated or altered in the high single digits to one in five, depending on the channel. Tools to edit a fake tax form are openly marketed online for a few dollars, and a careful edit takes only minutes. These documents are easy to alter and — once edited carefully — invisible to a process built to verify content rather than file integrity. They are also slow to be contradicted by an IRS pull that arrives days later.

The Missing Layer: Structural PDF Forensics

A PDF is not a flat picture. It is a structured file that carries an internal record of how it was built and saved — when it was created, what software produced it, whether it holds a digital signature, and how many times it was written to disk. When someone opens a tax program’s original 1040 or an IRS transcript and saves an edit, that act leaves traces in the file’s structure, no matter how plausible the visible numbers are.

Structural forensics reads that internal record and returns a verdict. It never judges whether a $180,000 AGI is a believable income — that’s the underwriter’s job and the content layer’s job. It judges whether the file’s own construction is consistent with a clean, single-pass export from tax software or an IRS system, or whether it bears the marks of having been opened and re-saved in an editing tool after the fact.

HTPBE is a self-serve, developer-first API that performs exactly this analysis. You send it a PDF; it returns one of three verdicts plus a list of named markers describing what it found. It is not a KYC or identity vendor and was never meant to be one — it answers a single, narrow question: was this file altered after it was created? Critically for lending, it answers that question in seconds, on the file in hand, while the 4506-C is still in flight.

The three verdicts

intact — no evidence of post-creation modification, and the file looks like a genuine institutional export. The structural layer found nothing to flag.
modified — the file carries forensic evidence that it was changed after it was first generated. This is the case that matters most for fraud: a 1040 or transcript that should be a clean export but instead shows the fingerprints of an editing session.
inconclusive — the file was produced by consumer software, an online editor, or a scanner, so there is no institutional baseline to check integrity against. This is not a pass. It is a routing signal, and in tax-document verification it is often the most useful verdict of all (more on that below).

What it actually catches — in plain terms

Without turning this into a how-to for forgers, here is the kind of structural evidence the analysis surfaces, described as outcomes rather than recipes:

Editing-tool fingerprints. Genuine 1040s come out of tax-preparation software, and IRS transcripts come out of IRS systems. When a file instead carries the signature of a consumer PDF editor or an online conversion service, that origin is inconsistent with a real tax-document pipeline. The marker HTPBE_EDITING_TOOL_FINGERPRINT flags this.
Disagreeing internal timestamps. A clean export’s creation and modification timestamps line up. When they contradict each other — the file claims to have been created on one date but was last written days later — that gap is recorded in the file structure even though it is invisible on the page. HTPBE_DATES_DISAGREE covers this, and it is one of the most conclusive signals there is.
Multiple revision layers. Each time a PDF is edited and saved, the change is appended as a new layer on top of the original. A tax document that should have been generated in a single pass but instead shows several stacked write sessions reveals that it was modified after creation. The marker is HTPBE_MULTIPLE_REVISION_LAYERS.
A spoofed institutional producer. Some tools try to disguise their involvement by rewriting the file’s stated generator to impersonate legitimate tax software or an IRS system. When that producer identity has been forged to mask the real origin, the analysis flags it with HTPBE_PRODUCER_IDENTITY_FORGED.
Targeted character and glyph edits. When specific figures on a return — an AGI line, a wage box, a Schedule C total — have been overwritten character by character or glyph by glyph by a desktop editor, the analysis can surface the localized edit. The markers HTPBE_CHARACTER_OVERLAY_EDIT and HTPBE_GLYPH_LEVEL_EDIT describe this pattern: individual numbers replaced after the document was authored, while everything around them was left untouched.

None of these depend on the visible numbers being implausible. A perfectly reconciled, perfectly tidy inflated AGI still sits inside a file that was edited — and the edit is what gets caught, on day zero, not after the IRS responds.

Want to see it on a real document? You can drop a 1040 or an IRS transcript into the free check on this site and get a verdict in a few seconds — no account needed. It’s the same engine the API runs, and it’s a fast way to sanity-check a single suspicious tax document before you decide whether to wire it into your intake.

What `inconclusive` Means in a Tax-Document Context

The inconclusive verdict is the one that confuses people, so it is worth being precise.

inconclusive means the file was created in software that anyone can use to build a document from scratch — Word, Excel, an online editor, a scanner. Because there is no institutional baseline, the structural layer cannot say whether the content was tampered with. It is telling you, honestly, “I cannot verify integrity here.”

The power of that verdict comes from context — specifically, where the document claims to come from.

IRS transcripts and 1040 exports from mainstream tax software have a recognizable institutional shape. A document that genuinely came from the IRS or a major tax-preparation product should look like an institutional export. So if a borrower hands you an “IRS tax return transcript” and the analysis returns inconclusive because the file was actually built in a word processor, rebuilt by a print-to-PDF driver, or run through an online editor, the verdict is doing real work: a real transcript pulled from the IRS would not look like that. That mismatch is a reason to insist on the 4506-C transcript before the income counts — not to approve the file on its face.

The same inconclusive verdict on a self-employed borrower’s own profit-and-loss export, or a return printed and re-scanned at a branch, is routine. The verdict is identical; the action depends on whether the claimed source is supposed to produce institutional files. Used this way, inconclusive is not a dead end — it is often the signal to fall back to the 4506-C pull the document was standing in for.

Honest Limits — What This Layer Cannot Catch

Structural forensics is a powerful additional control, not a fraud oracle. Two scenarios sit outside its reach, and a serious underwriting team should know them.

Documents fabricated entirely from scratch in the right kind of software. If a forger does not edit a real 1040 but instead builds a fake one from zero using a tool that produces clean, single-pass, institutional-looking output, there is no “original” to compare against and no editing event to detect. The file may look clean structurally because, structurally, it is a clean single-pass file; it just contains invented data. This is precisely where the 4506-C transcript pulled directly from the IRS remains the right control: it corroborates the income against a source the borrower never touched. The structural layer’s strength is the far more common case — editing a real document — not fabrication from nothing. Use it to catch the edits in the days before the IRS responds, and let the 4506-C finish the job.

Legitimately consumer-generated tax documents. Some borrowers legitimately export their own records through generic office software, and self-employed filers produce their own statements. For those, inconclusive is the correct and expected verdict, and reading it as guilt would generate false positives. The signal only carries weight when the claimed source — the IRS, mainstream tax software — has an institutional baseline to deviate from.

Being upfront about these limits is the point. The structural layer is designed to slot alongside your existing process — catching the altered-PDF case that a content review and a lagging 4506-C can’t see in the moment — not to be a single switch that decides loans on its own.

Wiring It Into Your Tax-Document Workflow

For teams that decide the structural layer belongs in their intake, integration is deliberately small. The pattern is three steps, and it runs the moment the borrower uploads — not when the IRS responds.

1. Analyze the uploaded document. When a borrower uploads a 1040 or a tax transcript, send its URL to the analyze endpoint. There is no numeric risk score to interpret — you get a verdict and named markers.

curl -X POST https://api.htpbe.tech/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-storage.example.com/income/applicant-7821-1040.pdf"}'

The response is just the check ID:

{ "id": "506a6b1b-1360-48a2-b389-abb346f85d04" }

2. Fetch the verdict. Retrieve the result by ID. The response is a flat object — the two fields your policy cares about are status and modification_markers.

curl https://api.htpbe.tech/v1/result/506a6b1b-1360-48a2-b389-abb346f85d04 \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "status": "modified",
  "modification_markers": ["HTPBE_EDITING_TOOL_FINGERPRINT", "HTPBE_DATES_DISAGREE"],
  "modification_confidence": "certain"
}

3. Route on the verdict. Wire the three outcomes into your existing review queue rather than auto-deciding on any single marker:

modified → route to manual review, hold the income until the 4506-C transcript clears, or — for the most conclusive markers — reject. The structural flag lets you stop the loan before the IRS pull rather than discovering the discrepancy after closing.
inconclusive → branch on the claimed source. A consumer-software origin on a document claimed to be an IRS transcript or a mainstream-tax-software 1040 is worth insisting on the direct 4506-C pull; the same verdict from a self-employed borrower’s own export is routine.
intact → no structural evidence of alteration; proceed with your normal verification while the transcript request runs.

Store the check ID against the loan file. If a credit decision is ever disputed or audited, the forensic result stays available as a permanent record showing exactly which structural signals fired — useful for both compliance and repurchase defense.

Who Should Add This Layer

If you run underwriting or fraud operations at a mortgage lender, a consumer lender, or any shop where borrowers upload 1040s and IRS transcripts — especially where the 4506-C transcript lags the decision, or current-year income isn’t on file with the IRS yet — this is the gap in your stack worth closing. Your underwriters are already verifying income well, and your 4506-C process is the right backstop. What neither can see, in the days before the IRS responds, is whether the file in front of them was edited after the tax software or the IRS produced it. That blind spot is exactly where careful borrowers operate, and it’s exactly what a structural PDF forensic layer covers — in seconds, on day zero.

For the closely related case of altered paystubs and W-2s, see the forensic layer mortgage underwriting misses on income documents; for doctored bank statements, see how lenders verify bank statements and the forgery layer they miss; and for the broader picture across the funnel, PDF fraud detection in loan origination ties the document types together. You can also read how the structural layer fits fake tax-document detection and mortgage origination specifically. When you’re ready to put a verdict behind your tax-document intake, the self-serve API is documented end-to-end with test keys you can wire up before you spend a credit, and pricing starts at a tier built for a single underwriting team.

The VIES Consultation Number for Finance Teams

Iurii Rogulia — Fri, 28 Aug 2026 09:00:43 +0000

Originally published at vatnode.dev. The version on vatnode.dev is the canonical source — refer to it for the latest content.

The VIES Consultation Number for Finance Teams

When an auditor reviews a zero-rated intra-EU invoice, one of the things they can ask is a simple question: how do you know the customer's VAT number was valid when you raised it? A screenshot of a VIES page from last week does not answer that. The VIES consultation number does — it is a reference the European Commission's system issues that ties a specific VAT number, a specific date and time, and a specific reply together. This guide is about why that reference matters to a finance, tax, or audit team, and what it does and does not prove. It is the business companion to the technical write-up on how to extract and store it — there is no code here.

The field auditors ask for

On a VAT audit of cross-border B2B supplies, the reviewer is testing whether you were entitled to not charge VAT. Part of that is substantive — was this genuinely a supply to a taxable person in another member state — and part of it is evidential: can you show you did the checks a diligent business is expected to do?

For the evidential part, self-produced records help but they are exactly that: self-produced. A line in your own system saying "checked, valid" is your word. The consultation number is different in kind. It is issued by VIES, not by you, and it points back to a validation that VIES itself performed. When Your Europe's guidance on checking a VAT number talks about proving to a tax administration that you checked a number and got a validation reply, the consultation number is the thing it tells you to keep. That is the whole reason it exists.

What the consultation number is, in plain English

VIES has two modes. A plain check answers "is this number valid, yes or no." A requester-qualified check answers the same question but records who was asking — you supply your own VAT number as the requester alongside the number you are checking. Only the requester-qualified check produces a consultation number.

Think of it as a receipt. It says: requester X asked VIES about number Y on date Z, and here is the reply. In the raw VIES response the value sits in a field called requestIdentifier — a short opaque string. You never need to read or interpret it; you store it as text and keep it with the transaction it relates to. That is the extent of what a finance team needs to know about its shape. If a single field reference is useful, it looks like this in a structured response:

{
  "valid": true,
  "consultationNumber": "WAPIAAAAX9999999",
  "verifiedAt": "2026-08-31T09:12:00Z"
}

The point is not the string. The point is that VIES attests to it.

Why it matters for zero-rated intra-EU B2B invoices

On an intra-EU B2B supply, the seller often does not charge local VAT — the supply may be a zero-rated intra-Community supply of goods, or the place of supply for a service may shift to the buyer under the reverse-charge mechanism. In both cases the buyer accounts for the VAT in their own country, and in both cases one of the conditions is that the buyer is a VAT-registered taxable person in another member state.

Verifying the buyer's VAT registration is therefore not a nicety, it is one of the things national authorities expect a seller to have done. The consultation number is the cleanest evidence that you did it, and that you did it at a point in time you can name. Where a plain screenshot proves nothing about when, the consultation number is contemporaneous — it is dated by the system that issued it. That is what makes it useful for an invoice you may have to defend years later.

Two clarifications keep this honest. First, the consultation number supports proof of verification; it is one input to the treatment, not the treatment itself. Second, whether validation is even required, and how often, depends on the situation — that is covered in when validation is required. If you want the plain-English picture of what VIES is before going further, what VIES is, for finance is the place to start.

What it does and does not prove

This is where the line has to be drawn precisely, because it is easy to claim too much.

What it proves:

That you checked a specific VAT number.
The date and time you checked it.
The reply VIES gave.

What it does not prove:

That the transaction is exempt or zero-rated. Those depend on substantive conditions — the nature of the supply, evidence of transport for goods, the buyer's status — not on the fact that a check happened.
That the VAT number was "certified" or that the treatment is secured. The consultation number does not adjudicate the transaction. It is evidence you did your part of the diligence, nothing more.

So the accurate framing is narrow: keep the consultation number to prove that you checked, not to prove that the sale was correctly treated. It complements your own records; it does not replace them. If VIES was unreachable and a check fell through to another source, or if your client logged an attempt that never returned, those entries still belong in your trail — the consultation number just will not be on them.

What to keep alongside it

On its own the consultation number is a reference without context. To be usable as evidence, keep it next to the facts that give it meaning:

The VAT number you checked, in the form you sent it.
Your requester VAT number — the consultation number is meaningless without knowing who asked.
The timestamp of the check.
The reply — valid or not, and the trader name and address if returned.
The source — was this answered by VIES, or by a national fallback source? Only VIES lookups carry a consultation number.
The invoice or transaction the check belongs to, so the two can be tied together later.

That last link is what turns a pile of validations into an audit trail. A consultation number that you cannot connect to an invoice does not help anyone. Building the whole chain — check, evidence, invoice, retention — is its own exercise; there is a walkthrough in build the full audit trail.

Where it belongs in your records

A common question is whether the consultation number goes on the invoice itself. It does not have to, and no EU member state requires it to appear there. Some teams do print a short "VIES ref" near the customer's VAT number as a courtesy signal to the buyer's finance department, but that is a convention, not a legal invoice field. Treat it as internal evidence first.

Where it does belong is in your validation records, retained on the same footing as the invoice it supports. If your invoices are kept for a given period, the consultation numbers backing them should be kept at least as long — they are only useful for as long as the invoice they defend is open to review. Retention periods differ by jurisdiction, so the specific number of years is a question for your adviser, not for this page.

How to make sure you capture it every time

The consultation number is easy to lose without noticing, because a plain valid/invalid answer looks complete on its own. To capture it reliably:

Run requester-qualified checks, not plain ones. If your validation path does not send a requester VAT number, VIES will answer the question but issue no consultation number. There is nothing to store after the fact — you either asked for it at the time or you did not.
Persist it immutably. Append each check as a new record; never overwrite an earlier one with a later result. The evidence is time-specific, and overwriting destroys it.
Allow it to be absent. When a check is answered by a national fallback source instead of VIES, there is no consultation number, and that is expected. Keep the record anyway, mark the source, and leave the reference blank rather than inventing one.

If you would rather not manage the VIES call and its edge cases yourself, a VIES API that returns the consultation number does the requester-qualified lookup on every live check and hands you the field as structured data — the mechanics of extracting and storing it are in how to extract and store it. You can run a check to see the consultation number a live lookup returns.

This is general information about EU VAT and VIES, not tax advice — whether and how to rely on the consultation number for a specific filing is for a qualified adviser.

FAQ

What is a VIES consultation number?

It's the reference VIES issues for a requester-qualified validation — proof that you checked a specific VAT number at a specific time and what reply you got. The Commission's guidance is to keep it in your records as evidence you ran the check.

Is the consultation number unique to vatnode?

No. VIES issues it; any provider that runs a requester-qualified check can return it. It is a standard part of the VIES response, not something exclusive to one service.

Is a consultation number returned for every check?

No. It exists only for requester-qualified VIES lookups. A check answered by a national fallback source has no consultation number, so don't assume it's always present.

How long should we keep it?

Align it with your invoice retention — the consultation number backs up the invoice it relates to. Retention periods vary by jurisdiction; this is general information, not tax advice.

Capture the consultation number on every check

vatnode runs requester-qualified VIES checks — set your EU VAT number once in Settings and every live VIES check then returns the consultation number as a structured field, so your finance records carry the evidence without extra work. Free plan, 100 requests/month.

Get a free API key

Three small design decisions in a "toggle effects via CSS class" library, and the tradeoffs behind them

Iurii Rogulia — Thu, 27 Aug 2026 12:13:45 +0000

Three small design decisions in a "toggle effects via CSS class" library, and the tradeoffs behind them

I built halloween.js, a small library that adds Halloween-themed page effects (blinking eyes, flying witches, a dropping spider, screen-corner webs) to any website, driven entirely by CSS classes on <body>. The effects themselves aren't interesting — CSS animations and a setTimeout scheduler. What I want to write about are three decisions that turned out harder than they looked once real usage exposed the edge cases.

1. Reactive sync via MutationObserver instead of an imperative API

The obvious API for a library like this is imperative: Halloween.start("eyes"). I built that first, then threw most of it away.

The problem: this library is meant to be dropped into contexts where you don't control JS execution order — a WordPress header, a page builder, a CMS field that toggles a class based on user state. An imperative API assumes you can call a function at the right moment. In practice, the "right moment" doesn't exist in these environments.

So instead, the library watches document.body's classList:

const observer = new MutationObserver(trySync);
observer.observe(document.body, {
  attributes: true,
  attributeFilter: ['class', 'data-halloween-start', 'data-halloween-end'],
});

Any code, anywhere, adding or removing halloween-eyes on <body> — a page builder's visual toggle, a classList.toggle() in unrelated code, a browser extension — gets picked up and re-synced automatically. No init call, no "did this run before or after my class change" race.

The non-obvious part: when a class is removed, the corresponding effect has to stop immediately, not after its current animation cycle finishes. If a spider is mid-drop and you flip halloween off, waiting for the drop-and-climb animation to complete before tearing down the node means up to several seconds of an effect running after it was explicitly turned off — which, from the caller's perspective, looks like a bug ("I removed the class, why is it still animating"). So trySync() does a hard stop-and-remove on any mutation where the gate condition is now false, rather than a graceful fade-out queued behind the current animation frame.

2. Three-source config with per-edge precedence, resolved fresh every time

The library only runs within a season window (defaults to ~2 weeks around Halloween), so it can be left on a page year-round. That window's start/end can come from three places:

A data-halloween-start/data-halloween-end attribute on <body> (highest priority)
A classic <script src="..."> tag's own ?s=/?e= query params, captured once via document.currentScript while the script is synchronously executing
A hardcoded library default

The precedence is resolved independently for the start and end edge — you can override just the end date and let the start fall through to the query param or default. More importantly, it's re-resolved on every sync call, not cached at load:

export function getSeasonWindow(): { start: string; end: string } {
  return {
    start: bodyAttrOr('data-halloween-start', CONFIG.seasonStart),
    end: bodyAttrOr('data-halloween-end', CONFIG.seasonEnd),
  };
}

This matters because the data-* attributes are in the MutationObserver's attributeFilter. If a page changes data-halloween-end at runtime (say, a marketing team extends the promotion by a week via a CMS field), the new value takes effect on the very next mutation-triggered sync — no page reload needed. Caching the resolved window at module load, which is what I did in the first draft, silently broke that.

3. Fail-open on malformed date input, plus a wraparound range and leap-day clamp

Date parsing for DD-MM strings turned out to have more edge cases than expected:

Malformed input fails open, not closed. If data-halloween-start is set to garbage (typo, wrong format), the library defaults to running, not to silently disabling itself:

export function isWithinSeason(now: Date, startStr: string, endStr: string): boolean {
const start = parseDDMM(startStr);
const end = parseDDMM(endStr);
if (!start || !end) return true; // fail open
...

The reasoning: a config typo that silently turns the whole feature off is a much worse failure mode for this library's use case (a seasonal decoration someone configured once and forgot about) than one that just always runs. A support ticket for "it's running when it shouldn't" is easier to diagnose than "it silently never ran and nobody noticed for a year."

The range can wrap across New Year's (e.g., a 25-12–05-01 window), which flips the comparison from AND to OR:

if (startDate <= endDate) {
return now >= startDate && now <= endDate;
}
return now >= startDate || now <= endDate;
29-02 is accepted as a valid date year-round, not just in leap years, and gets clamped to 28-02 when resolved against a non-leap year. This avoids a config that silently stops working every three years out of four, which is exactly the kind of intermittent bug that's miserable to track down months after the config was written.

What I'd still call unfinished

The season gate is only re-evaluated when something mutates the watched attributes — there's no polling for "it's now past midnight, recheck the date." If a page is left open across a season boundary with zero DOM mutations in between, the library won't notice until something else touches class or the data-halloween-* attributes (a reload, another caller of the public halloween() re-sync function). For a page that's actually being interacted with this is a non-issue in practice, but it's a real gap I haven't closed, not an oversight I'm unaware of.

Source: https://github.com/rogulia/halloween.js
Live demo: https://halloween.js.org/

A Typed MDX Content Pipeline with Velite (Next.js Tutorial)

Iurii Rogulia — Wed, 26 Aug 2026 10:00:54 +0000

Most Next.js blogs read MDX at request time, hand you frontmatter as any, and discover a missing date or a typo in a tag when the page 500s in production. That works until the content set grows past a handful of posts. Then every rename, every new frontmatter field, every tag cleanup becomes a guessing game, because nothing checks the shape of your content until a user hits the route.

This site works differently. Content is compiled once, validated against Zod schemas, and emitted as typed JSON that the app imports like any other module. If a post is missing a required field, the build fails — not the page. Here's how it's wired, taken straight from the config that ships this site.

The Problem with Reading MDX at Request Time

The common pattern looks like this: a getPostBySlug() helper reads a file, runs gray-matter, and returns an object. TypeScript has no idea what's in the frontmatter, so you either cast to any or hand-write an interface that drifts from reality the moment someone adds a field in an .mdx file.

Three things go wrong as the content grows:

No validation. A post dated 2026-13-01 or missing a summary sails through until render.
No single source of truth. The frontmatter shape lives in your head; the TypeScript type lives in a types.ts that nobody updates.
Runtime cost. Parsing and compiling MDX on every request, or fighting the router's caching to avoid it.

Velite moves all of that to build time. You describe each content collection once, with a schema, and get back validated, typed data plus compiled MDX.

Defining a Collection with a Zod-Style Schema

Velite's s object is a thin wrapper over Zod with content-aware helpers (s.slug(), s.isodate(), s.mdx(), s.raw()). A collection binds a glob pattern to a schema. Here is the blog collection this site uses, trimmed to the fields that matter:

// velite.config.ts
import { defineCollection, s } from "velite";

const posts = defineCollection({
  name: "Post",
  pattern: "blog/**/*.mdx",
  schema: s.object({
    title: s.string().max(120),
    seoTitle: s.string().max(70).optional(),
    subtitle: s.string().max(220).optional(),
    keyphrase: s.string().max(80).optional(),
    slug: s.slug("posts"),
    summary: s.string().max(300),
    date: s.isodate(),
    updated: s.isodate().optional(),
    category: s.enum(["dev", "business"]).default("dev"),
    verb: s.string().max(20).optional(),
    cta: s
      .object({
        service: s.string().optional(),
        text: s.string().max(280).optional(),
      })
      .optional(),
    raw: s.raw(),
    body: s.mdx(),
  }),
});

A few of these earn their place:

s.slug("posts") validates the slug is URL-safe and unique across the posts set. Two posts with the same slug is a build error, not a silent overwrite.
s.isodate() rejects anything that isn't a real ISO date. The 2026-13-01 case above dies here.
s.enum(["dev", "business"]).default("dev") is how the editorial track is enforced. A post either declares one of two categories or defaults — you can't invent a third by typo.
s.raw() keeps the untouched Markdown source around; s.mdx() compiles the body to a function string the renderer executes. Having both means you can derive things from the raw text (word count, headings) that the compiled output has already thrown away.

The .max() limits aren't decoration. A summary capped at 300 characters and a seoTitle at 70 mean malformed metadata fails the build instead of quietly breaking a SERP snippet weeks later.

Sharing Schema Fragments

Tags on this site aren't a flat array — they're categorized into stack, libraries, databases, services, and topics. That structure is identical across posts, projects, and reviews, so it lives in one schema fragment:

const tagsSchema = s
  .object({
    stack: s.array(s.string()).default([]),
    libraries: s.array(s.string()).default([]),
    databases: s.array(s.string()).default([]),
    services: s.array(s.string()).default([]),
    topics: s.array(s.string()).default([]),
  })
  .default({});

Each collection reuses tags: tagsSchema. Change the categories once and every collection updates. This is the same DRY instinct you'd apply to a shared type — it just happens at the content-schema layer.

Computed Fields with `.transform()`

Raw frontmatter is rarely what the app wants to consume. You want a permalink, a reading time, a flattened tag array, an extracted table of contents. Velite's .transform() runs after validation and lets you derive all of it, so the emitted record is enriched and still fully typed.

schema: s
  .object({ /* fields above */ })
  .transform(async (data) => {
    return {
      ...data,
      tagCategories: data.tags,
      tags: [
        ...data.tags.stack,
        ...data.tags.libraries,
        ...data.tags.databases,
        ...data.tags.services,
        ...data.tags.topics,
      ],
      permalink: `/blog/${data.slug}`,
      readingTime:
        data.readingTime ??
        Math.max(1, Math.round(data.raw.split(/\s+/).length / 200)),
      wordCount: data.raw.split(/\s+/).filter(Boolean).length,
      headings: extractHeadings(data.raw),
      coverImage,
    };
  }),

What's happening here:

tags is flattened from the categorized object into a single string[] that components can iterate — while tagCategories preserves the grouped shape for anything that needs it. One source, two views.
readingTime falls back to a word-count estimate (words / 200) only when the frontmatter didn't set it. Author override wins; otherwise it's computed.
headings are extracted from the raw Markdown by a small parser that walks the source, skips fenced code blocks, and slugs each ##/### with github-slugger — the same slugger rehype-slug uses for anchors, so the table of contents links resolve.

The transform is async, which is what makes the next part possible.

Side Effects at Build Time: Cover Images

Because the transform runs at build time and can be async, it's also the right place to do content-adjacent asset work. When a cover.png sits next to index.mdx, the transform copies it into public/, generates a WebP for serving, and pre-pads OG and dev.to variants with sharp:

const coverSrc = path.join(process.cwd(), "content", "blog", data.slug, "cover.png");
let coverImage: string | undefined;
if (existsSync(coverSrc)) {
  const destDir = path.join(process.cwd(), "public", "images", "blog", data.slug);
  mkdirSync(destDir, { recursive: true });
  copyFileSync(coverSrc, path.join(destDir, "cover.png"));
  await ensureWebp(coverSrc, path.join(destDir, "cover.webp"));
  await ensureCoverVariant(coverSrc, path.join(destDir, "cover-og.png"), 1200, 630);
  await ensureCoverVariant(coverSrc, path.join(destDir, "cover-devto.png"), 1000, 420);
  coverImage = `/images/blog/${data.slug}/cover.webp`;
}

The variant helpers are idempotent — they check the destination's mtime against the source and skip work if nothing changed — so incremental builds stay cheap. That's the point of a build-time content layer: image derivation, format conversion, and metadata validation happen in one pass, and the running app just references paths that are guaranteed to exist.

One Typed Import

Velite writes the compiled collections to .velite/ (configured via output.data), and the app imports them as @/.velite:

import { posts, projects } from "@/.velite";

posts is a fully typed array. The category is "dev" | "business", not string. permalink, readingTime, headings — all present, all typed, because the transform put them there and Velite inferred the shape. There is no getPostBySlug() reading the filesystem at request time; there's an array in memory, generated at build.

A worthwhile guardrail on top of this: you could add an ESLint no-restricted-imports rule that forbids importing from .velite in application code directly, routing everything through a thin lib/ layer instead. That would keep the raw generated output an implementation detail and give you one place to add filtering (drafts, future-dated posts) without touching every call site.

The Codegen Step: A Related-Posts Graph

Typed content unlocks work that's awkward to do at runtime. This site computes a tag-overlap graph — related posts, related projects, related services — in a script that runs after velite build and before next build:

{
  "scripts": {
    "build": "velite build && tsx scripts/generate-relations.ts && next build"
  }
}

That's the relevant slice of the build chain — the real build script has one more codegen step after this (generate-cv.tsx, which prebuilds a PDF), unrelated to the content pipeline and out of scope here. The script reads the JSON Velite just emitted, scores every pair by shared tags, and writes .velite/relations.json:

// scripts/generate-relations.ts
import { services } from "../lib/services";

const posts: VeliteItem[] = JSON.parse(readFileSync(join(root, ".velite/posts.json"), "utf8"));

function tagOverlap(tagsA: string[], tagsB: string[]): number {
  return tagsA.filter((t) => tagsB.includes(t)).length;
}

function findRelated(sourceSlug, sourceTags, candidates, limit = 2): string[] {
  return candidates
    .filter((c) => c.slug !== sourceSlug)
    .map((c) => ({ slug: c.slug, overlap: tagOverlap(c.tags, sourceTags), date: c.date }))
    .filter((c) => c.overlap > 0)
    .sort(
      (a, b) => b.overlap - a.overlap || new Date(b.date).getTime() - new Date(a.date).getTime()
    )
    .slice(0, limit)
    .map((c) => c.slug);
}

The scoring is deliberately boring: count shared tags, sort by overlap descending, tie-break on newest first, take the top N. It runs across four relationship types — post→posts, post→projects, post→reviews, post→services — and because it reads the same categorized-then-flattened tags array the schema produced, the graph is consistent with what the site renders everywhere else.

Two design choices are worth calling out. First, services feed the graph from lib/services.ts, not from MDX — service definitions live in TypeScript with their own tags field, and the script imports them as the single source of truth for that side of the relation. Second, the whole thing is a build artifact: relations.json is written once, committed to nothing, and read as static data. No runtime tag-matching, no per-request cost, no way for the graph to disagree with the pages.

Where This Pays Off and Where It Doesn't

The build-time model earns its keep when:

content is large enough that manual consistency breaks down;
you cross-link content by shared metadata (tags, categories, series);
frontmatter mistakes should block a deploy, not surface as production 500s;
you want derived data — reading time, TOC, related items — computed once, not per request.

It's overhead you don't need when the site is three static pages and a contact form, or when content changes so often that a rebuild per edit is friction rather than safety. A CMS with runtime rendering fits that better. There's also a real constraint: everything lives in the repo and requires a build to publish. If non-technical editors need to publish without a deploy, this isn't the shape for them — that's a headless CMS decision, not a Velite one.

For a code-owned, developer-authored content set, the trade is clean: one schema, one typed import, validation at the build boundary, derived data generated in the same pass. The content layer stops being a source of runtime surprises and becomes just another typed module the app depends on.

If you're building a content-heavy Next.js product and want the content layer typed and validated from the start — the schema, the codegen, the guardrails that keep it from rotting — that's the kind of foundation I put in before feature work begins. Get in touch if you're spinning up an MVP and want it built on something that won't break silently as it grows.

Further reading:

Velite documentation
Generating dynamic OG images in Next.js — another build-time asset step in this pipeline
Writing effective CLAUDE.md rules for AI coding agents — how this content architecture is documented for tooling

Right-to-Work and I-9 Document Fraud: The Tampered PDF Your Compliance Check Misses

Iurii Rogulia — Wed, 26 Aug 2026 10:00:41 +0000

Originally published at htpbe.tech. The version on htpbe.tech stays in sync with the latest detection algorithm — refer to it for the canonical text.

A new hire emails over their work-authorization paperwork before the start date. In the US, that’s a permanent resident card and a supporting document for the I-9. In the UK, it’s a screenshot or PDF of a Home Office share-code result, or a sponsor letter confirming the candidate’s visa. The name matches the offer. The dates are in range. The document looks exactly like every genuine one your team has processed. Your onboarding coordinator files it and clears the candidate to start.

Every step of that review was done correctly. And the document could still have been edited.

The reason is that the right-to-work (RTW) and I-9 verification process is built to check whether the document is plausible and consistent — the right name, a valid-looking expiry date, the correct document type for the person’s status. It was never designed to check whether the PDF file itself was altered after the issuing authority produced it. Those are two different questions. A candidate who opens a real share-code printout or a real sponsor letter, changes one expiry date or one name, and re-saves it defeats the second question completely — while passing the first without trouble.

This is the shape of most right-to-work document fraud and fake I-9 document cases in practice: not a forgery built from nothing, but a real document edited in one field. This article walks through how employers and background-verification (BGV) operators actually verify work authorization today, exactly where that process breaks on a well-edited PDF, and the structural forensic layer that closes the gap. It is written for HR compliance, BGV operations, and sponsor-licence holders — not developers, though there is a short integration section at the end.

One thing to be clear about up front, because this sits right next to a category HTPBE is not in: HTPBE does not confirm a person’s identity and does not confirm their eligibility to work. It does not replace E-Verify, the Home Office online right-to-work check, or any identity-document validation service. Those checks answer “is this person who they say they are, and are they allowed to work?” HTPBE answers a single, narrow, different question: was this PDF file edited after it was created? It is additive to your existing process, not a substitute for any part of it.

The Stakes: Civil and Criminal Liability Land on the Employer

Work-authorization fraud is one of the few compliance areas where accepting a forged document exposes the employer, not just the fraudster, to penalties.

In the United States, employers must complete Form I-9 for every employee and examine documents that establish identity and employment authorization. Knowingly accepting fraudulent documents, or failing to properly verify, carries civil fines into the thousands of dollars per violation, and a pattern of knowing violations can escalate to criminal exposure — against a backdrop of steadily rising US Immigration and Customs Enforcement audit activity.

In the United Kingdom, the regime is sharper still. An employer who hires someone without a valid right to work and cannot show a statutory excuse faces a civil penalty the Home Office raised to up to £60,000 per illegal worker in 2024 — triple the previous maximum. For sponsor-licence holders, the consequence isn’t only the fine: a compliance failure can mean licence suspension or revocation, severing the right to sponsor any overseas worker and collapsing a hiring pipeline overnight. And the statutory excuse depends on having carried out the prescribed check correctly. If a candidate hands over an edited document and the operator processes it at face value, that excuse can be undermined precisely because the underlying file was not what it appeared to be. The liability attaches to the organisation that accepted the paperwork.

How Employers Verify Work Authorization Today

Work-authorization verification is a layered process, and a competent one catches a great deal. Here is what the controls actually do — and they do their jobs well.

United States: I-9 and E-Verify

For the I-9, the employer examines the documents the employee presents from the Lists of Acceptable Documents — a List A document that proves both identity and authorization (a permanent resident card, an Employment Authorization Document), or a List B identity document paired with a List C authorization document — confirming each reasonably appears genuine and relates to the person. Many employers then run the data through E-Verify, which checks it against Social Security Administration and Department of Homeland Security records. When E-Verify runs, it is the right control — keep it. But under the remote alternative procedure available to qualified E-Verify employers, documents may be examined over video with copies transmitted in advance. That is where edited PDFs enter the workflow: the reviewer is looking at a transmitted file, not a physical card.

United Kingdom: Share Codes and Sponsor Compliance

For candidates with a digital immigration status, the prescribed check is online: the candidate generates a share code, the employer enters it with the candidate’s date of birth on the Home Office service, and the official result displays straight from government records. Done live, this check is robust — the data comes from the Home Office, not from a candidate-supplied file. Where an online check isn’t possible, the employer examines documents from the prescribed lists manually and retains a clear copy. Licensed sponsors carry ongoing duties on top of this: tracking visa expiry and retaining right-to-work evidence — sponsor letters, Certificate of Sponsorship records, share-code printouts, passport and BRP copies — as PDFs in a compliance folder, ready to produce if the Home Office audits.

Each of these is a real, valuable control, and the live share-code check in particular is excellent because it pulls from the source rather than trusting a supplied file. The problem is not that these checks are weak. The problem is what happens when a file is processed in place of the live source.

The One Thing the Process Doesn’t Check

Read those controls again and notice the common thread. They verify whether the document’s content is plausible and matches the person: right name, valid-looking expiry, correct document type, data that corresponds to a real record. These are content questions. None of them ask the other question: “Was this PDF edited after the issuing authority produced it?”

That is the gap a careful fraudster exploits. Consider the most common way work-authorization documents are faked — not forged from nothing, but edited from a real one:

The candidate obtains a genuine document as a PDF — their own expired share-code printout, a real sponsor letter issued to someone else, a permanent resident card scan, a visa grant letter.
They open it in a desktop or online PDF editor.
They change one field — push an expiry date forward, swap the name, alter a visa category, change a Certificate of Sponsorship number.
They re-save the file and send it to the employer.

The result is a document built on a real template, with the real layout, the real fonts, the real official styling — and a candidate who had every chance to make the edited field look correct. The expiry date is now in the future. The name now matches the offer. On screen, the edited field is indistinguishable from an original one, because the editor renders it in the same font at the same position. A visual review has nothing to catch.

Where does this slip through the otherwise-strong checks? Precisely at the moments when a file stands in for the live source:

A US reviewer examining transmitted document copies under the remote procedure is looking at a PDF, not a card.
A UK employer who relies on a candidate-supplied share-code printout rather than running the code live on the Home Office service is trusting a file, not the government record. (Running the code live is the safer path — and exactly why a tampered printout is the fraudster’s workaround for candidates who can’t pass the live check.)
A sponsor compliance folder full of retained PDFs has, by definition, no live source behind it — it’s the file or nothing when the auditor asks.
A BGV operator processing thousands of documents at scale receives PDFs by email and upload, far downstream from any original.

In every one of these cases, the decision rests on an uploaded or emailed PDF, and the integrity of that PDF goes unchecked. The content review confirms the data is plausible; nothing confirms the file wasn’t altered to make it so.

What E-Verify and the Online Check Solve — and What They Don’t

When E-Verify runs against DHS and SSA records, or a UK employer runs a share code live against the Home Office service, the data is validated against the authority directly — there is no supplied file to edit, so there is nothing for a PDF editor to defeat. For the candidates and moments those checks cover, they are the gold standard. HTPBE does not replace them, and you should keep every one of them.

But those checks have a coverage and timing boundary, and document fraud concentrates exactly at that boundary:

Documents that aren’t run live. A share-code printout examined as a PDF, rather than entered live on the Home Office service, is a file — and a file can be edited. The same is true of any supporting document transmitted as a copy.
Document types with no online equivalent. Sponsor letters, internal Certificate of Sponsorship records, visa grant letters, and many supporting documents have no real-time validation service behind them. They exist only as PDFs.
Retained compliance evidence. A sponsor’s audit folder is a collection of files captured at hire time. Nothing re-validates them later; their integrity is assumed.
High-volume BGV intake. Background-verification operators handle work-authorization documents in bulk, mostly as uploaded PDFs, where a manual live check on every single file isn’t feasible.

In each of these cases, an organisation is back to a human relying on a PDF — the exact scenario where content checks and even excellent live-lookup services can’t see an edit, because no file passed through them. Identity and eligibility services don’t fill this gap either: they confirm who the person is and whether they may work, not whether a particular submitted PDF was altered. That uploaded-file case is precisely where a structural layer earns its place. It is additive — it catches what the live checks sidestep and what the human reviewer can’t see.

The Missing Layer: Structural File Forensics

A PDF is not a flat picture. It is a structured file that carries an internal record of how it was built and saved — when it was created, what software produced it, whether it holds a digital signature, and how many times it was written to disk. When someone opens an authority’s original PDF and saves an edit, that act leaves traces in the file’s structure, no matter how convincing the visible field looks.

Structural forensics reads that internal record and returns a verdict. It never asks whether an expiry date is plausible or whether a name belongs to a real person — that’s the job of E-Verify, the Home Office check, and your reviewer. It asks whether the file’s own construction is consistent with a clean, single-pass document from an issuing system, or whether it bears the marks of having been opened and re-saved in an editing tool after the fact.

HTPBE is a self-serve API that performs exactly this analysis. You send it a PDF; it returns one of three verdicts plus a list of named markers describing what it found. To be unambiguous: it is not an identity or eligibility vendor, and was never meant to be one. It does not tell you the candidate is who they claim or that they may legally work. It answers only: was this file altered after it was created?

The three verdicts

intact — no evidence of post-creation modification, and the file looks like a genuine single-pass document from an institutional system. The structural layer found nothing to flag.
modified — the file carries forensic evidence that it was changed after it was first generated. This is the case that matters most: a document that should be a clean export but instead shows the fingerprints of an editing session.
inconclusive — the file was produced by consumer software, an online editor, or a scanner, so there is no institutional baseline to check integrity against. This is not a pass. It is a routing signal, and in work-authorization checks it is often the most useful verdict of all (more on that below).

What it actually catches — in plain terms

Without turning this into a how-to for forgers, here is the kind of structural evidence the analysis surfaces, described as outcomes rather than recipes:

Editing-tool fingerprints. Documents issued by government and institutional systems are produced server-side. When a file instead carries the signature of a consumer PDF editor or an online conversion service, that origin is inconsistent with a genuine issuing pipeline. The marker HTPBE_EDITING_TOOL_FINGERPRINT flags this.
Disagreeing internal timestamps. A clean export’s creation and modification timestamps line up. When they contradict each other — the file claims one creation date but was last written days later — that gap is recorded structurally even though it’s invisible on the page. HTPBE_DATES_DISAGREE covers this.
Multiple revision layers. Each time a PDF is edited and saved, the change is appended as a new layer on top of the original. A document that should have been generated in a single pass but instead shows several stacked write sessions reveals that it was modified after creation. The marker is HTPBE_MULTIPLE_REVISION_LAYERS.
Producer identity that’s been overwritten or spoofed. Some tools try to hide their involvement by rewriting the file’s stated generator. When that identity has been blanked or forged, the analysis flags it (HTPBE_IDENTITY_OVERWRITTEN, HTPBE_PRODUCER_IDENTITY_FORGED).
Tampering around a digital signature. Where a document is digitally signed — some official letters and certificates are — the analysis detects content changed after signing (HTPBE_POST_SIGNATURE_EDIT) or a signature stripped off entirely (HTPBE_SIGNATURE_REMOVED). These are among the most conclusive signals there are.

None of these depend on the visible field being implausible. A perfectly formatted, perfectly believable forged expiry date still sits inside a file that was edited — and the edit is what gets caught.

Want to see it on a real document? You can drop a PDF into the free check on this site and get a verdict in a few seconds — no account needed. It’s the same engine the API runs, and it’s a fast way to check a single suspicious share-code printout or sponsor letter before you decide whether to add it to your onboarding.

What `inconclusive` Means for Work-Authorization Documents

The inconclusive verdict is the one people most often misread, so it’s worth being precise.

inconclusive means the file was created in software that anyone can use to build a document from scratch — Word, an online editor, a scanner. Because there’s no institutional baseline, the structural layer can’t say whether the content was tampered with. It’s telling you, honestly, “I can’t verify integrity here.”

The power of that verdict comes from context — specifically, what the document claims to be.

A Home Office share-code result printout, an official visa grant letter, a permanent resident card scan from a government system: these have an institutional origin. A genuine one should look like an institutional export. So if a candidate hands you a document claiming to be an official government-issued result, and the analysis returns inconclusive because the file was actually built in a word processor or run through an online editor, the verdict is doing real work: a real official document would not look like that. That mismatch is a reason to escalate — and, ideally, to go run the share code live yourself rather than trust the printout at all.

The same inconclusive verdict on a document that’s supposed to be a simple internal letter — something an HR team might legitimately produce in Word — is routine, and you’d treat it as such. The verdict is identical; the action depends on whether the claimed source is supposed to produce institutional files. Used this way, inconclusive isn’t a dead end. It’s a fork in your workflow — and frequently a prompt to fall back to the authoritative live check.

Honest Limits — What This Layer Cannot Catch

Structural forensics is a powerful additional control, not a fraud oracle. Two scenarios sit outside its reach, and a serious compliance team should know them.

Documents fabricated entirely from scratch in the right kind of software. If a fraudster doesn’t edit a real document but instead builds a fake from zero using a tool that produces institutional-looking output, there is no “original” to compare against and no editing event to detect. The file may look clean structurally because, structurally, it is a clean single-pass file — it just contains invented data. This is exactly why the structural layer complements rather than replaces source verification: running the share code live on the Home Office service, running E-Verify, and confirming details with the issuing authority remain the right controls for fabricated-from-scratch fraud. The structural layer’s strength is the far more common case — editing a real document.

Legitimately consumer-generated documents. Some genuine letters really are produced in Word or exported through generic print drivers. For those, inconclusive is the correct and expected verdict, and reading it as guilt would generate false positives. The signal only carries weight when the claimed source has an institutional baseline to deviate from.

And to restate the boundary that matters most here: HTPBE checks the file, not the person. It does not establish identity or the right to work, and it is not a statutory check on its own. A modified verdict tells you a file was altered and should be escalated and re-sourced; an intact verdict tells you the file wasn’t altered — not that the candidate is authorized to work. Your E-Verify run and your live Home Office check remain the controls that answer eligibility. The structural layer slots alongside them, catching the altered-PDF case they can’t see.

Wiring It Into Your Onboarding or BGV Workflow

For teams that decide the structural layer belongs in their workflow, integration is deliberately small. The pattern is three steps.

1. Analyze the uploaded document. When a candidate uploads or emails a work-authorization PDF, send its URL to the analyze endpoint. There is no numeric risk score to interpret — you get a verdict and named markers.

curl -X POST https://api.htpbe.tech/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-storage.example.com/onboarding/candidate-7821-rtw.pdf"}'

The response is just the check ID:

{ "id": "506a6b1b-1360-48a2-b389-abb346f85d04" }

2. Fetch the verdict. Retrieve the result by ID. The response is a flat object — the fields your policy cares about are status, modification_markers, and modification_confidence.

curl https://api.htpbe.tech/v1/result/506a6b1b-1360-48a2-b389-abb346f85d04 \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "status": "modified",
  "modification_markers": ["HTPBE_EDITING_TOOL_FINGERPRINT", "HTPBE_DATES_DISAGREE"],
  "modification_confidence": "certain"
}

A Python version for a typical onboarding service:

import os
import requests

API = "https://api.htpbe.tech/v1"
KEY = os.environ["HTPBE_API_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

def screen_document(pdf_url: str) -> dict:
    submit = requests.post(f"{API}/analyze", headers=HEADERS, json={"url": pdf_url})
    submit.raise_for_status()
    check_id = submit.json()["id"]

    result = requests.get(f"{API}/result/{check_id}", headers=HEADERS)
    result.raise_for_status()
    data = result.json()

    return {
        "status": data["status"],                       # intact | modified | inconclusive
        "markers": data["modification_markers"],         # e.g. ["HTPBE_DATES_DISAGREE"]
        "confidence": data["modification_confidence"],   # certain | high | none
        "check_id": check_id,                            # store for your audit trail
    }

3. Route on the verdict. Wire the three outcomes into your existing review queue rather than auto-deciding on any single marker:

modified → route to manual review, request a fresh document direct from the candidate, and re-run the authoritative check (run the share code live, run E-Verify). For the most conclusive markers — a post-signature edit on a signed letter — treat the finding as conclusive: decline to accept that file and require a fresh issuer-delivered copy before proceeding, rather than making the verdict the sole basis for an automatic decision about the person.
inconclusive → branch on the claimed source. A consumer-software origin on a document claimed to be an official government result is worth escalating and re-sourcing live; the same verdict on a plain internal letter is routine.
intact → no structural evidence of alteration; proceed with your normal identity and eligibility checks, which remain the controls that confirm the person can work.

Store the check ID against the candidate record. If a hiring decision or a sponsor audit is ever questioned, you can retrieve the forensic result from your check history. It shows exactly which structural signals fired — useful both for demonstrating diligence and for defending a statutory-excuse position.

Who Should Add This Layer

If you run HR compliance, onboarding, or BGV operations — or you hold a sponsor licence and keep a folder of retained right-to-work evidence — this is the gap in your stack worth closing. Your team already runs E-Verify or the Home Office check well, and those controls already confirm identity and eligibility. What they cannot see, by design, is whether a particular uploaded PDF was edited after the authority issued it. That blind spot is exactly where a careful candidate operates, and exactly what a structural layer covers — without ever pretending to be an identity or eligibility check.

For a deeper look at how this works as a workflow, see the right-to-work document fraud detection use case and the broader immigration document fraud detection hub. When you’re ready to put a verdict behind your onboarding intake, the self-serve API is documented end-to-end with test keys you can wire up before you spend a credit — create an account and screen your first document in minutes.

What Is VIES? A Guide for Finance Teams

Iurii Rogulia — Wed, 26 Aug 2026 09:00:41 +0000

Originally published at vatnode.dev. The version on vatnode.dev is the canonical source — refer to it for the latest content.

What Is VIES? A Guide for Finance Teams

VIES is the free European Commission service you use to confirm that an EU VAT number is registered. Type in a number, and it tells you whether that number is on the books in the country it belongs to. Finance and operations teams reach for it constantly — before invoicing a new EU customer, when a supplier gives you their VAT number, or whenever an intra-EU B2B transaction depends on the other side being VAT-registered.

This guide is the plain-English version: what VIES actually does, what a "valid" or "invalid" answer really means for your invoices, and where the limits are. It stays inside the area VIES covers — the EU-27 plus XI (Northern Ireland). If you want the mechanics under the hood, how VIES works, in depth goes further than we will here.

What VIES is

VIES stands for the VAT Information Exchange System. The important thing to understand is what it is not: it is not one big central EU database of VAT numbers. The European Commission describes it as a search engine, not a database — and that distinction matters more than it sounds.

When you look up a VAT number, VIES takes the country prefix, works out which member state the number belongs to, and forwards your query to that country's own VAT database in real time. Ireland's tax authority answers for Irish numbers, Germany's answers for German numbers, and so on. VIES relays the answer back to you. It owns none of the data; it routes the question to whoever does.

That design has two consequences worth keeping in mind. First, the data is only as current as each national database — the Commission doesn't control it and disclaims its accuracy, so a change made by a national authority isn't always reflected the instant it happens. Second, because each country answers for itself, the countries can fail independently: one national node can be down while every other one works fine.

Who actually runs a VIES check (a person, or your billing system)

In practice a VIES check gets run one of two ways.

A person runs it manually. Someone in finance opens the Commission's public VIES page, types in a country and a number, and reads the result off the screen. This is perfect for a one-off — a new supplier, a single large invoice, a number that looks odd. It doesn't scale, and it leaves no record beyond a screenshot.

Your billing or ordering system runs it automatically. Instead of a human typing into a form, your software asks the same underlying service and gets a structured answer back — valid or invalid, plus whatever company detail the country returns. That's how you validate a VAT number on every signup or every invoice without anyone lifting a finger. The trade-off between the two is the subject of the last section; for now, the point is that both are asking the same thing of the same national databases.

Either way, VIES itself is free. There's no login, no fee, and no contract. There's also no service-level guarantee behind it, which is exactly why the "who runs it" question turns into an engineering decision once your volume grows.

What "valid" tells you — and what it doesn't

A "valid" result means the number was present and active in the relevant national database at the moment you asked. That is genuinely useful: it's evidence that the business is VAT-registered, and for intra-EU B2B it's one of the conditions that supports zero-rating or reverse charge.

Here's where finance teams overreach. A valid reply is not:

A guarantee about the company. VIES confirms a registration, not the counterparty's identity, solvency, or good standing. A number can be perfectly valid and belong to a business you still shouldn't extend credit to.
A statement about the transaction. Whether a specific sale qualifies for reverse charge depends on what's sold, where, and to whom — not on the VAT number alone. The valid number is one input, not the ruling.
A promise that the data is complete. Not every valid national VAT number is visible in VIES. Only numbers activated for intra-EU trade show up, so a business can be legitimately VAT-registered domestically and still not appear.

Treat a valid result as what it is: solid evidence of registration at a point in time, and a green light to move to the next check — not the final word on the deal.

A couple of prefix details trip people up, since they change what you type in. Greece uses EL, not GR. Northern Ireland uses XI, and only for goods. Enter the wrong prefix and you'll get a confusing answer to the wrong question.

What "invalid" means for an invoice

An "invalid" result does not mean "fraud." It means the number is not registered — or not enabled for cross-border trade — in that country's database at the time you checked. There are ordinary reasons for it:

a typo, or a domestic tax number entered where the VAT number belongs;
a registration that has lapsed or been cancelled;
a valid domestic number that was never activated for intra-EU use, so VIES can't see it.

The practical rule: don't invoice on a bare invalid. Before you apply reverse charge or zero-rate a supply, resolve why the number came back invalid. Go back to the customer, confirm the number, check the prefix, and re-run it. If it stays invalid, the safe default is to treat the supply as if the customer were not VAT-registered — charge VAT as normal — rather than assume a treatment you can't support.

Getting this wrong is expensive in one specific way: if you zero-rate a supply on the strength of a VAT number that turns out to be invalid, the tax can land back on you. That's the whole reason the check exists.

The limits of VIES (downtime, uneven company detail, point-in-time answers)

Three limits shape how you should use it.

Downtime is normal, not an emergency. Because each country runs its own node, availability is per-country and there's no guaranteed uptime — no SLA, no promise it will answer. Nodes go offline for maintenance or load, and some are less reliable than others. When a node is down you get an error, not an answer, and that error is not the same as "invalid." A VIES outage should never silently turn into a blocked customer or a wrong VAT decision. (For the systems side of this, we wrote up handling VIES downtime separately.)

Company detail is uneven. Some countries return the registered business name and address alongside the valid/invalid flag; others return only the flag. So you can't count on getting a name to match against your records for every country — it depends who's answering.

Answers are point-in-time. A valid result describes the moment you asked and nothing else. Registrations lapse; businesses deregister. A number you validated at onboarding a year ago may not be valid today, which is why a single check is a snapshot, not a standing guarantee.

Why keep proof of the check

If you rely on a VIES result to zero-rate or reverse-charge a supply, you should be able to show later that you actually ran the check and what it returned. Auditors on intra-EU supplies do ask.

A screenshot from a manual lookup is thin evidence. A stronger trail records, for each check, when it ran, what came back, and which source answered. VIES can also return a consultation number — a reference tied to a specific query that shows you performed the check at that time. It's a useful piece of the audit trail, though it's not the whole story and it's not something only one provider can give you. We cover how to use it in keep proof of the check.

The habit worth building: every VAT decision that depends on a check should have a stored record behind it, not a memory of having looked.

Manual checking vs automating it

So which way should you run checks?

Manual is fine when volume is low. A handful of new EU customers or suppliers a month? The Commission's free page does the job. The costs are that it doesn't scale, it's easy to skip under pressure, and the evidence it leaves is weak.

Automate once checks become routine. If you're validating numbers on every signup, every invoice, or across an existing customer base, hand-checking stops being realistic — and that's exactly where things get missed. Connecting your billing or ordering system to a VIES API means every number gets checked the same way, downtime is handled for you instead of becoming a blocked order, and each result is logged automatically for the audit trail. The judgement call is simply where your volume crosses the line from "occasional" to "routine."

Not sure yet? Start manual. You can check a VAT number free right now with no setup, and move to automation when the manual approach starts to strain.

FAQ

Is VIES free to use?

Yes. VIES is the European Commission's service and is free to query. It has no service-level guarantee, though — individual country nodes go down, so it is not something to treat as always-on.

What does it mean if VIES says a VAT number is invalid?

It means the number is not registered — or not enabled for cross-border trade — in the relevant national database at the time you checked. Investigate before you invoice; don't apply reverse charge on a bare invalid.

Does VIES prove a company is legitimate?

No. It confirms VAT registration at query time, not the company's identity, solvency, or good standing. A valid result is evidence of registration, not a guarantee about the counterparty.

How often should we check a VAT number?

At onboarding and again before you rely on it — registrations lapse. There's no legally fixed interval; set a cadence that matches your risk.

Check an EU VAT number free

Confirm a single number against VIES in seconds with the free VAT number checker — no account needed. Running checks on every signup or invoice instead? Get a free API key and validate through the VIES API from your own system — free plan, 100 requests/month.

Is Your Software Quote Honest? A Buyer's Guide

Iurii Rogulia — Mon, 24 Aug 2026 10:00:57 +0000

You've asked three developers to build the same thing. One says €8,000 and six weeks. One says €25,000 and four months. One says "give me a couple of days, I'll knock it out for €2,000."

You can't read the code. You can't judge the architecture. So you do the only thing you can: you compare the numbers, and the cheapest confident one wins.

That's how buyers get burned. Not because they made a foolish choice, but because the one signal they can read — the price — is the one signal that's easiest to fake.

The good news is that you don't need to read code to read a quote. A quote is a document written by a human being making judgments about uncertainty, and the way they handle that uncertainty tells you almost everything about how the project will go. You just have to know what to look at.

Why the Cheapest Quote Is Usually the Most Expensive

There's a reason the lowball number feels safe: it removes the scariest variable, cost, and it does it decisively. No hedging, no ranges, no "it depends." Just a small, confident figure. Decisive feels competent.

But in software, a small confident number for a non-trivial job is almost never competence. It's one of two things: the person doesn't yet understand what the work involves, or they understand it fine and they're pricing to win the deal, planning to make it back on change orders once you've already committed.

Both end in the same place. The naive quote runs out of money halfway, because the work was always going to cost more and reality doesn't care what was promised. The strategic lowball invoices you for everything the original number quietly excluded. Either way, the €8,000 project becomes a €20,000 project — except now it's late, half-built, and you've lost the leverage you had before you signed.

The expensive part of cheap software is never the invoice. It's what you build on top of it. A cheap quote buys you a system that works in the demo and breaks the first time a real customer does something the developer didn't picture. You find out in production, with your name on it. Rebuilding it costs more than doing it right would have — plus everything you lost while it was broken.

I'll say the uncomfortable version plainly: when you pick the cheapest quote for real business software, you're usually not saving money. You're deferring the real cost to a moment when it's more expensive and less recoverable.

Why "Two Weeks" Almost Always Means Six

This isn't developers lying to you. It's structural, and understanding why makes you a much harder buyer to fool.

When someone quotes a feature quickly, they're picturing the happy path — the version where everything works. Customer clicks the button, the data's valid, the payment goes through, the page loads. That mental movie runs in a few seconds and feels like the whole job.

It's maybe a third of the job.

Everything the demo doesn't show sits underneath: what happens when the data's wrong, when the payment provider times out, when the customer double-clicks and you're charged twice, what the screen looks like while it's loading and when it's empty and when it errors. Then someone has to test it, find the problems, fix them, and re-test the things the fix broke. None of that is in the two-week picture, and none of it is optional. A feature that only handles the happy path isn't 90% done — it's a prototype that happens to demo well.

There's a second trap hiding in every fast number. A developer estimates effort — "that's about five days of work" — and it gets heard as duration — done in a week. Those aren't the same thing. Five days of actual focused work don't fit into a five-day week, because a working day isn't eight hours of that one task. It's meetings, other people's questions, the context-switching, the admin. Five days of effort is closer to two weeks on the calendar before anything goes wrong.

So when you hear a fast, small number, the honest translation is: that's the best case, for the part they can see, if nothing surprises them. Something always surprises them. That's not pessimism — it's the base rate. If you want the longer engineering version of why this happens, I wrote it up in why "two weeks" always means six.

The Questions That Expose a Padded or Naive Estimate

You don't need technical vocabulary to test a quote. You need questions that force the person to reveal how they think about uncertainty. Ask these, and listen to the shape of the answer more than the content.

"What's your estimate, and what's the range?" A single number is a red flag. Not because ranges are more honest as a style, but because uncertainty is real and a single number pretends it isn't. A good answer sounds like: "Three weeks if the payment integration behaves the way its docs claim, five if it fights us the way these usually do, and my honest expectation is around four." That person has thought about what could go wrong. The one who insists on a single confident number either hasn't, or is hiding it.

"What's not included in this price?" The answer tells you whether they've thought past the happy path. "Nothing, it's all included" from a cheap quote means they haven't mapped the work. A real answer names things: data migration, third-party costs, revisions after your feedback, testing, the stuff that's genuinely out of scope. A quote that can't tell you what it excludes hasn't defined what it includes.

"What are you assuming to hit this number?" Every estimate rests on assumptions. "Three weeks, assuming your existing data is clean and the payment provider's system works as documented" is a real estimate — because when an assumption breaks, you get a named reason instead of an unexplained overrun. Someone who can't state their assumptions is giving you a number that stands on nothing.

"What would make this take twice as long?" This one's diagnostic. The person who says "nothing, it's straightforward" is telling you they haven't found the risks yet — which means you'll find them together, later, at your expense. The person who can immediately name two or three things that could blow up the timeline has actually looked at the problem.

The pattern underneath all four: you're not testing their coding. You're testing whether they've thought about what they don't know. A confident answer to every question is the worrying one. Some honest hesitation, some "it depends, here's what it depends on," is the sound of someone who's done this before.

slug="technical-consultation"
text="If you've got a proposal in front of you and no way to tell whether the number is real, that's a single-session job. I read the quote as an engineer, ask the seller the questions you can't, and tell you what it's actually pricing — before you sign anything."
/>

When a High Quote Is Not Justified

Filtering out lowballs is only half the skill. The other half is not overpaying, because expensive isn't automatically honest either. Some high quotes are padding, over-engineering, or someone charging you for complexity you don't need yet.

Here's how to tell the difference. A justified high number comes with a justified high scope — it's expensive because it's solving a genuinely hard problem, handling real edge cases, or building something that has to survive scale you actually have. The seller can point at what the money buys and it maps to something you recognize as real.

An unjustified high number is expensive because the seller is building for a future you don't have yet. Watch for these:

They're pricing for scale you don't need. You have zero users and they're quoting a system that handles a million. Building for load you don't have is real work you're paying for and won't use for years, if ever.
They're gold-plating the parts that don't matter. A beautiful admin dashboard with analytics before you have anyone to analyse. Elaborate user roles and permissions before you have a second type of user. These sound responsible and are, at your stage, expensive guesses. I listed the specific ones that reliably kill early products in features that kill MVPs.
They can't explain the number in your language. If a seller can't tell you why it costs what it costs without retreating into jargon, one of two things is true: they don't understand it well enough to explain, or they'd rather you didn't understand it well enough to question it. Neither is worth your money.

The honest expensive quote and the honest cheap quote have the same tell: the person can walk you through what the money buys, in plain words, and it holds up. The dishonest versions — padded high or naive low — both fall apart the moment you ask them to explain.

The One Thing to Do Before You Sign

If you take one action from this, make it this: ask each bidder to separate the estimate from the commitment.

The estimate is their honest technical guess at the effort. The commitment is the date and price they'll actually stand behind. These should be different, and the gap between them — the buffer for the things nobody can see yet — should be visible, not hidden.

A seller who says "my estimate is six weeks, but given what we don't yet know about your existing data, I wouldn't commit to a customer-facing date tighter than nine" is doing the honest thing out loud. A seller who gives you one number that's secretly the estimate promised as a commitment with no buffer is setting up the overrun you'll live through in month three.

And here's the filter, stated plainly, because it cuts both ways. If you punish the honest sellers — the ones who give you ranges, name their risks, and refuse to promise a comforting single number — and reward the confident lowballer, you are training your suppliers to lie to you. You will get exactly the quotes you selected for: small, confident, and wrong. The seller who won't compress an honest range into the number you want to hear is being useful, not evasive. That's the one to keep.

You can't read the code. You don't have to. You can read whether the person in front of you is comfortable being honest about what they don't know — and in software, that's the thing that predicts whether the project ships.

If you're staring at two quotes with a gap you can't explain, don't guess. Let's read the proposal together — I'll tell you which number is real and which one is a problem you haven't met yet.

Expense Report Fraud Detection: The Altered Receipt PDF Your Controls Never Inspect

Iurii Rogulia — Mon, 24 Aug 2026 10:00:41 +0000

Originally published at htpbe.tech. The version on htpbe.tech stays in sync with the latest detection algorithm — refer to it for the canonical text.

The Association of Certified Fraud Examiners puts expense reimbursement fraud at a median loss of $40,000 per scheme, with a median duration of two years before detection. That two-year gap is not an accident. It is the predictable result of a control environment that validates everything about an expense claim except the one artifact the claim rests on: the receipt PDF itself.

First, a quick boundary, because this site covers two different fraud classes that people often confuse. Vendor invoice fraud — a supplier’s invoice intercepted and edited in transit, or a fake supplier billing for nothing — is a different document, a different submitter, and a different control. We cover it in the accounts payable invoice fraud breakdown. This post is about the other case: employee-submitted expense receipts and hotel folios in a travel-and-entertainment (T&E) reimbursement workflow. Same finance team, completely different blind spot. The vendor-invoice control is the three-way match. The expense-receipt control is the expense policy. Neither one looks at the file.

The T&E Control Environment, and Where It Stops

Walk through how a typical mid-market expense claim is checked, and you can see exactly where the inspection ends.

An employee returns from a trip, opens the expense tool — Concur, Expensify, Ramp, Brex, a homegrown form — and uploads receipt images and PDFs against each line. A manager approves. Finance spot-checks. If the company is large enough to care about SOX, the controllership layer adds detective controls: sampling, duplicate-detection, policy-threshold flags, and the famous three-way match — purchase order against invoice against goods receipt.

Every one of those controls operates on data extracted from the receipt, never on the receipt as a file. The three-way match confirms that an invoice amount agrees with a purchase order and a goods-received note. It is an excellent control for procurement. But it says nothing about whether the hotel folio an employee attached to a $312 line was the folio the hotel actually issued, or a copy of it with the room rate quietly raised from $189 to $312.

This is the structural blind spot in detective controls for accounts payable: the three-way match was designed for vendor-billed spend that flows through purchasing. Employee reimbursements flow through a different door. They are usually self-submitted, individually small, and — most important — almost always below the approval and sampling thresholds that trigger review. A $312 dinner does not get a second look. A thousand $312 dinners across a sales team over two years is the $40,000 ACFE median walking out the door.

Why Receipt Fraud Survives the Standard Checks

Four properties of T&E make the receipt PDF the softest target in the finance stack.

It sits below the threshold. Sampling and dual approval start at amounts that most travel line items never reach. The fraud is sized to stay unnoticed — small edits, repeated.

It is self-submitted. Unlike a vendor invoice that arrives over a (theoretically) controlled channel, the receipt is whatever the employee chooses to upload. There is no handshake with an issuing system. The finance team receives a file and a claim, and is asked to trust that the two match.

It is reviewed visually, if at all. A manager glancing at a folio is checking that it looks like a hotel bill for roughly the right city on roughly the right dates. An edited room rate, an added minibar line, a date moved to bring a personal weekend inside the business-trip window — none of that is visible to a human approver who has no original to compare against. OCR-based duplicate detection reads the displayed number; it cannot tell whether that number was the one the hotel printed.

The genuine receipts are messy too. Real receipts come as phone-camera photos, scanner output, airline emails saved to PDF, and folios generated by whatever property-management system the hotel runs. The finance team has no clean baseline to compare against, which is exactly the cover an edited receipt needs.

The result: the receipt PDF is the only document in the entire reimbursement chain that nobody inspects structurally, and it is the one document the claim depends on entirely.

What an Altered Receipt Actually Looks Like

The common T&E manipulations are simple and effective:

The inflated restaurant receipt. A real $84 dinner becomes a $184 dinner by editing the total. The restaurant name, the date, and the card’s last four digits all stay correct — only the number changes.
The edited hotel folio. A genuine folio for a discounted rate is opened, and the nightly rate or the number of nights is raised. Fake hotel folio fraud is a long-standing favorite, because folios are dense, full of line items, and rarely checked against the booking.
The doctored rideshare or airfare receipt. An Uber or airline receipt saved to PDF, then edited to raise the fare or change the route so a personal trip looks like business.
The date shift. The amount does not change; a single date is moved so a non-reimbursable expense falls inside an approved travel window.

In each case the fraudster starts from a real document and changes a value. That detail matters a great deal, because it is exactly the pattern structural tamper detection is built to catch. The original file was generated by a hotel system, an airline, or a card terminal’s e-receipt service. The edit was made afterward, in a consumer PDF editor, and opening and re-saving that file leaves a structural record — the editor cannot make the change without disturbing the document’s internal construction.

How Structural Tamper Detection Catches the Edit

HTPBE is a file-integrity layer. It does not read the dollar amount on the receipt, decide whether $312 is reasonable, or know what the hotel charged. It is not a KYC or identity tool, and it does not validate content. What it does is analyze how the PDF was built — its cross-reference (xref) tables, its incremental update layers, its signature state, and the producer and date metadata that records which software touched the file and when — and return one of three verdicts: intact, modified, or inconclusive, plus a list of named markers that describe what was found.

When a genuine institutional receipt is opened in a desktop editor and a value is changed, the editor appends an incremental update layer rather than rebuilding the file from scratch, and it rewrites the metadata to record itself as the last tool that saved the document. A folio that claims to come from a hotel property-management system but carries the modification fingerprints of a consumer PDF editor is internally inconsistent in a way the displayed page never reveals.

Here is the response on a hotel folio that was issued cleanly, then opened in a desktop PDF editor to raise the nightly rate. First submit the file:

curl -X POST https://api.htpbe.tech/v1/analyze \
  -H "Authorization: Bearer $HTPBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-storage.example.com/expenses/folio-8841.pdf"}'

That returns an id. Retrieve the verdict:

{
  "id": "7c4a1f90-2b6e-4d3a-9f81-5e2c8a4b7d10",
  "status": "modified",
  "modification_confidence": "high",
  "modification_markers": [
    "HTPBE_MULTIPLE_REVISION_LAYERS",
    "HTPBE_EDITING_TOOL_FINGERPRINT",
    "HTPBE_DATES_DISAGREE"
  ],
  "origin": { "type": "consumer_software", "software": "desktop PDF editor" },
  "creator": null,
  "producer": "a desktop PDF editor",
  "xref_count": 2,
  "has_digital_signature": false,
  "creation_date": 1755302400,
  "modification_date": 1755561600
}

Three things line up. HTPBE_MULTIPLE_REVISION_LAYERS reports that the file carries more than one revision layer — it was modified after it was first created. HTPBE_EDITING_TOOL_FINGERPRINT reports the fingerprints of a known PDF editing tool, which is not how a hotel system produces a folio. HTPBE_DATES_DISAGREE reports that the modification timestamp is three days later than the declared creation date. On its own, any one of these can have an innocent explanation. Together, on a document that is supposed to be a freshly issued folio, they are a high-confidence signal that the file was opened and re-saved between issuance and submission.

The verdict is modified with named markers. That is enough to hold the line item for review — not enough to fire the employee. A modified verdict is a structural anomaly, not a confession. It justifies a reviewer asking the employee for the original folio, or calling the hotel. Other markers in the same family carry the same weight where they apply: HTPBE_CHARACTER_OVERLAY_EDIT (targeted character-level overlays added by a desktop editor) and HTPBE_TEXT_OVERLAY_ON_SCAN (values painted on top of a scanned receipt) describe the two most common ways a number gets changed on a receipt. The full id-to-outcome dictionary is published on htpbe.tech/how, so you can branch your routing logic on the marker id and render the human-readable label from one place.

Want to See It on Your Own Receipts?

Before you integrate anything, pull a handful of receipts from a closed expense cycle — some you trust, ideally one or two you have already flagged — and run them through the free PDF check on the homepage. No API key, no signup. You will get the verdict and the markers in a few seconds. This is the fastest way to see whether this layer catches anything in your actual receipt flow before you spend a line of engineering time.

The `inconclusive` Verdict Is What Matters Most in T&E

Here is where expense receipts differ sharply from vendor invoices, and where most teams misread the tool if they are not warned.

A large share of legitimate receipts are generated by consumer software. A genuine Uber receipt is an HTML email rendered to PDF. A genuine restaurant e-receipt comes from a card-terminal service. A photo of a paper receipt is a phone-camera scan. None of these are institutional documents in the way a bank statement or a notarized deed is. When HTPBE sees a file with no prior structure to compare against — a clean, single-revision document built in consumer software — it returns inconclusive:

{
  "id": "b91e7d23-4c8a-4f15-8e6d-3a9f1c7b2e04",
  "status": "inconclusive",
  "status_reason": "consumer_software_origin",
  "modification_markers": [],
  "origin": { "type": "consumer_software", "software": "an HTML-to-PDF renderer" },
  "producer": "an HTML-to-PDF renderer",
  "xref_count": 1,
  "has_digital_signature": false,
  "creation_date": 1755302400,
  "modification_date": null
}

inconclusive is not a failure and it is not a fraud signal. It means this file was built by consumer software, so there is no institutional baseline against which integrity can be proven or disproven. On a vendor invoice that claims to come from QuickBooks, inconclusive is suspicious. On an Uber receipt, inconclusive is exactly what a genuine receipt looks like. If you auto-reject every inconclusive in a T&E pipeline, you will reject most of your honest receipts and learn nothing.

The correct way to use inconclusive in expense workflows is to route on the claimed issuer, not on the verdict alone:

A receipt that claims to be a hotel folio or an airline e-ticket and returns inconclusive deserves a second look. Those issuers normally produce structurally distinctive output, so a consumer-software origin is slightly off-profile.
A receipt that claims to be a restaurant tab, a rideshare, or a phone photo of paper and returns inconclusive is unremarkable. That is the expected result. Move on.

This is the single most important operating instruction for T&E: modified is your hold signal; inconclusive is a routing hint that means something only when compared with what the receipt claims to be. Treat them differently, or the tool is useless to you.

Integrating Into the Reimbursement Workflow

The check fits in at submission, before the claim enters the approval queue. Three steps:

At upload, when the employee attaches a receipt, push the stored file URL to POST /api/v1/analyze. You get back an id.
Read the verdict from GET /api/v1/result/{id}. Branch on status and the modification_markers[] array.
Route the claim. intact → continue to normal approval. modified → flag the line item and hold it for a reviewer with the marker list attached. inconclusive → apply your claimed-issuer rule above.

import requests, os

def check_receipt(file_url):
    api = "https://api.htpbe.tech/v1/analyze"
    headers = {"Authorization": f"Bearer {os.environ['HTPBE_API_KEY']}"}

    submitted = requests.post(api, headers=headers, json={"url": file_url})
    check_id = submitted.json()["id"]

    result = requests.get(
        f"https://api.htpbe.tech/v1/result/{check_id}", headers=headers
    ).json()

    status = result["status"]                 # intact | modified | inconclusive
    markers = result["modification_markers"]  # e.g. ["HTPBE_MULTIPLE_REVISION_LAYERS"]

    if status == "modified":
        return "HOLD", markers                # structural edit — reviewer follows up
    if status == "inconclusive":
        return "ROUTE_BY_ISSUER", markers     # apply claimed-issuer rule
    return "PASS", markers

Store the id against the expense line. There is no numeric risk score — the API returns a verdict plus named markers, never a 0–100 number — so your audit trail is a stable verdict and the specific markers that produced it. If a reimbursement is ever disputed or pulled into an internal-audit sample, GET /api/v1/result/{id} retrieves the immutable forensic record that shows which markers triggered the hold and when. That is a detective control with an evidence trail, which is exactly what a SOX environment wants.

What This Cannot Catch — Stated Plainly

Structural tamper detection has a hard boundary, and pretending otherwise would set you up to fail.

Receipts fabricated from scratch are out of scope. If a fraudster does not edit a real folio but instead builds a fake receipt from nothing — a convincing hotel bill generated in a design tool or on a receipt-generator site — the file has no prior structure to be inconsistent with. It is internally clean. HTPBE returns inconclusive (consumer-software origin) on such a file, exactly as it would for a genuine consumer-software receipt. The structural layer cannot tell a well-made fake-from-scratch apart from an honest one, because neither has anything to contradict.

AI-generated receipts are out of scope for the same reason. A receipt produced end-to-end by a generative model is born synthetic. There is no edit to detect, because there was no original to edit. Catching fabricated and AI-generated receipts is a content-layer problem — cross-referencing the claimed transaction against issuer data, card-network records, or booking systems — which is a different category of product from file-integrity forensics.

What HTPBE catches reliably is the alteration of a genuine document: the real folio with the rate raised, the real airfare receipt with the route changed, the real restaurant tab with the total raised. That is the most common T&E manipulation, precisely because starting from a real receipt is easier than fabricating a convincing one — and it is the manipulation that structural forensics is built to surface. Use it for what it is: one layer in a defense that also includes policy controls, issuer cross-checks for high-value claims, and human review of what gets flagged.

Who This Is For

If you own a T&E control environment — Head of Internal Audit, Controller, AP or expense operations lead, a finance team with a SOX detective-controls mandate — this closes a gap your existing stack genuinely does not cover. The three-way match protects procurement. Sampling and duplicate detection catch the obvious cases. Neither inspects the receipt PDF as a file, and the receipt is where reimbursement fraud lives.

A practical starting point is the expense reimbursement fraud use-case guide for routing patterns and policy integration, and the fake receipt detection deep-dive for the document-class detail. When you are ready to connect the check to your submission flow, the API reference lists the full request and response contract, and you can create an account to generate a key. Run a sample of closed expense reports through it first. The math on a check that costs a fraction of a cent against a $40,000 median scheme only matters if the layer catches a meaningful share of your actual receipt flow, and a sampling pass is how you find out.

Frequently Asked Questions

How do you detect a fake or altered expense receipt?

By analyzing the receipt PDF’s structure rather than its displayed content. When a genuine receipt is opened in a desktop editor and a value is changed, the editor appends a new revision layer and rewrites the metadata to record itself as the last tool that saved the file. HTPBE returns modified with named markers such as HTPBE_MULTIPLE_REVISION_LAYERS and HTPBE_EDITING_TOOL_FINGERPRINT when those structural fingerprints are present on a document that is supposed to be a freshly issued receipt. It does not read the dollar amount and does not decide whether the amount is reasonable — that is a content question.

Does the three-way match catch expense receipt fraud?

No. The three-way match validates a vendor invoice against a purchase order and a goods receipt — it is a procurement control. Employee expense reimbursements are self-submitted, usually below sampling thresholds, and do not pass through purchasing, so the three-way match never sees them. It also never inspects the receipt PDF as a file under any circumstance. That is the structural blind spot in detective controls for accounts payable that file-integrity analysis fills.

What does an inconclusive verdict mean on an expense receipt?

It means the receipt was generated by consumer software — an HTML-to-PDF renderer, a phone-camera scan, a card-terminal e-receipt — so there is no institutional baseline to prove or disprove integrity against. A large share of genuine receipts return inconclusive, so it is not a fraud signal on its own. Route it by what the receipt claims to be: inconclusive on a hotel folio is slightly off-profile and worth a look; inconclusive on a rideshare or restaurant tab is the expected, normal result.

Can you catch a receipt that was fabricated from scratch or generated by AI?

No — that is the honest limit. A receipt built from nothing in a design tool or produced by a generative model has no original to be inconsistent with, so structural forensics returns inconclusive, the same as a genuine consumer-software receipt. Catching fakes built from scratch and AI-generated fakes requires content-layer verification against issuer or card-network data, which is a different category of tool. HTPBE reliably catches the alteration of a genuine document, which is the most common T&E manipulation.

Where does this fit in a SOX control environment?

As an automated detective control at the point of receipt submission, with an evidence trail. Each check produces a stable verdict plus the specific markers that justified it, retrievable later via GET /api/v1/result/{id} if a reimbursement is disputed or sampled in an internal-audit review. It complements policy controls and sampling rather than replacing them — it adds inspection of the one artifact those controls historically never examine.

DEV Community: Iurii Rogulia

What an MVP Actually Costs

Where the Cost Actually Comes From

The Cheap MVP That Becomes an Expensive Rebuild

What's Safe to Cut

What You Must Never Cut

How to Read the Quotes

Vendor Bank Account Change Fraud: Detect the Forged Bank-Letter PDF

This is not BEC invoice fraud — it’s the vendor master

Why AP controls miss the forged bank letter

What the fraudster changes, and what it leaves behind

What the API returns on a forged bank-change letter

What inconclusive means here — and why it is still useful

Honest limits: what this check does not do

Integrating the check into vendor onboarding and change requests

Who should run this check

VIES Uptime, Measured — 28 Member States, One Sample Every 15 Minutes

The aggregate number is useless

What we measure

Availability by member state

Germany: switched off every night

Ireland: one outage, one block

Latvia: degrades under load

What VIES actually returns when it fails

Why national registers are a worse fallback than they look

What to do with this

What this does not measure

Reproduce it

Structured Logging in Next.js with Pino (Request IDs to stdout)

Why Structured, Not Strings

The Logger

One ID Per Request

Skip the Noise

Wrap the Route Handlers

Never Log a Secret

What You End Up With

Fake Tax Return and Transcript Fraud: The PDF Forensic Layer 4506-C Misses

How Lenders Verify Tax Documents Today

The Timing Gap the 4506-C Leaves Open

The One Thing the Review Doesn’t Check

The Missing Layer: Structural PDF Forensics

The three verdicts

What it actually catches — in plain terms

What inconclusive Means in a Tax-Document Context

Honest Limits — What This Layer Cannot Catch

Wiring It Into Your Tax-Document Workflow

Who Should Add This Layer

The VIES Consultation Number for Finance Teams

The VIES Consultation Number for Finance Teams

The field auditors ask for

What the consultation number is, in plain English

Why it matters for zero-rated intra-EU B2B invoices

What it does and does not prove

What to keep alongside it

Where it belongs in your records

How to make sure you capture it every time

FAQ

What is a VIES consultation number?

Is the consultation number unique to vatnode?

Is a consultation number returned for every check?

How long should we keep it?

Capture the consultation number on every check

Three small design decisions in a "toggle effects via CSS class" library, and the tradeoffs behind them

Three small design decisions in a "toggle effects via CSS class" library, and the tradeoffs behind them

1. Reactive sync via MutationObserver instead of an imperative API

2. Three-source config with per-edge precedence, resolved fresh every time

3. Fail-open on malformed date input, plus a wraparound range and leap-day clamp

What I'd still call unfinished

A Typed MDX Content Pipeline with Velite (Next.js Tutorial)

The Problem with Reading MDX at Request Time

Defining a Collection with a Zod-Style Schema

Sharing Schema Fragments

Computed Fields with .transform()

Side Effects at Build Time: Cover Images

One Typed Import

The Codegen Step: A Related-Posts Graph

Where This Pays Off and Where It Doesn't

Right-to-Work and I-9 Document Fraud: The Tampered PDF Your Compliance Check Misses

The Stakes: Civil and Criminal Liability Land on the Employer

How Employers Verify Work Authorization Today

What `inconclusive` Means in a Tax-Document Context

Computed Fields with `.transform()`

What `inconclusive` Means for Work-Authorization Documents

The `inconclusive` Verdict Is What Matters Most in T&E