DEV Community: Iurii Rogulia

Building a Verified n8n Node That Is Exposed as an AI Agent Tool

Iurii Rogulia — Wed, 04 Nov 2026 11:01:12 +0000

I published n8n-nodes-vatnode, a verified n8n community node for EU VAT validation. One line in the node class, usableAsTool: true, also makes n8n generate an agent-facing Tool variant of it. That line is easy to add and easy to under-think, because it changes who reads your code. In a normal node the reader is a person looking at a canvas. In the tool variant, the reader of your descriptions is a model.

This article is about two things: what that flag does, as far as the types and n8n’s loader code show, and what the path to a verified node looks like when you build for it from the start. One limit up front: I have not run this node inside an agent or evaluated what an agent does with it. This covers how the tool variant is built, not agent behaviour.

What the Flag Does

usableAsTool is not described on the docs pages I checked (node base files, file structure, verification guidelines, submission). The evidence is elsewhere:

The n8n-workflow types declare usableAsTool?: true | UsableAsToolDescription, commented as ‘whether the node will be wrapped for tool-use by AI Agents’.
The @n8n/node-cli template guide says to set it to true to allow use as an agent tool, and to leave it off if the node works heavily with binary data, which tools don’t support.
In n8n’s source, createAiTools (packages/cli/src/tool-generation/ai-tools.ts) takes every node with a truthy usableAsTool and builds a copy: Tool appended to the name, inputs cleared, the output set to AiTool. It injects a required toolDescription string parameter that defaults to the node’s description. If the node has a resource or operation property, it also adds a descriptionType option, automatic or manual. Credentials are copied across.

The code I read has no condition on whether the node is built in or a community package. I have not checked every code path that could add one, and I did not verify that the Tool variant is available on a given instance; that may depend on its configuration.

The text a model sees comes from strings you wrote for a human dropdown: the node description, each operation’s description and action, each parameter’s description. Those strings are now your tool contract. I haven’t verified how the automatic description type composes them, so I treat all of them as if they will be read.

Designing Operations for a Reader That Can Spend Money

The node has two resources and four operations. Two of them are the interesting pair, because they answer the same question at different prices:

options: [
  {
    name: 'Validate',
    value: 'validate',
    description:
      'Verify a VAT number against the official EU VIES register. Requires an API key and spends one request from your quota.',
    action: 'Validate a VAT number',
  },
  {
    name: 'Check Format',
    value: 'checkFormat',
    description:
      'Check a VAT number against its country pattern. Runs offline: no API key, no network call, no quota.',
    action: 'Check the format of a VAT number',
  },
],

Cost is written into the description, in plain words, on each operation. A person scanning the dropdown benefits. So does anything choosing between the two from text alone. I did the same split in the MCP server for the same API, for the same reason: a caller who only needs a cheap answer shouldn’t be pushed toward the expensive one.

This is a mitigation, not a guarantee. A tool variant of a quota-spending operation exposes a quota-spending operation to an agent. What I did is state the cost where the model reads it, and make the free path complete on its own: the credential is only required for validate, so Check Format and both rate operations work with no key attached.

credentials: [
  {
    name: 'vatnodeApi',
    required: true,
    displayOptions: {
      show: { resource: ['vat'], operation: ['validate'] },
    },
  },
],

The node-level description is Validate EU VAT numbers against VIES and look up EU VAT rates, which says nothing about cost. The default toolDescription is that string. If you ship a spending operation, check what your default tool description actually says, and consider whether it should say more. I have not tested which of these strings a model weighs.

Errors a Reader Can Act On

A tool call that fails with a stack trace gives a model nothing to correct. Two small decisions apply to people and models alike.

First, parameters typed as strings are not always strings. An expression like {{ $json.vatId }} resolves to undefined on an item without that field:

function toStringParam(value: unknown): string {
  return value === undefined || value === null ? "" : String(value);
}

In Validate, the empty string then hits an explicit check and throws The VAT number is empty, which is a message the caller can act on, instead of a TypeError from .toUpperCase().

Second, input errors and upstream errors are different types, and the loop isolates failures per item:

} catch (error) {
  if (this.continueOnFail()) {
    returnData.push({
      json: { error: (error as Error).message },
      pairedItem: { item: i },
    });
    continue;
  }
  // Input problems are ours, not the API's – keep them out of NodeApiError.
  if (error instanceof NodeOperationError) {
    throw new NodeOperationError(this.getNode(), error.message, { itemIndex: i });
  }
  throw new NodeApiError(this.getNode(), error as JsonObject, { itemIndex: i });
}

pairedItem keeps the link from each output to its input row. The NodeOperationError versus NodeApiError split tells the user whether their input or the upstream failed.

One more cost detail, in the credential. n8n runs the credential test when you save or test a credential, so a test that validates a real number spends quota each time. The test sends the reserved number XX0000001 instead:

// XX0000001 is the reserved test VAT number: it never reaches VIES and never
// spends quota, so the test only proves that the key is accepted.
test: ICredentialTestRequest = {
  request: { baseURL: "https://api.vatnode.dev", url: "/v1/vat/XX0000001" },
  rules: [
    { type: "responseCode", properties: { value: 401, message: "The vatnode API key is invalid" } },
    {
      type: "responseCode",
      properties: {
        value: 403,
        message: "This vatnode API key is not allowed to validate VAT numbers",
      },
    },
  ],
};

The Verification Path

Verification is a review by n8n, and what it checks is public in the submission and verification guidelines pages. The ones that shaped this build:

No runtime dependencies. The format check needs a pattern per country. Hardcoding a pattern for each of 45 countries (plus an EL alias for Greece) creates a second source of truth, and a dependency is not allowed. So eu-vat-rates-data is a devDependency, and scripts/generate-patterns.mjs writes the patterns into countries.generated.ts at build time. The published package carries the patterns and nothing to install. The only other dependency, n8n-workflow, is a peer dependency.
One service per package, MIT license, matching repo and author. The npm repository URL has to point at the public GitHub repo, and the author has to match.
Scaffolded with n8n-node. Strongly suggested rather than required. The scaffold gives you the lint rules, the release script and the n8n block in package.json, including "strict": true.
Provenance from GitHub Actions. From 1 May 2026, n8n does not accept verified nodes published from a local machine. The publish workflow runs on a version tag, with the permissions it needs and no more:

on:
  push:
    tags: ["*.*.*", "v*.*.*"]
jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read

The workflow publishes from GitHub Actions with npm provenance. The first release used a granular npm token; from the second release the package has been published through npm Trusted Publishing. publishConfig.provenance is true. Releases need @n8n/node-cli 0.23.0 or later.

A README with usage, authentication details and example workflows. The repo ships three importable templates: validating a number from a form, deciding reverse charge before invoicing, and re-checking customer numbers on a schedule.
Submission through the n8n Creator Portal. The review applies to the version you submit.

Limits and Trade-offs

Verification is a review, and review can reject. n8n’s page says it may reject nodes that compete with its paid features. Build the checklist in, but don’t plan a launch around the outcome.
The no-dependencies rule is a real constraint. Anything you’d normally import has to be generated, inlined or written. For patterns, generation works. For something like a parsing library it may not.
usableAsTool puts your node in front of a caller you can’t see. For a read-only free operation that’s harmless. For a spending or destructive one, the description is the only guard in this design. I haven’t evaluated whether it’s enough.
The flag is wrong for nodes that work heavily with binary data, per the template guide.

What to Check Before You Submit

Package name is n8n-nodes-* or @scope/n8n-nodes-*, with the n8n-community-node-package keyword.
Nodes and credentials are listed in the n8n attribute of package.json.
npm run lint passes, and npx @n8n/scan-community-package n8n-nodes-yourpackage is clean.
No runtime dependencies. Generate at build time what you need.
MIT license; repository URL and author match the public GitHub repo.
Published by a GitHub Actions workflow with provenance, not from your laptop.
Every operation and parameter has a description written for a reader who can’t ask a follow-up, and operations that cost something say so.
Empty and missing inputs produce readable errors; continueOnFail and pairedItem are handled.
The credential test does not spend anything.
The README has usage, auth and example workflows.

Who This Is For

If you’re building a node for your own API, the points above are the checklist I’d want. If you only need your tool or API to appear as a working step in n8n, you don’t need to learn any of this.

If you have an API that should be a step in n8n, or exposed to an AI agent as a tool with its cost stated plainly, get in touch – that is API integration work.

Further reading:

n8n VAT validation node – project page – what the node does and how it was released
Building an MCP Server for VAT Validation: Why It’s Two Tools, Not One – the same free-versus-spending split in a different agent interface
Caching VAT and FX Rates at Build Time, Not on the Request Path – the build-time data idea in another setting
n8n: submit community nodes
n8n: verification guidelines

Document Forgery Detection Methods Compared

Iurii Rogulia — Wed, 04 Nov 2026 11:00:52 +0000

A lender receives a payslip as part of a loan application. The PDF came from a real payroll system at a real employer. Before uploading it, the applicant opened it in a PDF editor, raised the gross pay, adjusted the tax and net lines so they still add up, and saved the file again.

On screen the payslip looks exactly like the one the payroll system produced. The extraction step reads every figure cleanly. The arithmetic checks pass, because the applicant did the arithmetic. Nobody calls the employer, because the application looks ordinary. The only place that might record what happened is the file itself: it typically now carries evidence of being modified after the payroll system created it.

That scenario is a composite, not a specific case. It shows why document forgery detection is not one method: different methods answer different questions, and the edited payslip passes every check that asks the wrong one.

Document forgery detection: the four method classes

Document forgery detection splits into four classes of method. Each asks a different question:

Manual review – does a trained person, looking at the document, believe it?
Content-based checks – is what the document says consistent with itself and with other data sources?
Identity and issuer checks – is this the right person, and did the stated issuer actually issue this document?
Structural PDF forensics – was the file changed after it was created?

Content checks judge what the document says; structural checks judge the file’s history. Each misses what the other sees. Manual review and issuer confirmation sit on either side of them: one is human judgement on the surface, the other is the only route to the issuer’s own answer.

Manual review: what a human sees and misses

A reviewer reads the document the way its recipient is meant to: logo, layout, names, dates, totals. Good reviewers catch a lot: an employer that doesn’t exist, a salary that doesn’t fit the job title, a story that doesn’t hang together across the application. Human judgement is also where context lives.

What a reviewer cannot see is the file underneath the page. A PDF that was edited and re-saved can render exactly like the original, so the edit is invisible to anyone looking at it. Manual review also does not scale: every document costs the same human time, and attention drops on the hundredth file of the day. We compare the two approaches directly on PDF tamper detection vs manual review, and we break down the cost side of manual review separately.

Content-based checks: what they validate and what slips through

Content-based methods automate the question ‘is what this document says believable?’. The class covers several techniques:

Extraction and OCR – pulling text and figures out of the document so they can be checked by software rather than by eye.
Internal consistency – does the arithmetic work, do the dates line up, do the totals match the line items, do the account numbers have the right format?
Visual inspection – font, alignment and pixel-level analysis, including AI models trained to spot visual manipulation in a page image.
Data cross-checks – comparing the extracted values against an outside source such as a bank feed, a payroll provider or a company registry.

These methods catch things structure never can. A document with inconsistent figures fails an arithmetic check whatever its file history. A visual model can flag a pasted-in block that doesn’t match the surrounding page. And a data cross-check is the only automated method on this list that tests whether the content is true: if the payroll provider reports a different salary, the payslip is wrong regardless of how it was made.

The limit is that content checks evaluate the result of an edit, not the act of editing. A careful edit to a real document can leave content that is internally coherent and visually clean. Unless a cross-check against an independent source is available for that exact figure, the edited payslip from the opening passes. Cross-checks also depend on access: not every applicant connects a bank account, and not every employer, landlord or supplier is reachable through a feed.

Identity and issuer checks

Identity checks (KYC) confirm that the person in front of you is who they say they are – a government ID, a selfie, a liveness check. They answer a question about the person, not about the payslip or bank statement that person uploads. A real applicant with a valid passport can still submit an edited document. We go through that gap in detail in KYC vs document forensics.

Issuer confirmation – calling the employer, the bank or the registrar – is the strongest evidence that a document was actually issued with the values it shows. It is also slow, manual and often impossible at volume, so most teams reserve it for files something else has already flagged.

Structural PDF forensics

Structural forensics does not interpret what the page says; it examines how the file was built and changed. A PDF is a structured container with its own records, not a picture of a page. Editors can append revisions to it, it carries metadata naming the software that produced it and when, digital signatures cover a defined part of it, and pages can be assembled from more than one source. When a file is opened and saved again, those records usually change, and that change is what structural forensics looks for.

HTPBE works only at this layer. It does not extract or interpret the figures, run OCR, check arithmetic, compare values with outside data or judge what the page looks like. It answers one question – was this PDF modified after it was created – and reports outcomes such as:

‘Content changed after the document was digitally signed’
‘Document re-saved by another tool after its original creation’
‘Evidence that a digital signature was stripped after signing’

Those are labels from the public list on how HTPBE works, which as of October 2026 holds 63 checks across 8 categories. The result is a verdict – intact, modified or inconclusive – plus the named markers that support it. There is no numeric risk score.

Each verdict has a narrow meaning. modified means the file shows evidence of being edited after creation; it is not a finding of fraud, and it should route the file to a person rather than trigger an automatic rejection. inconclusive means the file offers limited structural evidence either way, typically because it came from consumer software, a scanner or a print-to-PDF step – scans and print-to-PDF output never return intact. What inconclusive means covers how to handle that outcome. intact means no structural edit evidence was found.

This is document tamper detection in the narrow sense, and it is one part of PDF fraud detection, not all of it. The anatomy of a modified PDF walks through what changes inside an edited file, binary PDF modification detection goes further into the format, and the product overview is on PDF tamper detection.

Side-by-side comparison

Method	What it inspects	Evidence it produces	Scales?	Blind spot
Manual review	The rendered page and the surrounding application	A reviewer’s judgement	Poorly – time per file is fixed	Edits that leave the page looking identical
Content-based checks	Extracted text, figures, fonts, pixels	Inconsistencies, visual anomalies, data mismatches	Yes, where extraction works	Consistent edits to a real file, when no outside source covers the changed figure
Identity and issuer checks	The person; the issuer’s own records	Identity match; issuer confirmation	Identity checks yes; issuer confirmation rarely	Identity: the document itself. Issuer: volume and unreachable issuers
Structural PDF forensics	The file’s construction and revision history	Verdict plus named markers	Yes – one check per file	Content false from the start; whether the content is true

Every blind spot in that last column is addressed, at least in part, by another row, which is the case for layering them.

What none of these methods can prove

None of the four classes, alone, proves that a document is authentic.

An intact structural result means no evidence of editing was found in the file. It does not mean the issuer produced it, that the figures are correct or that the applicant is who they claim to be. A document whose content was false from the start carries no evidence of a later edit, because nothing was changed afterwards, and a well-resourced forger can sometimes produce a file that shows no structural sign of editing. Structural modification detection does not claim to catch those cases; the reasoning is in can someone create a fake PDF from scratch?. Content and issuer checks are the layers that address them.

The reverse also holds. A clean content check means the numbers are coherent, not that the file is untouched. A matched identity means the person is real, not that their documents are. And no automated method replaces an expert examiner or the issuer’s own confirmation when a decision is consequential. Every result here is an input to a human decision, not the decision.

PDF tampering detection in a layered workflow

In practice, PDF tampering detection sits at intake, before a document reaches the more expensive steps. The shape is similar across industries:

Lending – check bank statements and payslips at upload; route modified files to an underwriter before the application moves on.
HR and background screening – check diplomas, reference letters and employment records as they arrive, and contact the issuer for flagged files.
Insurance – check repair estimates, invoices and medical bills before claim scoring; insurance fraud detection methods covers that vertical in depth.
Accounts payable – check supplier invoices before payment, and confirm bank detail changes by phone through a known contact.

The structural check is automated and runs per file, so it can sit on every upload and leave human and issuer time for the files that earned it. More examples by document type are on detect fake documents, and the integration view is on the document fraud detection API page.

How to choose and combine methods

Decide which questions you need answered and where each answer is cheapest:

Can you get the data from the source? If a bank feed or payroll connection exists for a figure, a data cross-check tests whether it is true. Use it where it is available.
Do you know who the person is? If not, you need an identity check as well – a clean document from the wrong person is still the wrong answer, and a person who passes an identity check can still submit an edited file.
Are the documents PDFs that applicants or suppliers could have edited? Then a structural check on every file is designed to catch the real-document-edited case that content checks can miss.
What happens on a flag? Decide in advance who reviews a modified or inconclusive result and when you contact the issuer. A flag without a review path tends to become an automatic rejection, which is the wrong use of any of these outputs.

If the structural layer is the one you are missing, try it on a file you already have. New accounts start with 5 welcome credits, then checks are pay-per-check. For developers, the HTPBE API is one POST with a PDF URL, returning the verdict and named markers, and test keys are free on every plan.

Frequently asked questions

What is document forgery detection?

Document forgery detection is the set of methods used to decide whether a submitted document can be relied on. In practice it is four different questions answered by four different method classes – manual review (does a trained person believe it), content-based checks (is what it says consistent with itself and with other data sources), identity and issuer checks (is this the right person, and did the issuer actually issue it), and structural PDF forensics (was the file changed after it was created). Each class fails in different places, so they are normally layered rather than chosen between.

Can document forgery be detected without reading the document’s content?

Some of it can. Structural PDF forensics does not interpret the figures or names on the page, and it does not judge what the page looks like. It examines how the file was built and changed – revision layers, metadata and timestamps, signature coverage, how pages were assembled – and reports whether the file carries evidence of being edited after it was created. It is built to catch a real document that was opened and re-saved with new figures, even when the edit is invisible on screen. A document whose content was false from the start carries no such evidence, because nothing was changed afterwards, and structural forensics says nothing about whether the content is true. Those questions belong to content and issuer checks.

What is the difference between structural PDF forensics and content-based document checks?

Content-based checks look at what the document says and shows – extracted text and numbers, arithmetic, fonts and pixels, and how the data compares with bank feeds, payroll records or registries. Structural PDF forensics looks at the file itself – whether it was modified after it was produced. Content checks tell you whether the numbers and pixels look right; structural checks tell you whether the file was edited after it was made. Each misses what the other sees, which is why they work best together.

Does an intact result prove a document is authentic?

No. An intact verdict means no structural evidence of editing was found in the file. It does not prove the issuer produced the document, that the person submitting it is who they claim to be, or that the figures are true. A document whose content was false from the start carries no evidence of a later edit, because nothing was changed afterwards. Treat intact as one input to the decision, and confirm with the issuer when the stakes call for it.

The case for reading a file’s own record, and five questions to put to any file-level check, are in why PDF modification checks read the file, not the page.

VAT Validation in Next.js Server Actions

Iurii Rogulia — Wed, 04 Nov 2026 10:00:50 +0000

This is the implementation for validating a VAT ID inside a Next.js Server Action at form submission: a useActionState hook, a server-only call to vatnode, and a response mapping that distinguishes an invalid number from a check that didn’t complete. For validation that runs live as the customer types, see Real-Time VAT Validation in a React Checkout Form instead – this post is about validating once, on submit.

Why not as-you-type here

The Next.js Server Actions and Mutations guide (checked 2 Oct 2026, docs for Next.js 16) says Next.js dispatches Server Actions from a given client one at a time: a second invocation waits for the first to resolve before it’s sent. Fine for a single submit button, not for a debounced per-keystroke check – a vatnode call can take several seconds when VIES itself is slow, so the action for the ninth keystroke queues behind the one for the fifth, and the UI falls further behind the input with every character typed.

A route handler doesn’t have this restriction – each fetch is an independent HTTP request, which is why the React checkout form post uses one for live validation. A Server Action is the right tool for the submit, the moment that sets the order’s VAT treatment (subject to the re-check before invoicing).

A Server Action is a public POST endpoint

Per the same guide, a Server Action is a route any client sending the matching POST request can reach, whether or not your UI renders a button pointing at it. Next.js checks the request’s Origin against its Host as a CSRF defense, but that’s not application-level authorization – it stops a cross-site form from POSTing to your action, not a well-formed request from a tool that isn’t your form.

For a VAT check, that means an action calling vatnode is a proxy to your API quota. Three things follow:

Validate the input shape locally before making the upstream call – a malformed string shouldn’t reach vatnode at all.
If the form sits behind a login, protect it with your app’s own session check, the same as any other mutation.
Return a shaped result, not whatever vatnode’s response body happens to contain – the Next.js docs call this ‘constrain return values.’

Keep the key server-only

lib/vatnode.ts holds the call and nothing touches it from client code:

// lib/vatnode.ts
import 'server-only'

export interface VatValidationResult {
  valid: boolean
  companyName: string | null
  consultationNumber: string | null
  source: string
  checkId: string
  verifiedAt: string
}

interface VatnodeErrorEnvelope {
  error: {
    code: string
    message: string
    requestId: string
  }
}

type VatCheckResponse =
  | { ok: true; result: VatValidationResult }
  | { ok: false; code: string; message: string }

export async function checkVat(vatId: string): Promise<VatCheckResponse> {
  const apiKey = process.env.VATNODE_API_KEY
  if (!apiKey) {
    throw new Error('VATNODE_API_KEY is not set')
  }

  let res: Response
  let body: unknown
  try {
    res = await fetch(`https://api.vatnode.dev/v1/vat/${encodeURIComponent(vatId)}`, {
      headers: { Authorization: `Bearer ${apiKey}` },
      cache: 'no-store',
      // Keep this above vatnode's own upstream budget, not below it — a
      // short timeout here aborts checks vatnode would have completed.
      signal: AbortSignal.timeout(35_000),
    })
    body = await res.json()
  } catch {
    // Network failure, the timeout firing, or a non-JSON body from a proxy.
    return { ok: false, code: 'NETWORK_ERROR', message: 'Could not reach vatnode.' }
  }

  if (res.ok) {
    return { ok: true, result: body as VatValidationResult }
  }

  const envelope = body as VatnodeErrorEnvelope
  return {
    ok: false,
    code: envelope.error?.code ?? 'UNKNOWN',
    message: envelope.error?.message ?? 'Unknown error',
  }
}

The server-only import turns an accidental client-component import of this module into a build error. process.env.VATNODE_API_KEY – no NEXT_PUBLIC_ prefix – stays out of the browser bundle entirely. If it’s missing, throw at call time; there’s no sane fallback for a missing credential.

Local format check without breaking test mode

Normalize the raw input the same way vatnode’s own API does – trim, uppercase, strip spaces, hyphens, and dots – then run it past validateFormat from the npm package eu-vat-rates-data:

function normalize(raw: string): string {
  return raw
    .trim()
    .toUpperCase()
    .replace(/[\s\-.]/g, '')
}

import { validateFormat } from 'eu-vat-rates-data'

validateFormat('DE123456789') // true
validateFormat('XX0000001') // false

validateFormat runs the ID against per-country regex patterns, and XX isn’t a country – it’s vatnode’s test-mode prefix with no pattern of its own, so it fails the check. Let it through explicitly:

if (!(vatId.startsWith('XX') || validateFormat(vatId))) {
  // reject locally
}

Skipping this check wouldn’t break anything: a vat_live_ key sent an XX id still gets 400 INVALID_FORMAT back from vatnode, and a malformed ID sent to a vat_test_ key gets the same 400 without hitting a fixture. The local check just avoids the round trip. Format-valid is not the same as registered – Greek VAT numbers use the prefix EL, not GR. Northern Ireland uses XI, for goods only.

The action, wired to useActionState

React 19’s useActionState(action, initialState) – imported from react, not react-dom – returns [state, formAction, pending], and the action itself receives (prevState, formData). A file with 'use server' at the top can only export async functions, so the state type and its initial value live in a separate module:

// app/checkout/types.ts
export interface CheckoutState {
  status: 'idle' | 'valid' | 'invalid' | 'unverified' | 'error'
  vatId: string
  message: string | null
  companyName?: string | null
}

export const initialCheckoutState: CheckoutState = {
  status: 'idle',
  vatId: '',
  message: null,
}

// app/checkout/actions.ts
'use server'

import { validateFormat } from 'eu-vat-rates-data'
import { checkVat } from '@/lib/vatnode'
import type { CheckoutState } from './types'

function normalize(raw: string): string {
  return raw
    .trim()
    .toUpperCase()
    .replace(/[\s\-.]/g, '')
}

// Stub — replace with your own persistence. Shown here only so the snippet
// compiles; the point is that it runs regardless of the VAT verdict.
async function saveBillingDetails(vatId: string, verified: boolean): Promise<void> {
  void vatId
  void verified
}

const OPERATOR_ERRORS = new Set([
  'UNAUTHORIZED',
  'INVALID_API_KEY',
  'INVALID_REQUESTER',
  'RATE_LIMITED',
])

const UNVERIFIED_MESSAGE =
  "We couldn't verify your VAT number right now. You can continue; VAT will be charged until it's confirmed."

export async function checkVatAction(
  _prevState: CheckoutState,
  formData: FormData
): Promise<CheckoutState> {
  const vatId = normalize(String(formData.get('vatId') ?? ''))

  if (vatId.length === 0) {
    return { status: 'invalid', vatId, message: 'Enter a VAT number.' }
  }

  if (!(vatId.startsWith('XX') || validateFormat(vatId))) {
    return { status: 'invalid', vatId, message: 'This does not look like a VAT number.' }
  }

  const response = await checkVat(vatId)

  if (!response.ok) {
    if (response.code === 'INVALID_FORMAT') {
      return { status: 'invalid', vatId, message: 'This does not look like a VAT number.' }
    }

    // Your side, not the customer's: a wrong key, a bad requester VAT, an empty quota.
    if (OPERATOR_ERRORS.has(response.code)) {
      console.error('vatnode check needs attention', response)
    }

    await saveBillingDetails(vatId, false)
    return { status: 'unverified', vatId, message: UNVERIFIED_MESSAGE }
  }

  if (!response.result.valid) {
    await saveBillingDetails(vatId, false)
    return {
      status: 'invalid',
      vatId,
      message: 'VIES reports this VAT number as not currently valid for intra-EU transactions.',
    }
  }

  await saveBillingDetails(vatId, true)
  return {
    status: 'valid',
    vatId,
    message: null,
    companyName: response.result.companyName,
  }
}

saveBillingDetails is a stub for whatever your app does with the result – attach it to an order, a customer record, whatever persistence you already have. It runs on every outcome except a malformed ID, including unverified: billing details still get saved, just flagged for a later re-check.

Expected outcomes – invalid, unverified – are returned from the action, not thrown. Nothing here throws except the missing-API-key case in checkVat, which is a deploy misconfiguration, not a user-facing state.

The React form docs say that after a form action succeeds, React resets every uncontrolled field in the form – and an action that returns an error as state has still completed. Return the submitted, normalized vatId in state and bind the input to it with defaultValue, or a rejected number vanishes from the field along with the error explaining why.

// app/checkout/VatIdField.tsx
'use client'

import { useActionState, useId } from 'react'
import { checkVatAction } from './actions'
import { initialCheckoutState } from './types'

export function VatIdField() {
  const [state, formAction, pending] = useActionState(checkVatAction, initialCheckoutState)
  const statusId = useId()
  const isInvalid = state.status === 'invalid'

  return (
    <form action={formAction}>
      <label htmlFor="vat-id">VAT number (optional)</label>
      {state.message && (
        <p id={statusId} role={isInvalid ? 'alert' : 'status'}>
          {state.message}
        </p>
      )}
      <input
        id="vat-id"
        name="vatId"
        type="text"
        inputMode="text"
        autoComplete="off"
        defaultValue={state.vatId}
        aria-invalid={isInvalid}
        aria-describedby={state.message ? statusId : undefined}
      />
      <button type="submit" disabled={pending}>
        {pending ? 'Checking…' : 'Validate VAT number'}
      </button>
    </form>
  )
}

The label sits above the field; the status message sits between the label and the input, not below it, where a phone keyboard hides it; aria-invalid/aria-describedby tie the message to the field for assistive tech. The submit button disables only while pending, with a visible ‘Checking…’ label – not based on whether the current input looks valid. <form noValidate> isn’t needed here, since the input carries no HTML validation attributes of its own.

If you redirect to a confirmation step on success, call redirect() outside any try/catch – the Next.js redirect reference notes that redirect() works by throwing, so catching it anywhere in the call chain swallows the navigation. The example skips the redirect.

Calling vatnode with a bounded timeout

checkVat sets signal: AbortSignal.timeout(35_000). vatnode’s own VIES budget is a 12-second attempt plus, for some failures, a 6-second retry, and for some countries a VIES outage also triggers a national-registry fallback before vatnode answers, so a slow check can take close to half a minute. A shorter timeout on your side aborts checks vatnode would have completed. Keep yours above that budget, not under it, and let vatnode return 504 UPSTREAM_TIMEOUT on its own schedule if VIES doesn’t answer.

A thrown fetch – a network failure, the abort firing, or a body that isn’t JSON – maps to unverified above. There’s no retry loop inside the action: vatnode caches a transient 503/504 for the same VAT ID for 60 seconds (when the account has no requester VAT configured), so an immediate retry would just replay the cached failure, not get a fresh answer.

Mapping every outcome by error code, not HTTP status

Switch on error.code from the envelope { error: { code, message, requestId } }, not on HTTP status alone – AUDIT_WRITE_FAILED and VIES_ERROR both arrive at 502.

Response	Meaning	Action state
`200`, `valid: true`	The number checks out – `source` says which system answered; `companyName` may be `null`	`valid`
`200`, `valid: false`	VIES reports the number as not currently valid	`invalid`
`400 INVALID_FORMAT`	Malformed ID (also returned if a `vat_test_` key gets a non-`XX` id)	`invalid`
`401 UNAUTHORIZED` / `INVALID_API_KEY`	Your key is missing or wrong – your config bug, not the customer’s input	`unverified`
`403 VIES_ERROR`	VIES reports the VAT ID or vatnode’s own IP as blocked (`VAT_BLOCKED` / `IP_BLOCKED`)	`unverified`
`422 INVALID_REQUESTER`	Your account’s dashboard requester VAT is invalid in VIES – your setting, not theirs	`unverified`
`429 RATE_LIMITED`	Monthly quota exceeded	`unverified`
`502 VIES_ERROR`	Unexpected VIES protocol error	`unverified`
`502 AUDIT_WRITE_FAILED`	Check ran, record couldn’t be stored – verdict withheld, no quota spent, safe to retry	`unverified`
`503 VIES_UNAVAILABLE`	VIES is unavailable (without a requester VAT, a national fallback was tried first where one exists for that country)	`unverified`
`504 UPSTREAM_TIMEOUT`	VIES didn’t answer within vatnode’s own budget	`unverified`
`500 INTERNAL_ERROR`	vatnode-side failure unrelated to VIES or the input	`unverified`

Every row except the first three says ‘the check didn’t complete’, not ‘the number is wrong’, so the action maps all of them to unverified. The ones caused by your own setup – the key, the requester VAT, the quota – also get logged, because no customer can fix them. The full code set and how to handle each one outside the UI – retry, cache, log – is in handling VIES errors in code; the contract they come from is in the error reference.

Never block the order on an unverified check

If the check can’t complete, don’t block the order. Treat the customer as unverified: charge VAT as you would for a customer without a valid VAT ID, re-run the check before the invoice is finalized, and – only for a customer in another member state – exempt the intra-Community supply of goods or apply the reverse charge for services once that later check confirms the number. A same-country customer is charged domestic VAT regardless of VAT ID status.

If confirmation arrives after an invoice has gone out, correct it with a credit note and a new, correctly treated invoice – not by editing the original.

A valid: true answer with source: 'VIES' means VIES confirmed the number is registered for intra-EU transactions at the moment of the check. Without a requester VAT, when VIES is down for that country, vatnode can fall back to the national VAT register instead – source then names that register, and there’s no consultation number. When your account has a requester VAT configured, every check skips the cache, so source is always 'VIES' or a named registry; without one, a repeat check within 15 minutes can return 'CACHE' instead, which tells you the number was valid recently, not which authority confirmed it. Store source with the verdict so you know which system confirmed the number, when it isn’t 'CACHE'. In any case, it isn’t a certificate, and it doesn’t tell you which treatment – the exemption for goods or the reverse charge for services – the supply qualifies for.

valid: false means VIES reports the number as not currently valid for intra-EU transactions – the customer may have a domestic-only registration, a typo, or a deregistered number. Charge VAT and let them correct it.

Store the consultation number vatnode returns when your account has a requester VAT set in the dashboard’s Account details – it’s your evidence that you checked. The response also carries checkId and verifiedAt, which are worth storing alongside it.

The Server Action above is the server-side check that happens at submit. ‘Re-run before the invoice’ is a separate, later server-side job – your invoice run, typically – since the action itself doesn’t retry a stale unverified result on its own. The same pattern, applied to a full checkout and to a signup form, is covered in validate VAT numbers at checkout and validate VAT numbers at signup.

Testing with a test key

A vat_test_ key accepts only XX-prefixed IDs, makes no VIES call, and spends no quota:

VAT ID	Result
`XX0000001`	`valid: true`, with a company name
`XX0000002`	`valid: true`, no company name or address
`XX0000003`	`valid: false`
`XX0000004`	`503 VIES_UNAVAILABLE`
`XX0000005`	`502 VIES_ERROR`
Any other `XX…`	`200`, `valid: false`
Non-`XX` ID with a test key	`400 INVALID_FORMAT`

That’s enough to exercise every branch in the action above without touching a live key. More on the full fixture set in test keys and the test-mode docs.

Next steps

Register for a free API key – 100 requests/month, no card. You get a test key straight away and create a live key in the dashboard.
API reference for the full request/response contract.
Pricing if you outgrow the free tier.
EU VAT validation in Node.js for the server-side contract outside of Next.js.
EU VAT validation API overview.

FAQ

Why not call vatnode on every keystroke from a Server Action?
Next.js dispatches Server Actions from the same client one at a time – a second action waits for the first to finish. A debounced per-keystroke action queues behind whatever check is already in flight, and a vatnode call can take several seconds when VIES is slow. For live-typing validation, use a route handler instead; this post covers validating once, on submit.

Is a Server Action safe to call from an unauthenticated form?
A Server Action is a public POST endpoint – anyone who can send the same request body can invoke it, framework CSRF origin checks aside. If the action calls vatnode, it’s a proxy to your API quota, so validate the input shape before the upstream call, put the form behind your app’s own auth/session if it has one, and return a shaped result rather than the raw upstream body.

What does useActionState reset on a failed submission?
React resets every uncontrolled field in the form after the action succeeds, and an action that returns a validation error as state has still succeeded. Return the submitted VAT ID in the action’s state and render the input with defaultValue bound to it, or a rejected VAT ID disappears from the field along with the error message.

Should an unverified VAT check block the order?
No. Treat the customer as unverified – charge VAT as you would for a customer without a valid VAT ID, let the order proceed, and re-run the check before the invoice is finalized. VIES has no uptime guarantee, and blocking checkout on it turns an upstream outage into a lost order.

UK Visa Bank Statement Fraud: What UKVI Actually Checks

Iurii Rogulia — Tue, 03 Nov 2026 11:00:49 +0000

Many people who search ‘how does UKVI verify bank statements’ are applicants. Others are the people helping them: an admissions officer at a university, a sponsor’s HR team, an immigration adviser assembling a bundle. The short answer is that the Home Office can check a bank statement with the bank that issued it. The public versions of its caseworker guidance describe when that happens only in outline and redact the operational detail.

This article sets out what the published rules and guidance say, route by route, and how the Home Office describes checking financial evidence. Then it looks at a narrower question that sits on the intake side, before anything is submitted: whether the PDF statement an organisation is holding was edited after the bank produced it.

Everything below reflects published gov.uk guidance as of October 2026. Immigration rules change several times a year. Each source is cited with the date of the version we read, so check the current page for the route you are working on before relying on any figure here.

Does UKVI verify bank statements?

Yes, it can. The student financial-evidence guidance tells applicants directly: ‘We may verify the evidence with your bank’ (updated 31 December 2025). Appendix Finance (updated 3 August 2026) goes further at FIN 2.1: funds will not be counted if the decision maker cannot make satisfactory verification checks, if the institution holding them is not regulated, or if it does not keep electronic records.

What the guidance does not describe is a check on every statement. The Student caseworker guidance (version 14.0, 3 August 2026) says verification is carried out where there is reasonable doubt about a document or where a risk profile instructs it, and the risk profiles themselves are redacted. The rules and guidance do set out the consequence when a document is found to be false, covered below. The suitability guidance’s definition of a false document includes a genuine document that has been altered or tampered with.

What UKVI asks for, route by route

Financial evidence rules differ by route. Since October 2020, the general position under the Immigration Rules has been more permissive about format than many applicants expect: the Explanatory Memorandum to HC 813 records that the old Appendix P list of acceptable banks was deleted and replaced with a general verification test, and that format rules were removed so electronic statements no longer needed a bank stamp on every page.

Student route

The student financial-evidence guidance (updated 31 December 2025) sets the maintenance figure at £1,171 a month outside London and £1,529 a month in London, for up to nine months. The money must have been held for 28 consecutive days, and the most recent evidence must be dated no more than 31 days before the application. Paper statements and electronic statements downloaded from online banking are both accepted, provided they show the account holder’s name, the bank’s name and the balance. Nationals of listed countries do not have to submit the evidence with the application unless they are asked for it.

Appendix Finance, at FIN 7.1 to 7.3, sets the general rules on dating: evidence must be dated within 31 days of the application, and the holding period is counted back from the closing balance.

Work routes

For sponsored and endorsed work routes, the financial evidence page (last updated 22 August 2022, so read it alongside the current Appendix Finance) describes a maintenance requirement that an A-rated sponsor can certify on the applicant’s behalf instead of the applicant showing personal savings. Where the applicant does provide statements, electronic statements are acceptable without a stamp if they show the date, name, institution and balance. The page also says the Home Office may check the evidence with the bank and may refuse the application if it cannot be verified.

Family routes

Family applications are governed by Appendix FM-SE (3 August 2026), which is more prescriptive than the other routes. Paragraph 1(a) requires statements on official bank stationery or, for electronic statements, a supporting letter from the bank or a bank stamp on every page.

The financial requirement caseworker guidance (version 9.0, 12 September 2025) states that electronic statements need neither a stamp nor a letter. The two published documents read differently on this point, so advisers should check the current wording of the rule and guidance for the specific application rather than rely on either summary here. FM-SE also allows the decision maker, in some cases, to request missing documents or documents in the correct format (paragraph D).

The same caseworker guidance says verification follows local processes, that funds can be disregarded if the bank refuses to verify them, and that ATM mini-statements are not accepted because they do not show enough information and are easy to fake. Much of the remaining procedure is redacted.

Visitors

There is no fixed amount for visitors. The visit caseworker guidance (version 17.0, 25 February 2026) says recent large deposits may be queried for their source, and that documents a caseworker doubts may be verified at source.

How the Home Office checks financial evidence

Read together, the published guidance describes three stages: caseworker review, verification at source when a document is in doubt, and a suitability decision if a document is found to be false.

Caseworker review. A caseworker assesses the evidence against the rules for the route: the amount, the holding period, the dates, the name and the institution.

Verification at source. The document verification guidance (version 1.0, 12 December 2016, still listed on gov.uk) gives the questions a caseworker may put to a bank: whether the account and branch exist, whether the bank knows the applicant, whether the balance is correct, whether the statement is genuine, and whether the person who signed it works there. A finding that a document is false is recorded in a Document Verification Report.

The Student caseworker guidance describes three outcomes for these checks: genuine, false and inconclusive. Where the Home Office’s own verification outcome is inconclusive, the document is discounted; if no other evidence meets the requirement, the caseworker refuses the application or refers the applicant for interview. Keep that term separate from the HTPBE verdict inconclusive discussed below. They share a word and nothing else.

Suitability and consequences. Part Suitability (3 August 2026) sets the outcomes. Under SUI 9.1, deception proven against the applicant, including the use of false documents, leads to mandatory refusal, and SUI 12.1 adds a 10-year re-entry ban after deception. Under SUI 10.1, false documents can lead to discretionary refusal whether or not the applicant knew the document was false, including where a third party supplied it. The suitability guidance (version 1.0, 11 November 2025) defines a false document to include a genuine document that has been altered or tampered with, says the Home Office must prove deception on the balance of probabilities, and notes that discretionary refusals carry no ban.

The public record stops there. It does not describe how the Home Office selects documents for checking beyond the redacted risk profiles, and we do not speculate about it.

Three checks that answer different questions

There are three kinds of check here. Each answers a different question, and none substitutes for another.

Content rules. Does the statement show the right name, bank, balance and dates, and does the money meet the requirement for the route? This is the caseworker’s assessment, and the adviser’s or sponsor’s pre-submission review.
Source enquiries. Does the bank confirm the account, the holder and the balance? Only the bank can answer this, and the Home Office decides when to ask.
File structure. Was this PDF file edited after the software that produced it first wrote it? This is a property of the file, not of the account.

The first two are the Home Office’s process. The third concerns something only the intake organisation holds: the files it has collected before anything is submitted. A university admissions team, a sponsor’s HR team or a regulated adviser (the regulator, formerly OISC, was renamed the Immigration Advice Authority in January 2025) may receive a statement as a PDF attachment. That file has its own construction history, whatever the content shows.

Student Sponsor Guidance Document 2 (version 04/2026) sets no specific duty on sponsors to check applicants’ bank statements. It requires sponsors to act honestly, assess applicants before assigning a CAS and record the evidence they relied on. The specific authenticity duty at paragraph 5.73 concerns qualifications. A file-level check on statements is a choice an organisation makes for its own reasons, and what it buys is narrow: the chance to ask for a fresh copy from the bank before a file the organisation is unsure about goes into a bundle.

What a file-level tamper check can and cannot tell you

HTPBE is a PDF tamper-detection tool. It reads the structure of a PDF and returns one of three verdicts plus a list of named markers describing what it found.

intact means no structural evidence of modification after the file was created. It does not mean the statement is genuine, that the balance is correct, or that the bank issued it.
modified means the file carries evidence that it was changed after it was first generated. Markers name the finding by outcome, for example HTPBE_EDITING_TOOL_FINGERPRINT (signs of a known PDF editing tool), HTPBE_MULTIPLE_REVISION_LAYERS (the document was modified after creation) or HTPBE_ONLINE_EDITOR_ORIGIN (the file passed through an online PDF editing or conversion service).
inconclusive means the file’s structure cannot settle the question either way. It is not a finding that the file was edited, and it is not a finding that it was not. Plenty of legitimate statements return it, including some downloaded directly from a bank.

What it does not do matters as much:

It does not read figures. It does not check balances, totals, the 28-day holding period or the closing date.
It does not establish who owns the account, and it does not confirm anything with the bank.
It does not check identity or eligibility, it is not a KYC or identity-verification service, and it is not part of any Home Office process. Its output has no bearing on a visa decision.
It does not judge whether what a statement says is true. A structural check speaks to the file’s edit history only, which is why the content review and the bank remain the controls for the content itself.

A modified verdict is a statement about the file: it was edited after creation. It is not a finding of fraud, and it says nothing about who made the edit or why. People merge statements into one PDF, redact account numbers before emailing them, and convert files to meet upload limits, all for ordinary reasons.

What to do with a `modified` or `inconclusive` result

Treat both as routing signals inside your own review, never as grounds for adverse action against a person on their own.

modified. Ask for the statement again, obtained directly from the bank: a fresh download from online banking, or a letter or stamped statement where the route expects one. Note the result and what you asked for in your file. If the new copy raises the same question, that is a matter for your organisation’s normal escalation process and, where relevant, professional advice, not something the verdict decides by itself.

inconclusive. This is common on legitimate statements and is not a finding against the applicant. On its own it is not a reason to discount a statement or to treat the applicant differently, but it is not a pass either: it gives no structural assurance in either direction, so your content review carries the weight. Where your review needs a firmer answer, ask for the statement again, obtained directly from the bank, and bear in mind that a fresh bank download can itself return inconclusive.

intact. No structural evidence of an edit after creation. Your content review still applies, and so does every check the Home Office makes after submission.

Where it fits in an intake workflow

The check sits at the point where a PDF statement arrives, before it goes into an application bundle or a CAS assessment. It answers one question about the file and leaves every other question to the people and processes that own them.

For occasional checks, create an account. New accounts normally receive 5 welcome credits, and further checks are pay-per-check; the options are on the pricing page. For volume, the API takes a PDF URL, and the result endpoint returns the verdict and named marker IDs, so the result can be stored against the case record. Test keys return deterministic sample results for wiring up an integration; they never analyse a real file. If you check applicants’ statements through any third-party tool, make sure your lawful basis and privacy notice cover it.

For the wider picture, the immigration document fraud detection hub and the sponsor licence document fraud page cover other document types. Share codes and right-to-work checks are covered in right-to-work and I-9 document fraud. If your team also handles statements outside immigration, see how lenders verify bank statements, the guide to spotting an altered bank statement and the bank statement tamper detection use case.

FAQ

Does UKVI contact the bank to check a statement?

It can. The published guidance tells applicants the Home Office may verify financial evidence with the bank, and caseworker guidance describes verification at source when there is reasonable doubt about a document or a risk profile instructs a check. The detailed procedure is redacted from the public versions.

Is an HTPBE `inconclusive` verdict the same as the Home Office’s inconclusive verification outcome?

No. The Home Office’s own verification outcome of inconclusive means its enquiry with the issuer could not settle whether a document is genuine. An HTPBE inconclusive verdict means the file’s structure cannot settle the question either way: it is neither a finding that the file was edited nor a finding that it was not. It is common on legitimate statements and is not on its own a reason to discount one, but it gives no structural assurance either, so the content review carries the weight.

Can a tamper check confirm the funds requirement is met?

No. HTPBE reads the structure of the PDF file, not its figures. It does not check balances, the 28-day holding period, who owns the account or whether the bank issued the statement. Those questions belong to the decision maker and, where it chooses to ask, to the bank.

What a Fractional CTO Actually Costs

Iurii Rogulia — Mon, 02 Nov 2026 11:01:13 +0000

Most articles about fractional CTO cost answer the wrong question. They quote a day rate, multiply it by two days a week, and present the annual figure like that settles it. It doesn’t. The number that matters isn’t what you pay – it’s what you’re buying instead, and whether you need it at all yet.

So let’s do the honest version. What does part-time senior technical leadership actually cost, what does it replace, and when does the math flip to a full-time hire – or to spending nothing at all for another six months?

(This piece assumes you already know what the role covers. If you’re still working that out, start here first – the numbers below make more sense once the scope is clear.)

The Three Prices You’re Choosing Between

When a non-technical founder has technical decisions piling up and no one qualified to make them, there are really three options on the table, and each has a different price.

A full-time CTO. The salary depends heavily on country and stage – often somewhere in the €120,000–180,000 range in the EU – plus employer costs, plus equity in many cases, plus the six-month search to find one, plus the risk that the person you hire at that price turns out to be wrong for a company your size. The salary is the smallest part of that sentence. The search and the mis-hire risk are the expensive parts.

An agency. You pay a blended rate covering their salaries, overhead, sales team, and margin. The people who scoped your project are rarely the people who build it, and nobody is accountable to you for the architecture two years from now. Agencies are good at delivering defined work. They’re structurally bad at owning your company’s long-term technical direction, because your company isn’t their company.

A fractional CTO. Senior leadership, part-time – typically one to three days a week. You’re paying for judgment, not hours: the architecture calls, the hiring decisions, the vendor evaluations, the ‘don’t build that’ that saves you six weeks. The monthly cost lands well below a full-time salary because you’re buying a fraction of a person’s time, not a fraction of their seniority.

Notice the trick in that comparison. The fractional CTO isn’t cheaper because they’re less experienced. They’re cheaper because you’re only buying the part you actually need – the senior judgment – without the full-time overhead of a role your stage can’t yet keep busy.

Where the Break-Even Actually Sits

The break-even isn’t a spreadsheet line. It’s a question about how much genuine senior decision-making your company generates per week.

A company making one architecture-shaping decision a month does not need a full-time CTO. At that stage a full-timer spends most of the week inventing work to justify the seat – or worse, over-engineering, building for scale you don’t have, adding complexity that becomes someone’s problem later. You’d be paying a six-figure salary for a person busy 20% of the time on the things only they can do.

That same company still feels the pain when those monthly decisions get made badly or not at all. That’s the gap a fractional CTO fills. Picture a CEO with a small in-house dev team where nobody internal is senior enough to make the hard architectural calls, and a full-time CTO doesn’t make sense at that stage. Two days a week is enough to untangle a deployment process, sit in on hiring, and help the team push back on a sales feature request that would have cost six weeks. The value isn’t in the hours. It’s in the six weeks that don’t get wasted.

That’s the real math. If part-time senior judgment prevents one bad hire, kills one unnecessary rewrite, or stops one six-week detour, it has usually paid for a quarter of itself in a single decision. The cost of the engagement is small next to the cost of the mistakes it prevents – and mistakes are exactly what a company accumulates when technical decisions get made by guessing.

slug="fractional-cto"
text="I hold the fractional CTO seat for founders who have real technical decisions piling up but not enough of them to justify a full-time hire. Part-time senior ownership – architecture, hiring, vendor calls – priced against the mistakes it prevents, not the hours it takes."
/>

When You Do NOT Need One Yet

Here’s the part the day-rate articles skip, because it costs them a sale.

If you’re pre-product-market-fit with one strong technical founder, you don’t need a fractional CTO. You need to keep building and shipping. A technical founder who can make reasonable architecture calls is not improved by paying someone to second-guess them monthly. Spend the money on runway.

If you have no engineers and no product yet, you don’t need one either. What you need is someone to build the first version – a senior contractor, or a technical co-founder if you can attract one. Hiring a fractional CTO to oversee a team that doesn’t exist is paying for management of nothing. The leadership need becomes real around the moment you start hiring engineers, not before.

If your technical work is genuinely defined and stable – adding features to a system that works, maintaining integrations, routine development – a contractor does that better and for less. A fractional CTO’s rate is justified by decisions, not by keystrokes. Paying leadership rates for execution work is the most common way founders overspend on this.

The pattern: you need a fractional CTO when you have more senior decisions than senior people to make them – and not before.

When Full-Time Is Actually the Right Spend

And the mirror of that: sometimes the fractional model is the wrong economy, and a full-time hire is genuinely cheaper in the long run.

The clearest signal is volume. When technical decisions stop being monthly and become daily – when your team is large enough that direction, unblocking, and coordination need someone in the room every day – a fractional CTO embedded a day or two a week starts leaving value on the table. Someone part-time carries less context than a full-timer. Past a certain scale, the decisions made while they’re not in the room cost more than the salary you saved.

The honest framing: the fractional model is a bridge, not a destination. A common case is a founder who has just raised and needs to double the team fast, but for whom a full-time CTO is a six-month search they don’t have time for. A fractional arrangement covers the gap – sets up the hiring loop, makes the infrastructure call before it becomes a fire – and when a permanent hire lands, the handover takes a week because everything was documented. That’s the model working as intended: it makes itself unnecessary.

If your company already generates enough senior technical work to keep a full-timer genuinely busy, and you can afford the salary and the search, hire the full-timer. The fractional CTO’s honest job at that point is to help you hire them and hand over cleanly – not to stretch the engagement indefinitely.

The One-Line Test

Strip away the rates and the comparison comes down to a single question: how many decisions that only a senior technical person can make does your company face this month – and does anyone qualified currently make them?

If the answer is ‘several, and no one’ – that’s the fractional CTO case, and the cost will look small against the first bad decision it prevents. If it’s ‘constant, and we need someone here every day’ – that’s the full-time case, and part-time is a false economy. If it’s ‘barely any, and our founder handles them fine’ – you don’t need either yet, and anyone telling you otherwise is selling you a title.

The cost of a fractional CTO is real, but it’s rarely the number that decides this. The number that decides it is what a wrong technical call costs you – and at most stages, that number is a lot bigger than a few days a week of senior judgment.

If you’re trying to work out whether your situation calls for part-time leadership, a full-time hire, or nothing yet, let’s talk it through – I’d rather tell you honestly which one the numbers point to than sell you the one that pays me.

Fake PDF Detector Tools: What They Check and Miss

Iurii Rogulia — Mon, 02 Nov 2026 11:00:47 +0000

You have a PDF in front of you – a bank statement from a tenant, a payslip from a candidate, an invoice from a supplier you have not paid before – and something about it bothers you. So you search for a fake document detector, and you get a page of tools that all claim to answer the same question.

They don’t. Each tool in that list looks at a different part of the file, and each one misses things another would catch. Picking one without knowing which part it reads is how a document gets ‘checked’ and still gets through.

Short answer: what a fake PDF detector actually does

A ‘fake PDF detector’ is not one kind of tool. Some read the metadata fields, some look at the rendered page, some compare the text against expected values, and some examine the internal structure of the file for signs it was changed after it was created. None of them answers ‘is this document genuine?’ on its own – each answers a narrower question, and the useful choice is the one whose question matches what you need to know about the file.

The six kinds of fake PDF detector

Kind of tool	What it inspects	Good at	Where it stops
Metadata viewers	Document properties: producer, creator, creation and modified dates	A fast, free look at what the file says about itself	Shows fields without judging them; fields can be rewritten
Online ‘was this PDF edited’ checkers	Varies by tool – often metadata, sometimes more	A fast first answer, nothing to install	Depth varies; ask what the result is based on
Visual and image-forensics tools	The rendered page and embedded images	Spotting visual anomalies in how the page looks	A cleanly edited PDF can look perfect
OCR and content-consistency checkers	The text and figures on the page	Wrong totals, mismatched names, values that don’t add up	Reads what the page says, not how the file was produced
Manual review	Everything a trained person can see and cross-check	Context, judgement, calling the issuer	Slow, inconsistent at volume, does not see how the file was built
Structural forensics	The PDF’s internal construction and revision record	Whether the file itself was changed after it was created	Says nothing about whether the content is true or who issued it

The rest of this article takes each row in turn. If you want the step-by-step version – how to do these checks yourself on one file – that is covered in how to check if a PDF has been edited.

Metadata viewers and online edit checkers

A metadata viewer opens the document’s properties and shows you what is there: which application created the file, which one last saved it, when each happened. Our own PDF metadata viewer is free and does exactly this, and for a quick look it is useful. If a statement that claims to come from a bank’s system lists a home word processor as the application that made it, you have learned something in ten seconds. Reading the two dates properly is a skill of its own – see checking a PDF’s creation and modification dates.

The limit is that a viewer displays fields; it does not judge them. A producer field that says the file came from a bank’s statement system is a claim the file makes about itself, and that claim can be edited like any other text. A viewer will not tell you whether the file was changed after it was created. For more on that distinction, see PDF tamper detection vs metadata tools.

Online ‘was this PDF edited’ checkers sit one step further along: you upload a file and get an answer back. Depth varies between tools. Before you rely on any edited PDF checker, ask one question: is the result drawn from the metadata fields alone, or from the file’s structure as well? That tells you which of the questions in this article it is answering.

Visual, AI-image and OCR checkers

These tools work on what the page shows. Image-forensics tools look at the rendered page and its images for visual anomalies. OCR and content-consistency checkers extract the text and figures and test them: does the running balance add up, do the names and dates agree across the document, is the tax consistent with the gross.

This is the class of tool that reads what the document says, so it is where wrong figures and altered values get caught. Structural analysis cannot answer ‘are these numbers right?’, and neither can a metadata viewer.

The limit follows from the same fact. A cleanly edited PDF can look perfect and produce consistent figures. A tool that only reads the rendered page has nothing to object to: it tells you how the document looks, not what happened to the file.

Detecting AI-generated documents is a different question again – whether content was produced by a generative model, not whether an existing file was changed. If that is your concern, we cover what works and what does not in detecting AI-generated PDFs.

Manual review

A person who knows the document type is still the best tool for context. They notice a payslip dated on a Sunday, an employer address that does not match the company register, an account number in the wrong format for that bank. They can phone the issuer. No automated tool does that.

Manual review has three costs. It is slow. It is inconsistent – two reviewers on the same file, or one reviewer at 9am and at 5pm, will not reach the same conclusion every time. And it does not see how the file was built: a reviewer looking at a well-made edit on screen sees the same perfect page the visual tools see. PDF tamper detection vs manual review goes into where each one fits.

What structural forensics adds

Every PDF carries a record of how it was put together – its dates, its revisions, its signature state and how its pages were produced. Structural PDF analysis reads that record and asks one question: was this file changed after it was created?

That is the layer HTPBE covers. You submit a PDF and get one of three verdicts – intact, modified or inconclusive – and, when something was found, a list of named markers describing what it was. At outcome level, the findings look like this:

Dates that disagree – the file’s date records do not support the history it presents (HTPBE_DATES_DISAGREE is one of the public marker IDs).
Edits after signing – content changed after the document was digitally signed (HTPBE_POST_SIGNATURE_EDIT), or a signature stripped after signing.
Pages from multiple sources – pages assembled from independently produced documents (HTPBE_PAGES_FROM_MULTIPLE_SOURCES).
Editing-tool traces – fingerprints of a known PDF editor, or the identity of an online editing or conversion service.
Revision history – the document re-saved after its original creation.

The full list of public markers and what each one means is on how HTPBE works. The PDF tamper detection page covers the approach in more depth, and viewing a PDF’s edit history explains the revision record itself.

What structure adds is evidence the other classes do not look at. A clean visual edit is still an edit, and the file often records that it happened even when the page looks untouched.

If you have one file and want to see this in practice, start with checking whether a PDF was edited.

What no PDF detector proves, including ours

Be clear about the boundary before you build a decision on any of these tools.

intact does not mean authentic. It means the structural analysis found no evidence the file was changed after it was created. It does not mean the content is true, and it does not mean the document was issued by the party named on it. HTPBE detects modification of the file – not whether what the file says is correct.
HTPBE does not read the content. It does not run OCR, check arithmetic, compare names or validate figures. That is the job of the content-checking class above.
It is not identity or issuer verification. It does not confirm who someone is, check a document against an issuer’s records, or perform KYC.
inconclusive is neither a pass nor proof of fraud. Usually it means the file came from a source – ordinary consumer software, a scan and similar – where a structural check cannot confirm integrity either way; occasionally it means the analysis could not finish, in which case treat the file as unchecked rather than clean. Judge it against the origin the document claims: a statement presented as coming from a bank’s system that returns inconclusive needs a closer look through your other checks, and the safe next step is to request the original from the issuer.
No verdict is a decision. A modified result is a reason to look more closely or ask questions, not a reason to reject an applicant automatically. Route it to a person.

How to choose: a decision guide

Start from what you are trying to find out, and how many files you handle.

One file, one decision. Open it in a metadata viewer for a first look. Run a structural check to see whether the file was changed after it was created. Read the content yourself against what you already know – names, dates, amounts. If the stakes are high, contact the issuer through a channel you find independently, not one printed on the document.

Recurring volume – a lettings agent screening tenants every week, an HR team checking candidate documents, a small lender reviewing applications. Manual review alone stops scaling, and its inconsistency starts to matter. Put a structural check on every incoming file so reviewers know which ones to open first – files that come back intact still get your normal content review, because the check sets priority, it does not approve anything. Keep content checks for the figures that drive the decision and issuer contact for the cases that warrant it. If you are looking for a fake document detector for a specific document type, the use-case pages show what the check covers for each.

Integration into your own system. If documents arrive through an application form or an upload flow, the check belongs in the pipeline, not in someone’s browser. With the HTPBE API you submit a PDF URL and fetch the verdict and named markers as JSON, so modified and inconclusive files land in the review queue automatically, alongside the content checks every file still gets.

Frequently Asked Questions

Is there a free fake PDF detector?

Several tools are free for a quick look, including our PDF metadata viewer. For structural analysis, an HTPBE account comes with 5 free credits at signup – one credit per check – so you can run a few files before paying anything. After that, checks are pay-per-check: $5 for 8 credits or $15 for 25. See pricing.

Can a PDF edit checker tell me what was changed?

Not the specific words or numbers. A structural check tells you whether the file was modified and, if so, what kind of evidence was found – dates that disagree, an edit after signing, pages from different sources. To see which values on the page are wrong, you need to read the content against a trusted source.

Does a PDF integrity checker prove a document is genuine?

No. An integrity check speaks to the file – whether there is evidence it was changed after it was created – not to the facts in it or who issued it. For high-stakes documents, combine a structural check with content review and contact with the issuer.

Can I run a PDF fraud checker automatically on every document?

Yes, through an API. You submit a PDF URL to the HTPBE API and fetch a verdict with named markers. Subscriptions start at $15 a month. Treat the result as input to your review queue, not as an automatic accept or reject.

Where to go from here

If you are deciding whether to build this layer in-house or use a service, build vs buy PDF tamper detection works through the trade-offs. If you have a file to look at now, create an account and use the 5 welcome credits on it. If documents reach you through your own system, start with the API.

What to put around any detector once you have chosen one – source confirmation, callbacks, retention and escalation – is set out in PDF fraud prevention: a layered playbook.

When a B2B Customer Won't Give You a Valid VAT Number

Iurii Rogulia — Mon, 02 Nov 2026 10:00:52 +0000

Short answer: none of the three outcomes stops you from invoicing. No number and a confirmed-invalid number both mean the cross-border exemption or reverse-charge treatment isn’t available right now, so you charge VAT as you would to any customer without one – the exact rate and place of supply depend on whether you’re selling goods or services. An unavailable check is different again: it’s not a negative result, so retry it, record the attempt, and either hold the invoice or charge VAT and correct it once the number is confirmed.

This post covers B2B customers established in another EU member state. A customer in your own country is a domestic sale either way – neither the cross-border exemption nor the standard reverse-charge rules apply to it, though some countries run their own domestic reverse-charge regimes for specific sectors. Check that separately if it’s relevant to you.

Three situations, and they’re not the same problem

No VAT number given at all

Some customers genuinely don’t have one – they’re below their own country’s VAT registration threshold, or they’re a sole trader who hasn’t registered. Others just haven’t filled in the field yet. Either way, you have nothing to verify, so there’s nothing to zero-rate against.

A number was given, but it doesn’t check out

The string exists, but it fails when you run a VAT check against it. Several things can produce ‘invalid’: the number was never registered, the business hasn’t completed the separate intra-EU registration some member states require, or the registration lapsed. One of the more common causes is a number that’s valid domestically but not activated for intra-EU transactions – VIES reports it as invalid even though the business is VAT-registered at home. VIES invalid for a domestic-only registration covers how that cause plays out and what to tell the customer. And don’t confuse ‘invalid’ with ‘badly formatted’ – a string that merely fails the pattern check is a different, earlier problem; see format-valid vs. actually registered for that distinction.

VIES or a member-state service can’t confirm it right now

This one gets mistaken for invalid constantly. An unavailable check means the lookup didn’t complete – not that the number failed. Retry it, and keep a record of the attempt and its timestamp regardless of outcome. Handling VIES downtime and the error reference show what the response looks like in that case, so you can tell it apart from a genuine negative in code rather than by eyeballing a dashboard.

What EU rules actually let you assume

There’s no general EU obligation to collect a VAT number from every B2B customer. The rules describe what you can rely on once you do have one – or once you’ve established you don’t.

For services, Implementing Regulation 282/2011 Article 18 sets out two routes. Under Article 18(1)(a), unless you have information suggesting otherwise, you may treat an EU customer as a taxable person once they’ve given you a VAT ID and you’ve obtained confirmation – per Article 31 of Regulation (EU) No 904/2010 – of both its validity and the associated name and address. Under Article 18(1)(b), a customer who says they’ve applied for a number but doesn’t have one yet can still be treated as a taxable person if you have other proof of that and you’ve done reasonable verification. And under Article 18(2), unless you have information to the contrary, you may treat a customer as non-taxable once you can show they haven’t given you a VAT ID at all. Note the word ‘may’ throughout – this is a permission and a presumption you’re allowed to rely on, not a mandatory checklist with one correct outcome.

For goods, the relevant condition sits in Directive 2006/112/EC Article 138(1), as amended by Directive (EU) 2018/1910 from 1 January 2020: the exemption requires the customer to be identified for VAT in another member state and to have given you that VAT ID, plus a correct recapitulative statement under Article 138(1a). It’s one condition among several – transport evidence is the other half – but if no qualifying number is indicated to you (or only a number from the dispatch country), the exemption doesn’t apply and you must charge VAT.

What to charge instead

Goods. No valid VAT ID means the Article 138 exemption isn’t available, but that doesn’t automatically make it a domestic-rate sale. If the customer is a genuine taxable person who just didn’t share a number, VAT is normally due in the country where transport begins, at your own rate. If the customer is actually non-taxable for VAT purposes – a non-taxable legal person, or a business below its own country’s acquisition threshold under Article 3(1) – you’re making an intra-Community distance sale under Articles 14(4) and 33(a): VAT is due where the goods end up once you’re over the same combined €10,000 Article 59c threshold described below, usually accounted through the One Stop Shop.

Services. Don’t flatten this to ‘charge your own rate.’ The general rule (Article 45) puts the place of supply where you’re established, so for most B2B services without a valid customer VAT ID, you’d apply your own country’s VAT. But most SaaS falls under the specific rule for telecom, broadcasting, and electronically supplied services (Article 58), which puts the place of supply where the customer is, once you’re over the combined EU-wide €10,000 threshold in Article 59c for suppliers established in only one member state. That threshold counts these cross-border service sales together with any intra-EU distance sales of goods you also make. Below that threshold you can still apply your own domestic VAT; above it, VAT for other member states is usually accounted through the One Stop Shop rather than registering separately in each one. A handful of other services have their own place-of-supply rules too. If you’re not sure which rule a service falls under, confirm it before you decide what to charge: the wrong assumption here is a recurring source of mispriced invoices, not just a paperwork gap. When reverse charge applies and how it’s invoiced is covered in the reverse-charge concept guide and by-country invoice wording.

In both cases this isn’t a one-off decision per customer. Know when to re-check a customer’s VAT number, so a number that starts invalid or missing doesn’t stay that way in your records after it’s been fixed.

What to tell the customer

No number at all. Tell them plainly that without a VAT ID you’ll charge VAT as you would for any customer without one, and that you’ll switch the treatment as soon as they provide a number that checks out. If they’re a sole trader, their VAT number can be built from a personal national identifier in some member states – reluctance to hand it over in a support chat might be a privacy concern, not an attempt to dodge tax. The same applies on your side: a sole trader’s VAT number, name and address are personal data, so keep them in your billing records where you need them, not in support transcripts, debug logs or analytics.

Invalid number. Say exactly what failed – the number didn’t come back confirmed – and ask them to double-check it with whoever handles their VAT registration, since a typo and an unregistered number look identical from your side. Don’t promise to retroactively fix the invoice until you actually have a number that checks out.

Check unavailable. Tell them the check didn’t complete, not that their number is wrong – that distinction matters to the finance team reading your email. Let them know you’ll retry, and that the failed lookup says nothing yet about their registration.

If it later turns out VAT shouldn’t have been charged, the usual fix runs through you, not the customer’s tax authority: you correct the invoice and refund the VAT, then adjust your own return under your national rules. The cross-border refund procedure under Directive 2008/9/EC covers VAT that was correctly charged and is deductible, not VAT invoiced in error. If a customer pushes back, tell them how you correct invoices, and don’t promise a refund outcome on their side.

What to record

Keep the same three things for every outcome: what you asked for, what came back, and when. A definitive invalid result, a definitive ‘no number given,’ and a transient unavailable result all look different in an audit, and conflating them later is how a routine outage turns into a disputed invoice years on. What auditors look for in EU VAT documentation covers the fuller checklist; if you’re set up to run requester-qualified checks, the consultation number VIES issues on those is the strongest form of that evidence – see the VIES consultation number for finance teams.

vatnode’s GET /v1/vat/:vatId on this EU VAT validation API returns valid as true or false along with source, a timestamp, and a check ID on every answered check. An outage is never reported as a silent ‘invalid’: either a national source answers instead, and source says so, or the call comes back as an error such as VIES_UNAVAILABLE. A national-source answer isn’t the same as a VIES confirmation, though. It reflects that country’s own register, which may not show whether the number is activated for intra-EU transactions, so check source before relying on a valid: true for the exemption or the reverse charge. The three outcomes above are distinguishable in the response itself, not just on a dashboard. The consultation number is included once your account has an EU VAT number set in dashboard Account details and VIES answers live.

If the number arrives later

If a customer sends a valid number after you’ve already invoiced them without one, there’s no EU-wide deadline or procedure forcing a fix within a set window. Article 219 treats a document that amends and clearly references the original invoice – a credit note plus a corrected one – as an invoice in its own right, so that’s the usual mechanism. Whether you do it, and how, is a matter of national law and your own process. A number arriving later doesn’t by itself mean the original invoice was wrong. If you applied Article 18(2) correctly, or charged VAT on the information you had and had no information to the contrary, you were relying on a presumption the rules expressly allow. Zero-rating on a number that later turns out to have been invalid is a different, higher-stakes problem – covered in what happens when you reverse-charge an invalid VAT number.

FAQ

A customer has no VAT number at all – what do I charge?

For services, Implementing Regulation 282/2011 Article 18(2) lets you treat them as a non-taxable person when you can show they haven’t communicated a VAT ID, and charge accordingly. For most SaaS that means the place-of-supply rule for electronically supplied services: your own country’s VAT below the EU-wide €10,000 threshold for suppliers established in one member state, the customer’s country’s VAT above it. For goods, the Article 138 exemption needs a VAT ID the customer gave you; without one, it doesn’t apply. VAT is then normally due where transport begins if the customer is a genuine taxable person who just withheld the number. If they’re non-taxable or below their own acquisition threshold, it’s an intra-Community distance sale, taxed at destination above the combined €10,000 threshold. This is general information, not tax advice for a specific transaction.

The customer gave a number but VIES says it’s invalid – can I still zero-rate?

No, not on this number. The goods exemption (Article 138), and the Article 18 customer-status presumption that lets you apply reverse charge under Article 196 instead of your own VAT, both depend on a VAT ID that actually checks out. For services the treatment is reverse charge rather than a zero-rated line, because the place of supply moves to the customer’s country. An invalid result means that condition isn’t met at this time, regardless of why – unregistered, not yet activated for intra-EU transactions, or simply wrong. Ask for a correction or fall back to charging VAT; don’t treat an invalid number as a formality to wave through. This is general information, not tax advice for a specific transaction.

VIES is down and won’t confirm the number – is that the same as invalid?

No. An unavailable check is a different outcome from invalid. The number may be perfectly valid; the lookup just didn’t complete. Retry, and keep a record of when you tried and what came back. Until the number is confirmed you can’t rely on it for the exemption or the reverse charge, so either hold the invoice until a retry succeeds – within the Article 222 deadline for exempt and reverse-charge supplies, the 15th of the month after the chargeable event – or charge VAT now and correct it once the number is confirmed. If you’ve already been paid for services, Article 65 can make VAT chargeable on receipt, so holding the document alone may not move the tax point. Don’t record the outage as an invalid result.

Do I have to ask every customer for a VAT number before I can invoice them?

No EU-wide rule requires it. Asking is how you access the exemption or the reverse-charge treatment where it applies; a customer who doesn’t have or won’t give a number is simply treated under the rules for a customer without one. Not providing one doesn’t stop you invoicing them.

If a valid number arrives after I’ve already invoiced without one, do I have to redo the invoice?

There’s no EU-wide procedure or deadline for this. A document that amends and clearly references the original invoice is itself treated as an invoice under Article 219, so a credit note plus a corrected one is the usual route – but whether and how to reissue is a matter of national law and your own process, not a single EU rule.

PDF Tamper Detection in Rust: Integration Guide

Iurii Rogulia — Sun, 01 Nov 2026 11:00:46 +0000

This guide covers one narrow job: checking whether a PDF file was structurally modified after it was created, from a Rust service, before your business logic trusts it. It is not KYC, not identity or issuer verification, not OCR and not AI-generated-content detection. The check looks at the file’s structure and metadata, says whether that structure shows evidence of post-creation editing, and leaves the person who sent it entirely out of the answer.

The PDF tamper detection API is a small REST surface: one POST to submit a URL, one GET to read the verdict. There is no official Rust SDK, so this guide builds a client by hand against the REST contract with reqwest, serde, thiserror and tokio: result types, an error enum that knows what is worth retrying, idempotent retries, an axum handler that routes each verdict, and a presigned-URL helper for private buckets.

If you want the concepts first, read How to Detect PDF Tampering Programmatically. The same integration exists for Go, Node.js, Python, Java / Spring Boot, C#, Laravel / PHP and Ruby on Rails.

TL;DR

Two calls: POST /analyze takes a PDF URL and returns 201 with a check id; GET /result/{id} returns a flat JSON object whose status is intact, modified or inconclusive.
Analysis is synchronous. When the POST returns, the result is ready to read.
Send an Idempotency-Key on every POST and reuse it on every retry of that request. A retry of a completed request returns the same id and is not charged again.
Retry 409, 429, 500, 502, 504 and transport failures with the same key. Never retry 400, 401, 402, 403, 404, 413 or 422; a 503 surfaces as a pending check to retry once later.
Route on usage_caution.recommended_action. No branch in this guide auto-declines a person: the API marks every verdict safe_for_automated_adverse_decision: false.
A structural verdict is about the file. intact means no structural modification was detected, not that the document is genuine or its contents are true.

Prerequisites

A recent stable Rust toolchain.
An HTPBE account. Every account has a test key (htpbe_test_...) on the API keys page of the dashboard; live keys start with htpbe_live_....
These dependencies, at the crate versions the listings below target:

[dependencies]
reqwest = { version = "0.13", features = ["json"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread", "net", "time"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
thiserror = "2"
uuid = { version = "1", features = ["v4"] }

# Step 5 (HTTP handler) and Step 6 (presigned URLs) only
axum = "0.8"
aws-config = "1"
aws-sdk-s3 = "1"

json is an opt-in reqwest feature, so it has to be listed. In reqwest 0.13, query also became a separate feature that is off by default, so this guide builds query strings by hand rather than calling .query().

The listings assume four modules under src/htpbe/:

// src/htpbe/mod.rs
pub mod client;
pub mod error;
pub mod routing;
pub mod types;

src/main.rs declares mod htpbe; (Step 5). Add mod upload; if you use the Step 6 helper.

Step 1: Test the API with curl

Before any Rust, confirm the key and the flow with curl, using your test key and a fixed test URL (test keys accept only those and never consume credits).

Submit the file:

curl -i -X POST https://api.htpbe.tech/v1/analyze \
  -H "Authorization: Bearer htpbe_test_YOUR_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c2f6b6e-1a3d-4b8a-9c3a-2e6f1d9b4a10" \
  -d '{"url": "https://api.htpbe.tech/v1/test/signature-removed.pdf"}'

The response is 201 Created with a Location header pointing at the result URL and a body that contains only the id:

{ "id": "00000000-0000-4000-8000-00000000000c" }

Read the result:

curl https://api.htpbe.tech/v1/result/00000000-0000-4000-8000-00000000000c \
  -H "Authorization: Bearer htpbe_test_YOUR_TEST_KEY"

The response is one flat object. Trimmed to the fields this guide uses, it looks like this:

{
  "id": "00000000-0000-4000-8000-00000000000c",
  "filename": "signature-removed.pdf",
  "check_date": null,
  "status": "modified",
  "modification_confidence": "certain",
  "modification_markers": ["HTPBE_SIGNATURE_REMOVED"],
  "signature_removed": true,
  "modifications_after_signature": false,
  "usage_caution": {
    "safe_for_automated_adverse_decision": false,
    "recommended_action": "route_to_human_review",
    "message": "Structural evidence of post-creation modification was found. Route this document to a human reviewer before any decision — do not use this verdict as the sole basis for an automatic adverse decision against a person."
  }
}

check_date is null for test results. Swap the URL for clean.pdf, dates-mismatch.pdf, inconclusive.pdf or scanned-document.pdf to see the other shapes.

Step 2: Result types with serde

serde skips JSON fields your struct doesn’t declare (so don’t add deny_unknown_fields): the struct can be partial, and a field added to the API later can’t break decoding. Each enum has a #[serde(other)] catch-all, so a value added after you ship decodes as Unknown, and Step 5 sends Unknown to a person.

// src/htpbe/types.rs
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Status {
    Intact,
    Modified,
    Inconclusive,
    #[serde(other)]
    Unknown,
}

/// Present only when `status` is `inconclusive`. It explains why the
/// integrity check could not reach `intact` or `modified`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum StatusReason {
    ConsumerSoftwareOrigin,
    OnlineEditorOrigin,
    ScannedDocument,
    UnverifiableMetadata,
    FilledFormOrigin,
    FillSignOrigin,
    VisibleSignatureOrigin,
    /// Describes the check, not the document: part of the analysis did not finish.
    AnalysisIncomplete,
    #[serde(other)]
    Unknown,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Confidence {
    Certain,
    High,
    /// The wire value is "none". Renamed so it doesn't read like `Option::None`.
    #[serde(rename = "none")]
    NoneDetected,
    #[serde(other)]
    Unknown,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum RecommendedAction {
    RouteToHumanReview,
    RequestFromIssuer,
    NoAction,
    #[serde(other)]
    Unknown,
}

#[derive(Debug, Clone, Deserialize)]
pub struct UsageCaution {
    /// Always false. The verdict alone must never drive an adverse decision.
    pub safe_for_automated_adverse_decision: bool,
    pub recommended_action: RecommendedAction,
    pub message: String,
}

/// The flat GET /result/{id} response. Partial on purpose: serde skips
/// any field not declared here, so new API fields never break decoding.
#[derive(Debug, Clone, Deserialize)]
pub struct CheckResult {
    pub id: String,
    pub filename: String,
    /// Unix seconds. Null for test-key results and legacy records.
    pub check_date: Option<i64>,
    pub file_size: u64,

    pub algorithm_version: String,
    pub current_algorithm_version: String,
    /// Present only when the check ran on an older algorithm version.
    pub outdated_warning: Option<String>,

    pub status: Status,
    pub status_reason: Option<StatusReason>,
    /// Null on legacy records.
    pub modification_confidence: Option<Confidence>,
    /// Public HTPBE_* ids, strongest first.
    pub modification_markers: Vec<String>,

    pub has_digital_signature: bool,
    pub signature_removed: bool,
    pub modifications_after_signature: bool,

    pub page_count: u32,

    pub usage_caution: UsageCaution,
}

Markers stay Vec<String>. The HTPBE_* ids are append-only, so an enum would break on the first new one. Branch on the ids you care about and render labels from the dictionary on how PDF tamper detection works; the first marker is the strongest.

outdated_warning is worth logging: it means the stored check ran on an older algorithm version.

Step 3: A typed error enum

The retry loop needs to know whether the same request could succeed if sent again; the handler needs to know what to tell the caller. One enum serves both if it keeps the HTTP status, the code and Retry-After. The API’s error body is {"error": "...", "code": "...", "details": "..."}, but a proxy in front of it can answer with HTML, so parsing is best effort.

// src/htpbe/error.rs
use std::time::Duration;

#[derive(Debug, thiserror::Error)]
pub enum HtpbeError {
    /// A non-2xx response from the API (or from something in front of it).
    #[error("HTPBE API returned {status} ({code}): {message}")]
    Api {
        status: u16,
        /// Machine-readable code, e.g. "payment_required". "unknown" when
        /// the body was not the API's JSON error shape.
        code: String,
        message: String,
        details: Option<String>,
        /// Parsed from Retry-After (seconds) when the response carried it.
        retry_after: Option<Duration>,
    },

    /// Connect failure, timeout, reset connection, unreadable body.
    #[error("transport error: {0}")]
    Transport(#[from] reqwest::Error),

    /// A 2xx response whose body did not match the documented shape.
    #[error("unexpected response body: {0}")]
    Decode(#[from] serde_json::Error),

    #[error("configuration error: {0}")]
    Config(&'static str),
}

impl HtpbeError {
    /// Whether sending the SAME request again (same Idempotency-Key) could succeed.
    pub fn is_retryable(&self) -> bool {
        match self {
            // 409 idempotency_key_in_progress: the original is still running.
            // 429 server_at_capacity: server-wide concurrency, not your quota.
            // 500/502/504: transient on the server side or in front of it.
            // 503 is NOT retried here: it surfaces to the caller (CheckPending).
            HtpbeError::Api { status, .. } => matches!(*status, 409 | 429 | 500 | 502 | 504),
            // Timeouts and dropped connections are exactly what the
            // Idempotency-Key exists for. A builder error is a bug, not a blip.
            HtpbeError::Transport(e) => !e.is_builder(),
            // A malformed 2xx body will be malformed again.
            HtpbeError::Decode(_) | HtpbeError::Config(_) => false,
        }
    }

    pub fn code(&self) -> Option<&str> {
        match self {
            HtpbeError::Api { code, .. } => Some(code.as_str()),
            _ => None,
        }
    }

    pub fn retry_after(&self) -> Option<Duration> {
        match self {
            HtpbeError::Api { retry_after, .. } => *retry_after,
            _ => None,
        }
    }

    /// 409 idempotency_key_in_progress: the original request with this key
    /// is still running. The retry loop waits on it separately.
    pub fn is_in_progress(&self) -> bool {
        matches!(self, HtpbeError::Api { status: 409, .. })
    }

    /// No credit source left on the account. Not retryable: it fails the
    /// same way until credits are added, so send it to whoever owns billing.
    pub fn is_out_of_credits(&self) -> bool {
        self.code() == Some("payment_required")
    }
}

code stays a String for the same reason as the markers. The codes worth knowing:

Status	`code`	Retry?	What it means for you
400	`invalid_request`, `invalid_url_format`, `download_failed`	No	Bad body or URL, or the server could not fetch the file
401	`missing_api_key`, `invalid_api_key`	No	Configuration problem; alert, don’t loop
402	`payment_required`	No	No credits left on the account
403	`inactive_client`, `test_url_required`, `account_restricted`	No	Key deactivated, test key with a real URL, or account restriction
404	`not_found`	No	Unknown id, or an id owned by another account
409	`idempotency_key_in_progress`	Yes	The original request with this key is still running
413	`file_too_large`	No	Over the 10 MB limit
422	`invalid_pdf`, `idempotency_key_fingerprint_mismatch`	No	Unreadable PDF, or one key reused for two different URLs
429	`server_at_capacity`	Yes	Server-wide concurrency limit; honour `Retry-After`
500	`internal_error`	Yes	Server-side error; retry with the same key
503	`internal_error`	Later	No result stored, no `Retry-After`; contact support if it repeats

The client retries 500 (and a 502 or 504 from a proxy) within its attempt cap. A 503 is left to the caller: the handler in Step 5 records it as check pending, to be retried once later.

Step 4: The client

Build one reqwest::Client at startup and share it: it pools connections and is cheap to clone.

Three design points drive the rest of the code.

Timeouts sized to the server’s limits. The server allows 30 seconds to download your file and 20 to analyse it before the POST returns, so the client allows 90 seconds per request, plus a short connect timeout. Anything tighter cuts off slow but valid checks and triggers pointless retries.

One Idempotency-Key per logical request, owned by the caller. check_pdf takes the key as an argument and resends it on every retry, so a retry of a completed request returns the same id with no second charge. The caller owns it because the logical request can outlive one call: a pending case retried later, while its document URL is still valid, must send the same key and the same URL, or it risks spending credit twice on one document.

POST and GET are retried separately. Once you have an id, a failed read is retried by reading again, never by re-submitting.

// src/htpbe/client.rs
use std::future::Future;
use std::time::{Duration, SystemTime, UNIX_EPOCH};

use reqwest::header::RETRY_AFTER;
use reqwest::Response;
use serde::{Deserialize, Serialize};

use super::error::HtpbeError;
use super::types::CheckResult;

const DEFAULT_BASE_URL: &str = "https://api.htpbe.tech/v1";
const MAX_RETRY_AFTER_SECS: u64 = 60;
/// How long to keep waiting on a 409 (original request still running).
const MAX_IN_PROGRESS_WAIT: Duration = Duration::from_secs(90);

#[derive(Clone)]
pub struct HtpbeClient {
    http: reqwest::Client,
    base_url: String,
    api_key: String,
    max_attempts: u32,
}

#[derive(Serialize)]
struct AnalyzeRequest<'a> {
    url: &'a str,
    #[serde(skip_serializing_if = "Option::is_none")]
    original_filename: Option<&'a str>,
}

#[derive(Deserialize)]
struct AnalyzeResponse {
    id: String,
}

#[derive(Deserialize)]
struct ErrorBody {
    error: String,
    code: String,
    details: Option<String>,
}

impl HtpbeClient {
    pub fn new(api_key: impl Into<String>) -> Result<Self, HtpbeError> {
        let api_key = api_key.into();
        if api_key.is_empty() {
            return Err(HtpbeError::Config("HTPBE API key is empty"));
        }
        let http = reqwest::Client::builder()
            .connect_timeout(Duration::from_secs(10))
            // Above the server's 30 s download + 20 s analysis limits,
            // so a slow but valid check is never cut off client-side.
            .timeout(Duration::from_secs(90))
            .build()?;
        Ok(Self {
            http,
            base_url: DEFAULT_BASE_URL.to_owned(),
            api_key,
            max_attempts: 4,
        })
    }

    /// Point the client at a mock server in tests.
    #[allow(dead_code)]
    pub fn with_base_url(mut self, base_url: impl Into<String>) -> Self {
        let base_url: String = base_url.into();
        self.base_url = base_url.trim_end_matches('/').to_owned();
        self
    }

    /// One logical check: submit (retried under the caller's key), then read.
    /// Persist `idempotency_key` with the case and reuse it if you retry later.
    pub async fn check_pdf(
        &self,
        pdf_url: &str,
        original_filename: Option<&str>,
        idempotency_key: &str,
    ) -> Result<CheckResult, HtpbeError> {
        let id = self.analyze(pdf_url, original_filename, idempotency_key).await?;
        self.result(&id).await
    }

    /// POST /analyze. Pass the same `idempotency_key` on every retry of
    /// one logical request, and a new key for every new document.
    pub async fn analyze(
        &self,
        pdf_url: &str,
        original_filename: Option<&str>,
        idempotency_key: &str,
    ) -> Result<String, HtpbeError> {
        let body = AnalyzeRequest { url: pdf_url, original_filename };
        let body = &body;

        self.with_retry(|| async move {
            let resp = self
                .http
                .post(format!("{}/analyze", self.base_url))
                .bearer_auth(&self.api_key)
                .header("Idempotency-Key", idempotency_key)
                .json(body)
                .send()
                .await?;
            let resp = check_status(resp).await?;
            let bytes = resp.bytes().await?;
            let parsed: AnalyzeResponse = serde_json::from_slice(&bytes)?;
            Ok(parsed.id)
        })
        .await
    }

    /// GET /result/{id}. A plain read, so retrying it is always safe.
    pub async fn result(&self, id: &str) -> Result<CheckResult, HtpbeError> {
        self.with_retry(|| async move {
            let resp = self
                .http
                .get(format!("{}/result/{}", self.base_url, id))
                .bearer_auth(&self.api_key)
                .send()
                .await?;
            let resp = check_status(resp).await?;
            let bytes = resp.bytes().await?;
            Ok(serde_json::from_slice(&bytes)?)
        })
        .await
    }

    async fn with_retry<T, F, Fut>(&self, mut op: F) -> Result<T, HtpbeError>
    where
        F: FnMut() -> Fut,
        Fut: Future<Output = Result<T, HtpbeError>>,
    {
        let mut retries: u32 = 0;
        let mut waited_in_progress = Duration::ZERO;
        loop {
            match op().await {
                Ok(value) => return Ok(value),
                // The original request is still running: wait on it without
                // spending a normal attempt, up to MAX_IN_PROGRESS_WAIT.
                Err(err) if err.is_in_progress() && waited_in_progress < MAX_IN_PROGRESS_WAIT => {
                    let delay = err
                        .retry_after()
                        .unwrap_or(Duration::from_secs(2))
                        .min(MAX_IN_PROGRESS_WAIT - waited_in_progress);
                    waited_in_progress += delay;
                    tokio::time::sleep(delay).await;
                }
                // 409 is excluded here, so the in-progress budget is a hard stop.
                Err(err) if !err.is_in_progress() && err.is_retryable() && retries + 1 < self.max_attempts => {
                    retries += 1;
                    let delay = err.retry_after().unwrap_or_else(|| backoff(retries));
                    tokio::time::sleep(delay).await;
                }
                Err(err) => return Err(err),
            }
        }
    }
}

/// Turns a non-2xx response into HtpbeError::Api. The body is parsed on a
/// best-effort basis: a proxy in front of the API can answer with HTML.
async fn check_status(resp: Response) -> Result<Response, HtpbeError> {
    let status = resp.status();
    if status.is_success() {
        return Ok(resp);
    }

    let retry_after = resp
        .headers()
        .get(RETRY_AFTER)
        .and_then(|v| v.to_str().ok())
        .and_then(|s| s.trim().parse::<u64>().ok())
        .map(|secs| Duration::from_secs(secs.clamp(1, MAX_RETRY_AFTER_SECS)));

    let bytes = resp.bytes().await.unwrap_or_default();
    let (code, message, details) = match serde_json::from_slice::<ErrorBody>(&bytes) {
        Ok(body) => (body.code, body.error, body.details),
        Err(_) => (
            "unknown".to_owned(),
            status.canonical_reason().unwrap_or("unexpected status").to_owned(),
            None,
        ),
    };

    Err(HtpbeError::Api {
        status: status.as_u16(),
        code,
        message,
        details,
        retry_after,
    })
}

/// 1 s, 2 s, 4 s ... capped at 30 s, plus up to one second of jitter.
/// The jitter comes from the clock's sub-second nanos: enough to keep a
/// batch of workers from retrying in lockstep, without an RNG crate.
fn backoff(attempt: u32) -> Duration {
    let base = Duration::from_secs(1u64 << attempt.saturating_sub(1).min(5))
        .min(Duration::from_secs(30));
    let nanos = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.subsec_nanos())
        .unwrap_or(0);
    base + Duration::from_millis(u64::from(nanos % 1_000))
}

Retry-After is read as integer seconds and clamped to 1–60. The API sends it on 429 server_at_capacity and on 409 idempotency_key_in_progress; otherwise the loop uses exponential backoff.

409 has its own budget. A 409 means the original is still running, so the loop keeps waiting on it for up to 90 seconds instead of spending its normal attempts.

Test keys never see 429: capacity limits apply to live keys only. Keep the retry path anyway, so the code behaves the same once a live key goes in.

Four attempts is a starting point. Exhausting them doesn’t mean the document failed; it means you don’t know yet, and the handler in the next step treats it that way.

Step 5: Routing the verdict (axum handler)

The API ships its own recommendation in every result: usage_caution.recommended_action is route_to_human_review for modified, request_from_issuer for inconclusive and no_action for intact. The router follows it, with one special case and one fail-safe rule.

The special case is status_reason: analysis_incomplete, which describes the check rather than the document, so the router asks for a resubmission. A resubmission is a new logical request, so it gets a new Idempotency-Key.

The fail-safe rule: anything the router doesn’t recognise, or any combination that doesn’t add up, goes to a human. Proceed requires both status: intact and recommended_action: no_action.

// src/htpbe/routing.rs
use super::types::{CheckResult, Confidence, RecommendedAction, Status, StatusReason};

/// Where a checked document goes next.
///
/// IMPORTANT: no variant here declines an application, flags a person or
/// takes any adverse action. The API marks every verdict
/// `safe_for_automated_adverse_decision: false`. A structural verdict is a
/// statement about the FILE, never about the person who sent it.
#[derive(Debug)]
pub enum Route {
    /// intact + no_action: no structural modification was detected.
    /// Not a statement that the document is authentic or its contents true.
    Proceed,
    /// modified + route_to_human_review, and every unknown or inconsistent case.
    HumanReview {
        markers: Vec<String>,
        confidence: Option<Confidence>,
    },
    /// inconclusive + request_from_issuer: the limit of what the file's
    /// structure can show. Not a suspicion of fraud.
    RequestFromIssuer { reason: Option<StatusReason> },
    /// status_reason analysis_incomplete: run the check again with a NEW
    /// Idempotency-Key. If it repeats, the caller downgrades to RequestFromIssuer.
    Resubmit,
}

pub fn route_check(r: &CheckResult) -> Route {
    // The incomplete case first: it describes the check, not the document.
    // (An incomplete analysis that still found a modification comes back as
    // `modified` with no status_reason, and the match below routes it.)
    if r.status_reason == Some(StatusReason::AnalysisIncomplete) {
        return Route::Resubmit;
    }

    match (r.usage_caution.recommended_action, r.status) {
        (RecommendedAction::NoAction, Status::Intact) => Route::Proceed,
        (RecommendedAction::RequestFromIssuer, Status::Inconclusive) => Route::RequestFromIssuer {
            reason: r.status_reason,
        },
        // route_to_human_review, plus anything unknown or inconsistent.
        // Fail safe: an unrecognised answer goes to a person, never to Proceed.
        _ => Route::HumanReview {
            markers: r.modification_markers.clone(),
            confidence: r.modification_confidence,
        },
    }
}

The handler receives a case from your own system, with everything it needs stored on the case: a reachable document URL (Step 6), the idempotency key minted when the case was recorded, and the resubmission key if one was ever needed.

The error branch matters as much as the routing. If the API can’t be reached or returns an error, the document has not been checked. The case stays ‘check pending’. It doesn’t proceed, and it doesn’t count against anyone. Because its keys are stored with it, a retry within the URL’s lifetime replays the same logical request; after a failed attempt whose URL has expired, restage first (Step 6).

// src/main.rs
mod htpbe;

use axum::{extract::State, http::StatusCode, routing::post, Json, Router};
use serde::{Deserialize, Serialize};

use htpbe::client::HtpbeClient;
use htpbe::error::HtpbeError;
use htpbe::routing::{route_check, Route};
use htpbe::types::{Confidence, StatusReason};
use uuid::Uuid;

#[derive(Clone)]
struct AppState {
    htpbe: HtpbeClient,
}

#[derive(Deserialize)]
struct SubmitDocument {
    document_url: String,
    original_filename: Option<String>,
    case_id: String,
    /// Minted (UUID v4) when the case was recorded and stored with it, next to
    /// the exact document_url. A pending case is retried with the SAME pair.
    check_key: String,
    /// Set once a first run came back analysis_incomplete. Stored on the case.
    resubmit_key: Option<String>,
}

#[derive(Serialize)]
#[serde(tag = "route", rename_all = "snake_case")]
enum CaseOutcome {
    Proceed { check_id: String },
    HumanReview {
        check_id: String,
        markers: Vec<String>,
        confidence: Option<Confidence>,
    },
    RequestFromIssuer { check_id: String, reason: Option<StatusReason> },
    /// The file itself could not be analysed (too large, unreadable,
    /// password-protected). Ask the submitter for a readable copy.
    FileNotCheckable { error_code: String },
    /// The check did not happen. Not a pass, not a fail: the case waits.
    CheckPending,
}

/// Stand-in for your case store: write the resubmission key to the case
/// record. Replace with a real database write.
async fn save_resubmit_key(case_id: &str, key: &str) -> std::io::Result<()> {
    // Demo only: never log real idempotency keys.
    let _ = (case_id, key);
    Ok(())
}

/// Runs the check and, for analysis_incomplete, exactly one fresh run.
async fn run_check(client: &HtpbeClient, req: &SubmitDocument) -> Result<(String, Route), HtpbeError> {
    let url = req.document_url.as_str();
    let name = req.original_filename.as_deref();

    let resubmit_key = match &req.resubmit_key {
        // A stored resubmit key means the first run already came back
        // incomplete: replay the resubmission, don't repeat the first check.
        Some(key) => key.clone(),
        None => {
            let first = client.check_pdf(url, name, &req.check_key).await?;
            match route_check(&first) {
                Route::Resubmit => {
                    // A resubmission is a new logical request, so it gets a NEW
                    // Idempotency-Key, persisted on the case BEFORE it is sent.
                    // If the write fails, nothing is sent and the case stays pending.
                    let key = Uuid::new_v4().to_string();
                    save_resubmit_key(&req.case_id, &key)
                        .await
                        .map_err(|_| HtpbeError::Config("could not persist the resubmit key"))?;
                    key
                }
                other => return Ok((first.id, other)),
            }
        }
    };

    let second = client.check_pdf(url, name, &resubmit_key).await?;
    let route = match route_check(&second) {
        // Incomplete twice: unexamined, so never clean.
        Route::Resubmit => Route::RequestFromIssuer {
            reason: Some(StatusReason::AnalysisIncomplete),
        },
        other => other,
    };
    Ok((second.id, route))
}

async fn submit_document(
    State(state): State<AppState>,
    Json(req): Json<SubmitDocument>,
) -> (StatusCode, Json<CaseOutcome>) {
    let checked = run_check(&state.htpbe, &req).await;

    let (status, outcome) = match checked {
        Ok((check_id, Route::Proceed)) => (StatusCode::OK, CaseOutcome::Proceed { check_id }),
        Ok((check_id, Route::HumanReview { markers, confidence })) => (
            StatusCode::OK,
            CaseOutcome::HumanReview { check_id, markers, confidence },
        ),
        Ok((check_id, Route::RequestFromIssuer { reason })) => {
            (StatusCode::OK, CaseOutcome::RequestFromIssuer { check_id, reason })
        }
        // run_check never returns Resubmit; if it ever did, the file is unexamined.
        Ok((_, Route::Resubmit)) => (StatusCode::ACCEPTED, CaseOutcome::CheckPending),

        Err(err) => match err.code() {
            Some(code @ ("file_too_large" | "invalid_pdf")) => (
                StatusCode::UNPROCESSABLE_ENTITY,
                CaseOutcome::FileNotCheckable { error_code: code.to_owned() },
            ),
            _ => {
                // Transport failure, retries exhausted, 401/402/403, 503, or a caller
                // bug such as idempotency_key_fingerprint_mismatch. The document
                // was not checked: never Proceed, never adverse.
                if err.is_out_of_credits() {
                    eprintln!("htpbe: no credits left, alert billing");
                } else {
                    eprintln!("htpbe check failed: {err}");
                }
                (StatusCode::ACCEPTED, CaseOutcome::CheckPending)
            }
        },
    };

    (status, Json(outcome))
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("HTPBE_API_KEY")?;
    let state = AppState { htpbe: HtpbeClient::new(api_key)? };

    let app = Router::new()
        .route("/documents", post(submit_document))
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await?;
    axum::serve(listener, app).await?;
    Ok(())
}

This is axum 0.8: a tokio::net::TcpListener handed to axum::serve, with Json last because it consumes the body. Cloning HtpbeClient only clones a handle to the same pool. When run inline, the worst case (retries, a wait on a 409, one resubmission) can hold a request for several minutes, which is why a queue suits higher volume; see batch PDF checks with a queue.

What each route means for the people reviewing cases

Proceed means the file showed no structural sign of being edited after it was created. Your other checks still apply, and it says nothing about whether the figures in the document are true.
Human review means the file’s structure shows evidence of post-creation editing, and the markers say what kind. The reviewer decides what that means for this case, typically by asking for the original or contacting the issuer. Results the router doesn’t recognise also land here, often with an empty marker list, so check the list before drawing any conclusion.
Request from issuer means the file came from a source where the structure can’t confirm integrity either way, such as an office suite, an online editor or a scan. That is a limit of the evidence, not a suspicion of the applicant. It also covers a file whose analysis came back incomplete twice; in that case the file was not fully examined, which says nothing about its source.
Check pending means the check did not run, and the case waits until it does.

For the full reasoning behind each verdict and each status_reason, see handling verdicts in code and what ‘inconclusive’ means.

Step 6: Giving the API a reachable URL

The API downloads the PDF from the URL you send, so the file must be reachable without authentication and no larger than 10 MB. For a private bucket, use a short-lived presigned GET URL, and pass original_filename so the stored result shows a readable name.

// src/upload.rs
use std::time::Duration;

use aws_sdk_s3::presigning::PresigningConfig;
use aws_sdk_s3::primitives::ByteStream;
use aws_sdk_s3::Client as S3Client;
use uuid::Uuid;

type BoxError = Box<dyn std::error::Error + Send + Sync>;

/// Covers one in-process check plus its retries, NOT the pending-case
/// window: a case retried after the URL expired is restaged instead.
const PRESIGN_TTL: Duration = Duration::from_secs(30 * 60);

/// Persist all three fields with the case. Every check of this case runs
/// from the stored URL and key while the URL is valid.
pub struct StagedCheck {
    pub object_key: String,
    pub document_url: String,
    pub check_key: String,
}

/// Uploads once, signs once, mints the Idempotency-Key once.
pub async fn stage_upload(s3: &S3Client, bucket: &str, pdf: Vec<u8>) -> Result<StagedCheck, BoxError> {
    let object_key = format!("incoming/{}.pdf", Uuid::new_v4());
    s3.put_object()
        .bucket(bucket)
        .key(&object_key)
        .content_type("application/pdf")
        .body(ByteStream::from(pdf))
        .send()
        .await?;
    sign(s3, bucket, object_key).await
}

/// Only for a check whose original attempt FAILED and whose URL has since
/// expired: a new URL is a new logical request, so it gets a new key too.
pub async fn restage(s3: &S3Client, bucket: &str, object_key: String) -> Result<StagedCheck, BoxError> {
    sign(s3, bucket, object_key).await
}

async fn sign(s3: &S3Client, bucket: &str, object_key: String) -> Result<StagedCheck, BoxError> {
    let presigned = s3
        .get_object()
        .bucket(bucket)
        .key(&object_key)
        .presigned(PresigningConfig::expires_in(PRESIGN_TTL)?)
        .await?;
    Ok(StagedCheck {
        object_key,
        document_url: presigned.uri().to_owned(),
        check_key: Uuid::new_v4().to_string(),
    })
}

The check itself runs from the stored pair: htpbe.check_pdf(&staged.document_url, Some(name), &staged.check_key). The Idempotency-Key is tied to the full URL, query string included, so a re-signed URL under the same key gets 422 idempotency_key_fingerprint_mismatch. That’s why the pair is signed once and stored, never rebuilt on retry.

Replaying a request that completed with a verdict returns the original check before the file is downloaded, so an expired URL doesn’t break a replay. If the original attempt failed and the URL has since expired, the retry comes back 400 download_failed: call restage for a new URL and a new key, store the new pair (and clear any stored resubmit key), and check again. That’s safe because a failed attempt is not charged.

The expiry is short on purpose. A presigned URL is a bearer link: anyone holding it can fetch the document until it expires, and a short expiry costs nothing more than a restage when a failed case is retried later. A URL signed with temporary credentials also stops working when those credentials expire.

Build the S3 client once at startup with aws_config::load_defaults(BehaviorVersion::latest()).await and aws_sdk_s3::Client::new(&config). The same code works against Cloudflare R2 or any other S3-compatible store once you set the endpoint URL on the SDK config.

One security note: if a URL ever comes from untrusted input, validate it first and reject localhost, link-local addresses such as 169.254.169.254 (cloud metadata) and the RFC 1918 private ranges. Better still, download the file yourself and send the API your own presigned link.

Batch processing, test mode and credits

Synchronous by design. There’s nothing to poll and no webhook to register. For a backlog, run checks with a modest concurrency bound (a tokio::sync::Semaphore or a small worker pool) and one shared HtpbeClient. In a job queue, mint the key when the job is created and store it with the job:

#[derive(Clone)]
pub struct CheckJob {
    pub pdf_url: String,
    /// Minted at enqueue time and persisted, so a worker that picks the
    /// job up again replays the same logical request.
    pub idempotency_key: String,
}

Workers then call client.check_pdf(&job.pdf_url, None, &job.idempotency_key). The retry loop already handles 429, but a small concurrency bound means you rarely reach it. For queue-based designs, see the event-driven integration guide.

Past checks. GET /checks returns a paginated list of your checks, filterable by status, from_date, to_date, creator, producer and tool, paged with limit (1 to 500) and offset. With reqwest’s query feature off, build the string yourself, for example format!("{base}/checks?status=modified&limit=100&offset=0"), with the same bearer header.

Test mode. Test keys accept only the fixed URLs under https://api.htpbe.tech/v1/test/ (anything else returns 403 test_url_required), return deterministic results and cost nothing. Five of them exercise three of the four branches of route_check: clean.pdf, signature-removed.pdf, dates-mismatch.pdf, inconclusive.pdf and scanned-document.pdf. No test URL produces analysis_incomplete, so cover Resubmit with a mock server via with_base_url. Test keys also ignore Idempotency-Key, so 409, replays and idempotency_key_fingerprint_mismatch only appear with a live key. trigger-402.pdf exercises the out-of-credits path. Test results never appear in GET /checks. The full list is in the testing reference.

Credits. API calls and web uploads share one credit pool. With no credit source left, /analyze returns 402 payment_required until credits are added, so route it to billing rather than retrying. Plans, credit packs and welcome-credit terms are on pricing.

What this does not catch

Structural analysis has limits, and a service making automated routing decisions should encode them rather than discover them.

Content that was false from the start. The check finds evidence that a file was changed after it was created. A document whose figures were wrong when it was first produced carries no such evidence, because nothing was changed afterwards. This is also why a file produced by consumer software comes back inconclusive with consumer_software_origin rather than intact: the structure can’t vouch for a file anyone could have produced from scratch.
Skilled, deliberate fabrication. A well-resourced forger can sometimes produce a file that shows no structural sign of editing. It’s rare and takes effort, but intact means no modification was detected, not that the document is genuine. Confirmation with the issuer remains the stronger check.
Encrypted or password-protected PDFs. The file has to be readable to be analysed; these come back as 422 invalid_pdf.
The content layer. The check doesn’t read the document’s text or figures, so it can’t tell you whether an amount, a name or a date printed on the page is correct.

That’s why structural tamper detection is one layer, not the whole stack. Pair the verdict with domain checks: confirmation with the issuer, account or employer lookups, and your KYC or OCR provider where those apply. More in PDF fraud prevention best practices.

Decisions before you ship

The API surface is deliberately small: one POST, one GET, three verdicts and an error contract. The decisions that matter are on your side.

What reviewers see. Give reviewers the markers rendered as labels from /how, the status_reason for inconclusive results and the usage_caution.message, so the reasoning travels with the case.
Policy per document type. The router above follows the API’s recommendation. If your workflow needs a different path for a given document type, add it as a policy layer on top, and keep the rule that no structural verdict alone triggers an adverse action against a person.

To start, get a key from the API page, run the Step 1 curl with your test key at no cost, then point the client at a real file with a live key. New accounts get 5 welcome credits on signup, then pay-per-check credits or a subscription; see pricing for the terms.

Grant and Relief-Fund Fraud: Altered Financial PDFs

Iurii Rogulia — Sat, 31 Oct 2026 11:00:47 +0000

A grant, subsidy or relief program asks applicants for much the same paperwork a lender does: bank statements, payroll records, tax returns, a profit and loss statement – and later, invoices showing what the money paid for. The difference is who reads it. A lender has an underwriting team paid to read that paperwork with suspicion. A funding program usually has a program officer, an eligibility checklist and a disbursement deadline.

Grant and relief-fund document fraud rarely looks dramatic. It is a real bank statement with a changed balance, a payroll register with an extra name, an invoice with a higher total. The page reads correctly because a real document was edited, not invented from nothing. Reviewers read what a document says; programs rarely check whether the file was changed after the issuing system produced it. A structural PDF check answers that one question – was this file edited after it was created? It does not tell you whether the applicant qualifies, whether the figures are true, or who sent the file.

When money moves fast on self-certified paperwork, the gap gets expensive. Paycheck Protection Program (PPP) fraud is a well-documented example, and the official record on it is summarised below.

Three checkpoints where applicant PDFs decide the money

A funder holds applicant-submitted PDFs at three distinct moments, and each one releases or commits money.

Eligibility intake. The applicant proves they exist as a going concern and meet the program’s thresholds: revenue, headcount, losses, location. Bank statements, tax returns and payroll summaries carry this step.
Pre-disbursement. Before the first payment, programs often ask for updated statements, a bank account letter for the payee details, or a signed budget. A changed account number here redirects the award itself.
Reimbursement and post-award review. After the award, grantees claim against their budget with invoices, receipts and payroll records for staff the grant funds. This is where most of the documents arrive, spread over months or years.

In most programs, document scrutiny is concentrated at the first checkpoint. Most of the documents arrive at the third.

The documents that carry the decision

Grant money is decided by the same handful of document types that decide loans. Each has its own altered-PDF pattern, described here by outcome rather than method:

Bank statements – a statement with a changed closing balance or a removed overdraft, used to show need or capacity. See bank statement tamper detection.
Payroll records and pay stubs – a payroll summary or pay stub showing staff or wages the business does not have, used for headcount-based awards and payroll reimbursement. See pay stub tamper detection.
Tax returns – a return with a revised gross receipts line, used to prove revenue loss against a prior year. See tax document tamper detection.
Financial statements and profit and loss reports – a P&L with a deeper loss than the books show.
Reimbursement invoices and receipts – an invoice with a higher total or a receipt re-dated into the grant period. See invoice tamper detection and expense reimbursement checks.

All of these share one property that matters for a funder: a well-made edit looks like the original on screen, so a careful reader often has nothing to catch.

What PPP and relief-fund history showed

The SBA Office of Inspector General’s June 2023 fraud landscape report (Report 23-09) is a detailed primary record. It describes how emergency measures allowed the SBA to ‘reduce or eliminate key internal controls and rely on self-certification of eligibility to expedite aid’, and estimates that the SBA disbursed more than $200 billion in potentially fraudulent COVID-19 Economic Injury Disaster Loans (EIDLs) and PPP loans – at least 17% of disbursed funds, split as more than $136 billion in EIDLs and $64 billion in PPP funds. The SBA disputed that estimate in its response, published in the same report, and put the body of loans likely to be fraudulent at approximately $36 billion. Either figure is large; the gap between them is a reminder that ‘potentially fraudulent’ is not ‘proven’.

Two details in the report matter for grant administrators. The first is that EIDL advances ‘were essentially grants that did not need to be repaid’, and applicants self-certified their headcount, a number ‘not vetted by SBA’. The second is that documents kept deciding money after disbursement: in one case the report describes, ‘the fraudulent payroll records were then submitted to SBA to obtain 100 percent loan forgiveness.’

Two limits apply. The report does not break losses down by how the documents were produced, and many of the schemes it describes ran on stolen identities, fabricated employer numbers and businesses with no operations – problems a file check does not touch. And where a scheme accepts a self-declaration instead of a document, there is no file to inspect at all. In a separate example, the UK’s Bounce Back Loan Scheme had ‘limited verification, and no credit checks on borrowers’, according to the National Audit Office’s December 2021 update; the department’s March 2021 estimate that 11% of loans, worth £4.9 billion, were fraudulent was described as ‘highly uncertain’; a later October 2021 revision put it at 7.5% of loans, a figure the NAO said it could not assure.

For how lenders handled PPP loan application fraud and what changed in their document review afterwards, see our post on SBA loan stip-document fraud. For the wider public-sector picture, see government document fraud and PDF checks.

Why application-time review misses post-award claims

Intake review gets the experienced staff: a few documents per applicant, read once, against clear criteria. Post-award claims arrive monthly or quarterly for the life of the grant, many small documents per grantee. Reviewers check them against budget lines – is this cost allowed, does it fall in the period, does the arithmetic match the claim – which is a question about the content, not the file. Audits are usually sampled. And a grantee who applied honestly can, under cash pressure two years later, edit one receipt total.

So reimbursement documents are where editing is cheapest and review thinnest: one changed figure on one invoice, among hundreds in the queue.

What a modification check tells a program officer

HTPBE runs a structural PDF tamper detection check on each file and returns one of three verdicts:

intact – no structural modification detected.
modified – the file carries structural evidence that it was changed after it was created.
inconclusive – the check cannot give a full answer for this file, so it says so instead of guessing. Treat it as unanswered rather than cleared, and confirm the document with its source wherever the decision depends on it.

A modified result names what was found with public marker IDs such as HTPBE_MULTIPLE_REVISION_LAYERS (the document was saved again with changes after creation), HTPBE_EDITING_TOOL_FINGERPRINT (a known PDF editor left its traces) or HTPBE_DATES_DISAGREE (the modification date differs from the declared creation date). Each check also gets an ID you can store with the application as a record of the check.

A trimmed example of a result:

{
  "id": "506a6b1b-1360-48a2-b389-abb346f85d04",
  "filename": "reimbursement-invoice-q3.pdf",
  "status": "modified",
  "modification_markers": ["HTPBE_MULTIPLE_REVISION_LAYERS", "HTPBE_EDITING_TOOL_FINGERPRINT"],
  "usage_caution": {
    "safe_for_automated_adverse_decision": false,
    "recommended_action": "route_to_human_review"
  }
}

The usage_caution field is always present, and safe_for_automated_adverse_decision is always false. That reflects how the verdict should be used: intake, then the check, then flagged files routed to a person who decides what the edit means and whether to confirm the document with its source. Source confirmation – the bank, a tax transcript, the payroll provider – stays the reference. The check helps sequence it: files returned as modified go to the front of the confirmation queue. For an intact file the API returns no_action: the file check raised no flag. That is not the same as saying source confirmation is unnecessary – an intact file simply sits lower in the queue.

What the check cannot tell you

Not identity. It does not establish who submitted the file or whether the business exists. That is a KYC and registry question.
Not eligibility. It does not decide whether an applicant qualifies under program rules.
Not whether the numbers are true. HTPBE does not read balances, totals or headcounts, and does not check arithmetic. It examines the file’s structure, not its content – which is exactly why an edit that leaves the page looking perfect can still show up.
Not issuer confirmation. intact means no structural modification detected. It does not mean the document is authentic or that the bank issued it.
Not fabrication from scratch. A document built with false content from the start, rather than edited, has no later edit for a modification check to find. Whatever verdict such a file gets – intact included – it says nothing about whether the content is true; source confirmation covers that case.
Not scans. A scanned or print-to-PDF document cannot return intact; confirm it with the issuer instead.

Wiring it into intake

Platform teams that own the upload step can call the HTPBE API with one POST per file. The file URL must be downloadable without authentication, so applicant documents in private storage need a short-lived signed link:

curl -X POST https://api.htpbe.tech/v1/analyze \
  -H "Authorization: Bearer $HTPBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://storage.example.org/signed/applicant-123/bank-statement.pdf"}'

# returns {"id": "..."}; fetch the verdict and marker IDs with:
curl https://api.htpbe.tech/v1/result/YOUR_CHECK_ID \
  -H "Authorization: Bearer $HTPBE_API_KEY"

Store the check ID with the application record. Send modified files to your existing review queue rather than to an automatic decision; for inconclusive files, which the check cannot answer, confirm with the source wherever the decision depends on them.

Frequently asked questions

Can a PDF check tell whether an applicant qualifies for a grant?

No. A structural check answers whether the file was edited after it was created. Eligibility depends on the program’s rules and on facts the file may or may not state truthfully – that stays with the program officer and with source confirmation.

How is this different from a lender’s stip review?

The check is the same; the timing differs. A lender concentrates its review before funding, while a grant program keeps receiving documents after the award, through reimbursement claims and close-out reports – so the check belongs on post-award documents too, not just at intake.

What happens with scanned documents?

Scanned and print-to-PDF documents cannot return intact, whatever happened to the original. If a program needs to rely on a scanned document, confirm it with the issuer.

Does a modified result mean the applicant committed fraud?

No. It records the fact of an edit, not the intent behind it. Redacting an account number, merging pages or re-exporting a file are edits too. A modified result is a reason to route the file to a person, never grounds on its own to deny an application.

Try it on your own applicant files

The fastest way to see what the check returns on your documents is to sign up and run a few through the web app – new accounts get five welcome credits. After that, as of October 2026, checks cost $5 for 8 or $15 for 25 as one-time credit packs, or plans start at $15 a month for 30 checks; see pricing for current tiers. Whatever the result, treat it as one input to review: none of the three verdicts on its own should be the sole basis for denying an applicant.

PHP2Shell: Two Critical PHP RCE Flaws and What to Do in the First Hour

Iurii Rogulia — Fri, 30 Oct 2026 11:01:17 +0000

On October 21, 2026, the PHP project released 8.5.12, 8.4.27, 8.3.36 and 8.2.35 to fix two critical remote code execution flaws, CVE-2026-109618 and CVE-2026-109619. Amazon Threat Intelligence calls the pair PHP2Shell. Both are rated CVSS v4.0 9.2, and no login is required to reach them.

If anything you run serves web requests through PHP, the first job is to find out which version is actually answering those requests. This article covers what the flaws are, who is exposed, and the order I would work in.

What the Two Flaws Are

Both are memory-safety bugs in PHP itself. Neither is in a framework, a plugin or your application code. The details below come from the PHP project’s advisories, GHSA-w8hw-w9fx-j79w and GHSA-6wmf-4rv5-p3rp.

CVE-2026-109618, RCE via OOM corruption. When PHP runs out of memory it exits the current context with longjmp(). In some places request data is reachable before it is fully initialised, so the early exit leaves invalid memory behind and request shutdown then acts on it. Multipart parsing can push PHP into that state while staying within the configured limits.
CVE-2026-109619, RCE via stale global state. A persistent worker can keep global state that points at memory owned by a previous request. After that memory is freed, a later request on the same worker may use the stale value before PHP has initialised the request. The confirmed paths are the PHP 8.5 fatal_error_backtraces setting and session upload progress.

The advisories give the affected ranges as everything below the fixed versions on 8.2, 8.3, 8.4 and 8.5.

Who Is Exposed

The PHP project says all installations serving web requests are at risk: PHP-FPM, Apache with mod_php, php-cgi, FrankenPHP and LiteSpeed. The risk is highest for mod_php, where an exploit was demonstrated that fires before any application code runs.

For PHP-FPM, the OOM flaw is considered susceptible from source analysis, but the advisory says no complete exploit has been demonstrated. The stale-state flaw was validated against FPM through session upload progress, which is enabled by default.

PHP 8.1 and older no longer get updates from the PHP project. It published minimal source backports on separate branches for 7.4, 8.0 and 8.1, and some distributions and long-term-support vendors ship their own fixes. PHP 8.2 reaches end of life on December 31, 2026, according to the PHP project.

Some distributions backport the fix into an old upstream version instead of upgrading. Ubuntu 22.04 ships PHP 8.1.2 and is fixed at 8.1.2-1ubuntu2.28, so comparing against the list above tells you nothing there. Debian moved to the upstream fixed versions instead (8.2.35 on bookworm, 8.4.27 on trixie). Check your distribution’s security tracker for the package version: Debian, Ubuntu.

Is It Being Exploited

Amazon Threat Intelligence reports an exploitation attempt on its MadPot honeypot network on October 17, four days before disclosure. On October 21, between about 02:00 and 08:00 UTC, it saw more attempts from other infrastructure with varying payloads, which it reads as multiple actors. Once the patch shipped, new proof-of-concept exploits hit its sensors within hours, and Amazon says PHP2Shell is now seeing broad exploitation attempts in the wild. Amazon also says it is unclear whether any of these attempts would have worked against real systems.

So the safe assumption is that scanning is already under way, and that the question is whether your version is fixed, not whether anyone is looking.

The First Hour

Find the PHP that serves requests, not the one in your shell. php -v reports the command-line binary. Your web server can use a different build, a different container or a different FPM pool. Check the version of the running web runtime, the container image tag, and your deploy and CI configuration.
Update. Move to 8.5.12, 8.4.27, 8.3.36 or 8.2.35, or to your distribution’s patched package. The PHP project says updating is the only complete fix for both flaws. On containers, rebuild the image from a patched base and recreate the containers, since restarting the old one changes nothing.
If you cannot update yet, apply the interim measures and treat them as partial.
- For the OOM flaw: set memory_limit=-1 so it cannot be overridden (php_admin_value in an FPM pool or Apache config; the price is that a single request has no memory ceiling, so you need an external limit such as a container or cgroup limit that kills only the affected worker), keep post_max_size at 8M (32M if you need uploads) with upload_max_filesize below it, and limit request size, field count, multipart parts and nesting at the proxy. Do not use RLIMIT_AS or RLIMIT_DATA, because they trigger the vulnerable path.
- For the stale-state flaw: set session.upload_progress.enabled=0 in php.ini, the FPM pool or the server config, then restart every worker. ini_set() and .user.ini do not work for this. On PHP 8.5, also set fatal_error_backtraces=0.
Look back, starting October 17. Amazon suggests searching web server logs for POST requests containing PHP_SESSION_UPLOAD_PROGRESS in form uploads, and checking servers for unexpected process execution or file changes. Start from October 17, not from the disclosure date.

Separately, the PHP project’s advisory page lists a related issue on session upload progress, CVE-2026-115560, dated October 23. It is not part of these two, and it needs a specific session.serialize_handler change at runtime. If you do not use upload progress, keeping it off removes that exposure too.

Letting an Agent Do the Inventory

The tedious part is the inventory: PHP on hosts, in container images, in CI, in deploy files, and telling the CLI version from the web one. I published a free Agent Skill that walks Claude Code, Codex or Cursor through this: PHP RCE Response. It finds the runtimes, classifies each by SAPI and the settings the advisories name, plans the update and checks the result. It is read-only by default: it diagnoses and recommends, and you decide what to change. Where the advisories do not state a fact, it marks it as unverified instead of guessing.

Sources:

Auto Insurance Claims Fraud: Altered Estimates and Reports

Iurii Rogulia — Fri, 30 Oct 2026 11:00:51 +0000

A motor claim rarely arrives as one document. It arrives as a stack of PDFs: the body shop’s estimate, a supplement two weeks later, a crash report the claimant downloaded, a tow and storage invoice, sometimes a total-loss valuation and a counter-offer. Most of them passed through someone else’s inbox before they reached yours, and for many of them the file is the only evidence you hold.

This article covers one narrow layer of automobile insurance fraud detection: what the structure of each of those PDFs can tell a claims team, and what it can’t.

The short answer

Ask one question of every PDF in the claim file: was this file changed after it was issued?

HTPBE answers that question by reading the file’s structure and history, not its content. The result is one of three verdicts – intact, modified or inconclusive – plus named markers for what was found. A marker might report, for example, that the file was saved again after it was created (HTPBE_MULTIPLE_REVISION_LAYERS) or that its modification date does not match its creation date (HTPBE_DATES_DISAGREE).

What it does not check:

whether the figures on the document are correct;
whether the police, the shop or the tow company actually issued it;
whether the accident happened the way the claim says;
photos of the damage.

Those are separate questions, and they need separate controls.

The motor-claim document set

Motor accounts for the majority of detected claims fraud by number, at least in the UK figures. The Association of British Insurers reported that UK insurers detected 51,700 fraudulent motor claims worth £576m in 2024 – 53% of all detected fraudulent general insurance claims by number. Across general insurance, detected fraud came to £1.16bn on 98,400 claims, and exaggerated loss was the most common type, at £466m. These are frauds insurers caught; the share they did not catch is unknown by definition.

Each document in a motor claim has a different author and a different route to the insurer. The route matters as much as the document type: a file that came straight from its issuer is a different object from one the claimant forwarded.

Document	Produced by	Usually reaches you via
Repair estimate and supplements	Body shop’s estimating system	Shop, claimant, broker or public adjuster
Police or crash report	Police agency, often sold through a records portal	Claimant, who downloads or scans a copy
Tow and storage invoice	Tow operator or storage yard	Claimant or shop, often by email
Total-loss valuation	Valuation provider; the claimant may send a rival one	Your own vendor, or the claimant in a dispute
Final repair invoice	Body shop	Shop or claimant at settlement

Every hand-off is a point where a PDF can be edited and saved again. Most of those edits are harmless; the job is to find the few that are not, without slowing down the rest.

Repair estimates and supplements: revisions are normal

Estimates change for legitimate reasons. A teardown finds hidden damage and the shop issues a supplement. A parts price changes and the estimate is re-issued. Three or four estimate documents on one claim is ordinary, and each one is normally its own file.

That is a different thing from one file being changed after it was produced, which is what a modified verdict reports – for example HTPBE_MULTIPLE_REVISION_LAYERS, meaning the file was saved again after it was created, or HTPBE_ONLINE_EDITOR_ORIGIN, meaning it carries the identity of an online editing or conversion service. A supplement does not explain a changed file, and a changed file is not proof of fraud either. The next step is to compare the whole document with the copy the shop sends you directly. If the two match, the edit did not change what the claim relies on. If they differ, the file goes to your special investigations unit (SIU).

The check matters most where the claimant, rather than the shop, is the courier. An estimate that arrives through your estimating platform or straight from the shop has fewer hands on it than one forwarded as an email attachment. The repair estimate tamper-detection page covers this document type in detail, and what adjusters miss in altered claim PDFs walks through how altered estimates, medical bills and receipts reach claims processing.

Police and crash reports: a copy, not the record

In some US states, people involved in a crash can buy and download the police report themselves. New York’s DMV, for example, lets you search, purchase and immediately download certified crash reports online. So the copy in your claim file has passed through the claimant’s hands.

File forensics can answer one question about that copy: did this PDF change after it was produced? It cannot tell you whether the content matches the agency’s record, whether an officer wrote it, or whether the narrative is accurate. If the report decides liability or the size of the payout, order the copy yourself from the same agency or portal, where you are entitled to request it, and compare.

Many crash reports also arrive as phone scans or photographed pages, and those often come back inconclusive: a scanned copy can never be confirmed intact, though some still show signs of editing and come back modified. An inconclusive result is not a sign of fraud or a reason to treat the claimant with suspicion; the answer has to come from the source.

The timeline across the claim file

Most PDFs carry their own creation and modification dates, and a motor claim has a fixed reference point: the date of loss. Lined up together, the dates of the estimate, the supplements, the tow invoice and the crash report should make sense against that date and against each other. A file last modified long after it should have been final is a question for the handler. Some dates move for ordinary reasons: a crash report bought from a portal may be generated at download time, so its creation date can fall well after the date of loss, and legitimate archiving and handling move dates too. Treat a timeline gap as a reason to look closer, not as a finding. For how a claims platform compares these dates automatically and routes each verdict to the right queue, see the claims-routing integration article.

What this does not catch

Content that was false from the start. A document whose figures were wrong when it was first produced carries no evidence of a later edit, because nothing was changed afterwards. And a well-resourced, deliberate forger can sometimes produce a file that shows no structural sign of editing. It’s rare, but intact means no modification was detected, not that the document is genuine.
Wrong figures in an issued document. HTPBE does not read totals, labour rates, parts prices or line items. An estimate inflated inside the shop’s own system before the PDF was issued has no later edit to detect.
Staged accidents and claim-level fraud. Staged collisions, phantom passengers and pre-existing damage are claim facts, not file facts. Claim scoring and investigation cover them.
Photos and video. HTPBE checks PDF files. It does not assess photographs of the vehicle or the scene.
Issuer and police records. HTPBE does not contact the shop, the tow company or the police, and it does not confirm that a document exists in their records.
Intent. modified means the file was changed. It does not say who changed it or why. That is for the handler or SIU to establish.

Where it fits in motor claims intake

Run the check once per PDF, when the document is attached to the claim, before anyone relies on it. Then route by verdict:

intact – normal handling. The file shows no evidence of a post-creation edit; everything else about the claim still gets its usual review.
inconclusive – not a fraud signal and no reason to treat the claimant with suspicion. If the document affects liability or the payout, get it from its source before relying on it.
modified – hold for review, with the markers attached. Compare the file with the issuer’s copy first; if they differ, send it to SIU. Declining the claim is not the next step.

A modified verdict is not a finding of fraud and should not on its own be the reason to decline or reduce a claim. Give the claimant or the issuer a chance to explain the change or supply the original.

Most documents go through untouched. For motor insurance fraud detection teams, the change is that the few edited files reach SIU with a reason attached, before payment rather than after. The insurance claims fraud detection overview covers the other claim document types, and how insurance fraud detection methods fit together explains where this layer sits next to claim scoring.

To try it on your own claim files, create an account: it comes with 5 welcome credits, and checks after that are pay-per-check (see pricing).

Frequently asked questions

Can HTPBE tell whether a repair estimate is inflated?

No. HTPBE does not read the figures, line items or labour rates on an estimate, so it cannot say whether a total is too high. It answers a different question – whether the PDF was changed after it was issued. If an estimate comes back modified, compare the whole document with the copy the body shop sends you directly. If the two match, the edit did not change what the claim relies on; if they differ, the file goes to review.

Does an inconclusive result on a police report mean the report is fake?

No. Scanned and photographed copies can never be confirmed intact, so unless they show signs of editing they come back inconclusive. That is a common result for this kind of file, not a sign of fraud and not grounds for denying a claim. If the report matters to liability, order the copy from the agency or state portal yourself, where you are entitled to request it.

Does an intact verdict mean the motor claim is genuine?

No. Intact means the file shows no evidence of being changed after it was created. A document whose content was false from the start, an estimate inflated inside the shop’s own system, or a staged accident can all sit behind an intact PDF. The verdict covers the file, not the claim, the figures or the events it describes.

For claims platforms

The HTPBE API takes one POST to https://api.htpbe.tech/v1/analyze with a publicly accessible URL of the PDF and returns a check ID. A GET on https://api.htpbe.tech/v1/result/{id} returns the verdict and public marker IDs. Call it from the document-upload step of your claims system, store the check ID on the claim record, and route on the verdict. A test key returns synthetic scenarios for each verdict, so you can build and test the routing before any real claim document goes through it.

Verifying vatnode Webhook Signatures (HMAC-SHA256)

Iurii Rogulia — Fri, 30 Oct 2026 10:00:50 +0000

A webhook signature proves the request was sent by someone holding your webhook’s signing key – vatnode, unless that key has leaked – and that the body wasn’t altered in transit. Getting verification right is less about the HMAC itself – that part is five lines – and more about three things people get wrong: reading the wrong bytes, skipping the timestamp check, and returning the wrong status code when verification fails. This post covers all three, with a verifier you can drop in as-is.

What’s actually in the signature

Every webhook delivery carries an X-Vatnode-Signature header:

X-Vatnode-Signature: t=1760000000,v1=3f2a9c...64 hex chars

t — the unix timestamp (seconds) at the moment vatnode signed and sent this specific attempt. It changes on every retry; the body bytes don’t.
v1 — a lowercase hex HMAC-SHA256, 64 characters. Only one v1 value is ever sent; there’s no multi-secret or multi-version list to loop over.

The signed message is ${t}.${rawBody}, where rawBody is the exact compact JSON string vatnode wrote to the wire – JSON.stringify(payload), no pretty-printing. The HMAC key is the full signing secret returned once in the 201 response of POST /v1/webhooks, vat_wh_ prefix included, used as a plain UTF-8 string – not decoded from hex or base64. Keep it in your secret store or environment, never in code, and never log it or the raw X-Vatnode-Signature header; log rejections without either. The framework examples below refuse to start without it: a missing key would otherwise make the verifier reject every real delivery, with nothing in the logs to say why.

X-Vatnode-Event carries the event type as a convenience header, but it isn’t covered by the signature. Route on the verified body’s event field, not the header – the header is for logging and quick filtering, not for a decision that depends on the payload being authentic.

The verified body is a JSON envelope with id, version, event, data, and timestamp fields. id is stable across every retry of the same event, and identical across every webhook endpoint on your account that received it – dedupe on id, not on the HTTP request. Possible event values are VAT_BECAME_VALID, VAT_BECAME_INVALID, COMPANY_NAME_CHANGED, COMPANY_ADDRESS_CHANGED, VIES_UNAVAILABLE, and webhook.test.

If VAT_BECAME_INVALID lands for a customer you’ve already invoiced, that’s a signal to re-check before your next invoice – not something to resolve automatically from this event alone. See VAT validation and subscription renewals for that workflow.

Here’s the full verifier both the Express and Next.js examples below import. TypeScript:

import { createHmac, timingSafeEqual } from 'node:crypto'

const TOLERANCE_SECONDS = 300

export function verifyVatnodeSignature(
  rawBody: string | Buffer,
  header: string | undefined,
  signingKey: string,
  nowSeconds = Math.floor(Date.now() / 1000)
): boolean {
  if (!header || !signingKey) return false

  let t: number | undefined
  let v1: string | undefined
  for (const part of header.split(',')) {
    const i = part.indexOf('=')
    if (i === -1) continue
    const name = part.slice(0, i).trim()
    const value = part.slice(i + 1).trim()
    if (name === 't') t = Number(value)
    if (name === 'v1') v1 = value
  }
  if (!t || !Number.isInteger(t) || !v1 || !/^[0-9a-f]{64}$/.test(v1)) return false
  if (Math.abs(nowSeconds - t) > TOLERANCE_SECONDS) return false

  const expected = createHmac('sha256', signingKey).update(`${t}.`).update(rawBody).digest()
  const received = Buffer.from(v1, 'hex')
  return received.length === expected.length && timingSafeEqual(received, expected)
}

Python:

import hashlib
import hmac
import re
import time

TOLERANCE_SECONDS = 300


def verify_vatnode_signature(raw_body: bytes, header: str | None, signing_key: str, now: int | None = None) -> bool:
    if not header or not signing_key:
        return False
    parts = {}
    for part in header.split(","):
        name, sep, value = part.partition("=")
        if sep:
            parts[name.strip()] = value.strip()
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not re.fullmatch(r"[0-9]{1,12}", t) or not re.fullmatch(r"[0-9a-f]{64}", v1):
        return False
    now = int(time.time()) if now is None else now
    if abs(now - int(t)) > TOLERANCE_SECONDS:
        return False

    expected = hmac.new(signing_key.encode("utf-8"), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

Pass it the request body as bytes, exactly as received: request.get_data() in Flask, request.body in Django, await request.body() in FastAPI or Starlette.

Both use a constant-time comparison (timingSafeEqual, hmac.compare_digest) rather than === or == on the hex strings – a plain string comparison leaks timing information about how many leading bytes matched, which is exactly the kind of detail an HMAC is supposed to deny an attacker.

The raw-body trap

The most common way to get a correct-looking implementation that still fails in production is verifying against the wrong bytes. A signature is a function of exact bytes, not of the data those bytes represent. If something in your stack parses the body into an object before your handler gets it, and you reconstruct a string from that object to verify, you risk hashing different bytes than the ones vatnode actually signed – a different serializer can add spacing JSON.stringify doesn’t, format a number differently, or otherwise produce output that means the same thing but isn’t the same bytes. The HMAC won’t match, and you’ll see a steady trickle of false rejections that look like an intermittent bug but aren’t.

The fix: capture the raw body before any parsing happens, and hash that. In Express, that means registering the webhook route with express.raw() ahead of any global express.json() middleware:

import express from 'express'
import { verifyVatnodeSignature } from './verify'

const VATNODE_WEBHOOK_SECRET = process.env.VATNODE_WEBHOOK_SECRET ?? ''
if (!VATNODE_WEBHOOK_SECRET) throw new Error('VATNODE_WEBHOOK_SECRET is not set')

const app = express()

// Register the raw-body route before any app.use(express.json()).
app.post('/webhooks/vatnode', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body as Buffer
  const ok = verifyVatnodeSignature(rawBody, req.get('X-Vatnode-Signature'), VATNODE_WEBHOOK_SECRET)
  if (!ok) {
    res.status(400).send('invalid signature')
    return
  }

  const event = JSON.parse(rawBody.toString('utf8')) as {
    id: string
    event: string
    data: Record<string, unknown>
  }
  // record event.id and enqueue your work in one step (see dedupe below)
  res.sendStatus(200)
})

app.use(express.json())
app.listen(3000)

Next.js route handlers give you the raw body by default – request.text() returns the exact string that arrived, with no parsing step in between:

import { verifyVatnodeSignature } from './verify'

const VATNODE_WEBHOOK_SECRET = process.env.VATNODE_WEBHOOK_SECRET ?? ''
if (!VATNODE_WEBHOOK_SECRET) throw new Error('VATNODE_WEBHOOK_SECRET is not set')

export async function POST(request: Request): Promise<Response> {
  const rawBody = await request.text()
  const ok = verifyVatnodeSignature(
    rawBody,
    request.headers.get('x-vatnode-signature') ?? undefined,
    VATNODE_WEBHOOK_SECRET
  )
  if (!ok) return new Response('invalid signature', { status: 400 })

  const event = JSON.parse(rawBody) as { id: string; event: string }
  return new Response(null, { status: 200 })
}

Whatever the framework, verify the bytes you received, never a re-serialized copy. If something upstream parses the body before your code sees it, you need the original string preserved somewhere, not just the parsed object.

Timestamp tolerance and replay protection

vatnode does not enforce any tolerance on t itself – a signature stays mathematically valid forever unless your verifier rejects it based on age. That check turns a signature from ‘proves the sender holds the key’ into ‘proves the sender held the key recently’, and it’s entirely your responsibility.

Compare t against your own clock and reject anything too far off – the documented tolerance is 300 seconds (5 minutes). Use the absolute difference so the bound is symmetric: a delivery is accepted only within 5 minutes either side of your clock, and clock skew in either direction fails visibly instead of quietly widening the window. (t is part of the signed message, so nobody can move it without breaking the HMAC.)

if (Math.abs(nowSeconds - t) > TOLERANCE_SECONDS) return false

Each delivery attempt – including retries of the same event – is re-signed with a fresh t at send time; the body bytes stay identical across attempts, only the timestamp and signature change. That’s why dedupe has to key on the envelope’s id, not on t or on the signature value: a retried event is a legitimately different signature for the same logical event. Together, the tolerance check and id-based dedupe are what make a captured delivery unusable if it’s replayed later.

Keep seen ids for at least as long as your tolerance window (longer is fine). Record the id in the same transaction as the work it triggers, or when you enqueue that work: if you mark it seen first and then crash and return a 5xx, the retry is deduped away and the event is lost.

The 401 trap: how a verifier bug silently drops events

This is the failure mode that costs the most and gets noticed last. vatnode’s delivery model treats any 4xx response other than 429 as a permanent failure – not retried, full stop. Only 5xx, 429, and network/timeout errors get retried (up to 5 attempts, exponential backoff of 1s/2s/4s/8s between them). There’s no redelivery or replay endpoint on the API, so a verifier that incorrectly returns 401 or 400 on a signature that was actually valid doesn’t get a second chance – that event is gone.

Returning a 4xx for a genuinely invalid signature is correct – it tells vatnode not to waste retries on a request that will never verify. The trap is a verifier bug that returns the same 4xx on signatures that are actually valid: a wrong secret loaded from an env var, a proxy that re-encodes the body, a clock far enough out of sync to exceed your tolerance window. From vatnode’s side that looks identical to a deliberate rejection, so it’s never retried and nothing flags it as a bug on your end.

The same goes for redirects: a 3xx response is never followed and counts as a permanent failure, so a trailing-slash or HTTP-to-HTTPS redirect in front of your endpoint loses events the same way.

It compounds: enough consecutive definitive failures (5), or 3 days of continuous failure, and vatnode auto-disables the webhook – at that point you’re missing everything until you notice and re-enable it with a passing test.

Only return a 2xx after verification succeeds, and investigate every rejection in production rather than just logging it. A verifier that wrongly rejects valid traffic is exactly the bug a test event is supposed to catch before it touches anything real.

Testing your verifier before it goes live

Every new webhook starts in a disabled state and only becomes active once a test delivery succeeds – a 2xx response is what flips it. If you created the webhook from the dashboard, it sends that test automatically right after creation. If you created it through the API, call POST /v1/webhooks/{id}/test yourself to trigger one.

The test event (event: "webhook.test") is signed exactly like a real one – same header format, same HMAC construction, same raw-body requirement. That makes it a real end-to-end check of your verifier, not a stub: if your verifier has a bug that rejects valid signatures, the test delivery fails the same way a real one would, and the webhook stays disabled instead of silently losing production events. Catching that during setup, against a webhook nothing depends on yet, is a lot cheaper than catching it after VAT_BECAME_INVALID stopped arriving for a week.

Webhooks and VAT monitoring both need a paid plan – the free plan runs on 100 requests/month with no card required, but has no monitoring subscriptions and no webhook slots at all. See pricing for what each paid plan includes.

Rotating the signing key

There’s no rotation endpoint – a webhook’s signing key is fixed for that webhook’s entire lifetime. Rotating means creating a new webhook rather than updating an existing one:

Create a second webhook pointing at the same URL with POST /v1/webhooks and store the new secret from the response. There’s no uniqueness constraint on URL, so two webhooks can target the same endpoint at once – you’ll need a free slot under your plan’s webhook limit.
Deploy your verifier accepting either the old or the new key, and keep deduping on the envelope’s id – during the overlap, the same logical event can arrive twice, once signed with each key.
Call POST /v1/webhooks/{id}/test for the new webhook. It stays disabled until that test passes, so do this only after step 2 is live.
Once the new webhook is active, delete the old one.

Deliveries already queued for retry at the moment you delete the old webhook were signed with the key snapshot taken at fan-out time, so a few old-key deliveries can still land afterward. Retries normally finish within a few minutes, but a queued delivery can be delayed further if delivery is backed up. That’s expected: keep the old key in your accepted set for a generous window – an hour is plenty – unless the key leaked.

If you’re rotating because the key leaked, skip the overlap: delete the old webhook and remove the old key from your verifier immediately. The few retries still in flight will be rejected, which is the price of not accepting forged requests.

Managing more than one webhook – which rotation requires, even briefly – needs the API; the dashboard’s webhook UI manages a single webhook. The management endpoints (/v1/webhooks*) accept either a dashboard session or a live API key; a test key gets 403 TEST_KEY_NOT_ALLOWED, because webhooks deliver real HTTP callbacks to a real endpoint, not fixtures.

FAQ

Why does my webhook endpoint need the raw request body, not the parsed JSON?

Because the signature covers exact bytes, not parsed data. vatnode signs ${t}.${rawBody}, where rawBody is the compact JSON string it sent on the wire. If you reconstruct that string yourself – especially with a different serializer, such as re-encoding in a language whose default JSON writer inserts different spacing – you can produce different bytes than the ones that were actually signed, and the signature will never match even though the payload means the same thing. Verify against the exact body you received, not a round-tripped copy.

What timestamp tolerance should I use when verifying a vatnode webhook signature?

vatnode does not enforce a tolerance itself – that check is entirely up to your verifier. Reject the request when the absolute difference between the current time and the header’s t exceeds 300 seconds (5 minutes). Use absolute difference, not just whether t is in the past, so the window is bounded in both directions and clock skew can’t stretch it.

If my verifier wrongly rejects a valid signature, will vatnode retry the event?

No – a 4xx response other than 429 is treated as a permanent failure and is never retried; only 5xx, 429, and network or timeout errors are. There is no redelivery or replay endpoint, so a verifier bug that returns 401 on a valid signature loses that event for good. Enough consecutive failures, or three days of continuous failure, disables the webhook entirely.

How do I rotate a webhook’s signing key without missing events?

There is no rotation endpoint – a signing key is fixed to its webhook for that webhook’s lifetime. To rotate, create a second webhook pointing at the same URL (there is no uniqueness constraint on URL) and get its new key into your verifier. Accept either key for an overlap window of about an hour, dedupe on the event id, then delete the old webhook. Already-queued retries were signed with the key snapshot at fan-out, so a few old-key deliveries can still arrive for a while after deletion – that’s expected, not a bug. If the key leaked, skip the overlap and drop the old key at once.

Next step

Full endpoint and payload reference lives in VAT monitoring; the end-to-end setup guide for monitoring alerts and webhook delivery is at VAT monitoring and webhooks. Before you wire real business logic to an event, make sure idempotency and retries on the rest of your VAT stack hold up too – see idempotency and retries when calling a VAT validation API.

DEV Community: Iurii Rogulia

Building a Verified n8n Node That Is Exposed as an AI Agent Tool

What the Flag Does

Designing Operations for a Reader That Can Spend Money

Errors a Reader Can Act On

The Verification Path

Limits and Trade-offs

What to Check Before You Submit

Who This Is For

Document Forgery Detection Methods Compared

Document forgery detection: the four method classes

Manual review: what a human sees and misses

Content-based checks: what they validate and what slips through

Identity and issuer checks

Structural PDF forensics

Side-by-side comparison

What none of these methods can prove

PDF tampering detection in a layered workflow

How to choose and combine methods

Frequently asked questions

What is document forgery detection?

Can document forgery be detected without reading the document’s content?

What is the difference between structural PDF forensics and content-based document checks?

Does an intact result prove a document is authentic?

VAT Validation in Next.js Server Actions

Why not as-you-type here

A Server Action is a public POST endpoint

Keep the key server-only

Local format check without breaking test mode

The action, wired to useActionState

Calling vatnode with a bounded timeout

Mapping every outcome by error code, not HTTP status

Never block the order on an unverified check

Testing with a test key

Next steps

FAQ

UK Visa Bank Statement Fraud: What UKVI Actually Checks

Does UKVI verify bank statements?

What UKVI asks for, route by route

Student route

Work routes

Family routes

Visitors

How the Home Office checks financial evidence

Three checks that answer different questions

What a file-level tamper check can and cannot tell you

What to do with a modified or inconclusive result

Where it fits in an intake workflow

FAQ

Does UKVI contact the bank to check a statement?

Is an HTPBE inconclusive verdict the same as the Home Office’s inconclusive verification outcome?

Can a tamper check confirm the funds requirement is met?

What a Fractional CTO Actually Costs

The Three Prices You’re Choosing Between

Where the Break-Even Actually Sits

When You Do NOT Need One Yet

When Full-Time Is Actually the Right Spend

The One-Line Test

Fake PDF Detector Tools: What They Check and Miss

Short answer: what a fake PDF detector actually does

The six kinds of fake PDF detector

Metadata viewers and online edit checkers

Visual, AI-image and OCR checkers

Manual review

What structural forensics adds

What no PDF detector proves, including ours

How to choose: a decision guide

Frequently Asked Questions

Where to go from here

When a B2B Customer Won't Give You a Valid VAT Number

Three situations, and they’re not the same problem

No VAT number given at all

A number was given, but it doesn’t check out

VIES or a member-state service can’t confirm it right now

What EU rules actually let you assume

What to charge instead

What to tell the customer

What to record

If the number arrives later

FAQ

What to do with a `modified` or `inconclusive` result

Is an HTPBE `inconclusive` verdict the same as the Home Office’s inconclusive verification outcome?