How TrustVerify reads documents, phone numbers and UK company records with published standards and open libraries, and why a missing check is never a pass.
Closed verification products often hand you a colour and a logo. The colour is the product. You cannot see whether a document was actually read, whether a screen completed, or what happens when an upstream is down. We built TrustVerify so a marketplace can see the measurement, and so a missing measurement cannot masquerade as a pass.
"Open-source signals" is the name for that choice. Where the industry already published the rule — a check digit, a number format, a public register — we implement the rule and show the result. Where we use an open library, we name it here. The customer's integration stays on the TrustVerify API either way.
This is an engineering article. It describes what the code does today. It is not a promise that every check in the platform is an open-source project, and it is not a claim about where servers are located.
Published rules, implemented in the open. The check digits on a passport's machine-readable zone are specified by ICAO 9303. Phone numbers have a published structure. UK companies have a public register. We would rather compute those than return "verified" with nothing underneath.
A stable integration. Your sign-up flow calls TrustVerify. It does not branch when the way a check is performed changes behind that API. See the docs.
Some checks depend on a data provider. This article does not invent a story in which every provider can be swapped on a Tuesday. What the code does show, and what hurts marketplaces, is the opposite failure: a provider that did not answer, recorded as if it had passed.
An identity check starts with the image of a document. Text is extracted with Tesseract, the open-source OCR engine, running in the image that serves the check. The interesting part is not the OCR brand. It is what happens when the text is thin.
A busy photo of a desk can produce some characters and a confidence figure. That used to be enough for a check to continue as if a document had been read. It is not enough now. If no name and no document number were read, the document is not readable, including when OCR did not run at all. An unreadable document cannot be approved automatically, and it cannot show as low risk on the trust score: the score is held to at most 59.
Where a machine-readable zone is present, the check digits are computed the way ICAO 9303 specifies. A valid check digit means the line is internally consistent. It does not mean the selfie matches the holder, and it does not mean the document is current. Expiry is tested separately. An expired document holds the trust score to at most 74 and holds the check for a person.
The selfie is compared with the photo on the document. That comparison is a measurement. If it did not run, the report does not print a face-match of zero, because zero would read as "these two faces were compared and do not match". A comparison that never happened is "not assessed". The same rule applies in the other direction: a comparison that ran and scored zero stays in the result. Dropping a genuine zero would make the score look healthier than the evidence.
We cover liveness checks. Liveness is not shown as a separate number in the trust score.
Proof-of-address images can be collected with the check so your team can look at them. Collecting a file is not the same as confirming the address against a register. The report should be read that way. Details are on identity verification and KYC.
At sign-up, before you send a code or accept a listing, you can check the contact details. Both checks are deliberately modest.
Phone. The number is parsed offline with libphonenumber-js. The response normalises it to E.164 and returns the country, a line type and a risk score. The carrier is the network the number range was allocated to. It is not a live lookup, and it does not follow a number that has been ported. A test key returns a fixed sandbox answer.
Email. The check covers syntax, whether the domain has mail servers, disposable domains, and role addresses such as info@. The verdict is deliverable, undeliverable, risky or disposable. If the domain could not be looked up, treat that as unknown, not as undeliverable.
Neither check proves the seller is who they claim to be. They stop the obvious rubbish before you spend an identity check on it. The guide is email and phone checks.
A limited company seller is not verified by an identity score. The company is a separate fact.
TrustVerify reads the UK company from Companies House: name, number, status, registered office and officers, and the people with significant control. Those people are the starting point for who controls the business. They are not, by themselves, proof that the person opening your seller account works there. You still check that person. KYB and UK registry checks describe the flow. Business checks cover UK companies.
Where the company has a Legal Entity Identifier, we match it against the public LEI records operated by GLEIF. No LEI is a normal outcome for a small UK seller. It is not a fail. An outage that cannot be distinguished from "no LEI" is a reason to treat "not found" with care and look at the Companies House record beside it, rather than to invent a match.
Screening of the company and of the people who control it is a further check, with re-screening after onboarding for subjects you enrol. A screen that does not complete is not stored as clear. Enrolment for monitoring runs a real screen first. If the provider does not answer, nothing is written and the caller gets an error, because a monitor with an unknown baseline is worse than no monitor. Alerts go to a webhook you registered, subscribed to aml.hit, not to an address pasted onto the monitor. That keeps signing, retries and the delivery log in one place. See ongoing monitoring and webhooks.
If you are writing the integration, store the status you received. Do not map an empty field to approved because a database column is non-null. That is how a marketplace approves a seller during an outage.
The trust score guide has the sibling rule for the weighted API. You send values from 0 to 1. If you send nothing, the score is 50 and the tier is provisional. Fifty is not "trusted". Do not send a 1 for a signal you did not measure.
There is no starter repository to clone and no language client we ask you to install. You call the HTTP API.
A typical seller sign-up:
WooCommerce. There is a plugin you download and install. It scores orders at checkout and can flag or hold them against thresholds you set. It does not cancel orders on its own. WooCommerce.
Shopify. Install the TrustVerify app on your store. On a paid plan, new orders are scored and tagged. Cancelling a high-risk order is an opt-in for that store. It is an app connection, not a plugin you drop into a theme. Shopify.
Your own stack. The fraud score takes an IP, a device fingerprint from your client, browser details you forward, and the order. If there is no IP result, the score is marked as a heuristic and will not come back as approve. A fallback must not look like a full result.
Sandbox test keys let your team walk the flow before a live seller does. A test key does not write the live device-velocity store. API keys are stored only as SHA-256 hashes and shown once, when you create them. An API key can call the API. It cannot sign in to the dashboard.
"The customer keeps their data" is a slogan we are not going to stretch. Here is the concrete version.
TrustVerify's registration with the Information Commissioner's Office is ZB962144, under UK GDPR. That is a registration, not a certificate that a document check is lawful for your marketplace. Biometric data used to identify someone is special category data. Your lawful basis, your privacy notice and your retention period are yours to set with your adviser. The ICO's explanation of special category data is here: ICO — special category data. The Data Protection Act 2018 sits alongside the UK GDPR.
Two-factor authentication for dashboard accounts is not in place. We do not describe it as if it were.
A marketplace in Bristol sells spare parts for commercial kitchens. The same endpoint path serves both seller types. The branch is yours.
Dana, a sole trader in Bath, lists used mixers. The document could be read, the expiry is in the future, the typed name matches, the face comparison ran, and the screen completed as clear. Status approved. You enable listing and store the check identifier. You do not also store a homemade "verified" flag you cannot reconstruct.
Harbour Parts Ltd, company number on the application, wants to sell new refrigeration units. Your server looks the company up. Companies House shows the company active, with two directors and one person with significant control. The person who filled in your form is not among them. The company check did not fail — the company is real — and it did not pass the person. You hold payouts, ask the applicant to be verified as themselves, and have a reviewer confirm they are authorised by the company. The review is a recorded decision, not a note in a chat. If the company later changes its person with significant control, monitoring is what tells you. The original trust score will not.
When Harbour Parts Ltd's buyer is a restaurant paying a large deposit, the goods can sit in escrow through Escrow.com, available on request. That is a separate arrangement from the check. The check does not move the money.
A summary for engineers, not legal advice.
If you are wiring the first seller, start with the docs, then seller verification for the operational picture and plans for what a subscription includes. If you are deciding whether a score is allowed to approve anyone, read what a trust score is before you write the rule.
Take one approved seller and one held seller. From the record alone, say which checks ran, which did not, and why the status is what it is. If you need a vendor slide to answer that, the integration is hiding the signal.
KYC, KYB, AML screening and fraud prevention in one place, with published pricing.
Developer
Using the TrustVerify Sandbox: Test Keys and Your First Check
A developer guide to the TrustVerify sandbox: test and live keys, deterministic synthetic results, magic test values and what the sandbox does not cover.
Developer
Pulling Verification Reports via API
How to fetch KYC, KYB and AML screening reports by API, check they exist, download the PDF and assemble an evidence bundle for audit.
Developer
KYC Webhooks and Decision Handling for Marketplaces
A practical guide to consuming KYC and fraud webhooks on a marketplace: signatures, retries, idempotency and mapping decisions to seller states.
