Integrating KYC via API into Marketplace Seller Onboarding

Most marketplace teams reach the same point. Seller signups are growing, a few bad accounts have got through, and someone asks for identity checks before a seller can list. Engineering then has to work out what that involves: capturing a document and a selfie, sending them somewhere, reading the result and deciding what the seller sees next.

The good news is that the verification itself does not need to be built. A KYC API does the document reading, the face comparison and the screening. Your job is to capture good images, make one call from your server, and turn the answer into a clear decision. This post walks through that flow using TrustVerify's public v1 API as it works today.

What the API call does

TrustVerify's identity check is a single request: POST /api/v1/kyc/verify. Your server sends it with your API key, and it carries:

• a base64-encoded image of the document front, with an optional back image
• a base64-encoded selfie
• a documentType of passport, national_id or driving_licence (passport is the default)
• optional checks, such as AML screening, which needs the person's name in metadata
• an optional generateReport flag, which adds a link to the PDF report in the response

The check runs document data extraction, compares the selfie with the document photo, and runs screening if you asked for it. The result comes back in the same response, so for most integrations there is nothing to poll.

One point to be clear about early: the check confirms that the selfie matches the document photo. It does not tell you how the selfie was captured. We come back to what that means for your rules below.

Where the check belongs in your onboarding flow

Placement matters more than most teams expect. Ask for ID too early and people abandon signup before they have seen any value. Ask too late and unverified sellers are already live.

A pattern that works for most marketplaces:

1. Account creation. Email, password, basic profile. No ID yet.
2. Seller setup. Shop name, category, first draft listing. The seller is invested now.
3. Verification gate. Before the first listing goes live or before the first payout, ask for the document and selfie.
4. Pending state. Listings can be drafted, but nothing publishes until the check has a result.

This keeps the ask close to the moment it matters, and gives sellers a reason to finish.

Capturing images that pass

Many failed checks are photo problems, not identity problems. Today your own app captures the images and your server sends them. That works on web and mobile. TrustVerify's capture guide recommends:

• JPEG or PNG
• around 1,500 to 2,000 pixels on the long edge
• the whole document in frame, flat, with no glare over the text or photo
• the whole request up to 10 MB

For the selfie, ask for a front-facing photo in good light, with the whole face visible and no hats, sunglasses or filters. Take a fresh photo in your app rather than accepting one from the camera roll.

On the web, a file input with a camera hint opens the phone camera directly. On native apps, use the platform camera and save a JPEG. Either way, send the images to your server, not straight to the API. Your API key must stay on the server.

Capture happens in your own app.

The integration, step by step

1. Get sandbox keys. Test keys start with tv_test_sk_ and return synthetic results. Live keys start with tv_live_sk_.
2. Capture on the client. Collect the document image (and back, if relevant) and the selfie, with the guidance above.
3. Call from your server. Post the images to /api/v1/kyc/verify with your key in the authorisation header. Store the checkId from the response against the seller.
4. Read the result. The response includes a status of passed, review or failed, a riskLevel of low, medium or high, and signals for the face match and screening.
5. Act on it. Approve, send to review, or block, according to your policy.
6. Retrieve later. GET /api/v1/checks/{checkId} returns the stored result whenever you need it again.

The quickstart and the KYC seller onboarding guide cover authentication and request formats in full. The API reference lists every field.

Reading the result honestly

The response is designed so that missing data never looks like a pass, and your code should respect that.

Null is not true. Each signal can be true, false or null. Null means no result was returned for that field. A passed status requires an explicit true from the face match, plus a clear AML result when screening was requested. Write your own rules the same way: only an explicit positive counts.

Some signals can be null. If your risk policy needs more than a face match, hold those sellers in review or add a step of your own.

The score can be null too. The score field is a confidence figure bounded by the weakest piece of evidence. It is null when providers returned verdicts but no numbers. Do not read null as zero.

503 means no verdict. If a required provider did not return a result, the API returns 503 rather than guessing. The response lists the unavailable providers. Retry later with backoff, and keep the seller in a pending state meanwhile. The rate limits page explains which errors to retry and how.

Turning results into decisions

Map API results to three seller outcomes and write the mapping down:

• Approve. passed, with the signals your policy requires. The seller can go live.
• Review. review, or a result your policy treats as uncertain, such as needing more than a face match. A person looks at the case. TrustVerify's review queues are built for this.
• Block. failed, or a confirmed problem found in review. Tell the seller what happens next and how to query it.

Do not treat one failed attempt as final. Many failures are poor photos. Let the seller retake, and route repeated failures to a person.

Webhooks and fetching outcomes

Because the verify call returns its result synchronously, many integrations do not need webhooks for KYC at all. Where you do use them, know what fires.

The verification.completed webhook event fires when a KYC check is approved, with the check ID, status and risk level. It does not fire for review or failed outcomes. For those, use the synchronous response, or fetch the result with GET /api/v1/checks/{checkId}.

Also note that a webhookUrl placed in request metadata is not called: per-request callbacks are paused, and the response says so. Subscribe to events through the webhooks resource instead.

When you do receive webhooks, verify the signature, respond quickly with a 2xx, and de-duplicate using the X-TrustVerify-Delivery-Id header. Deliveries time out after 10 seconds, redirects are not followed, and failed deliveries are retried up to three times with exponential backoff. Our post on KYC webhooks and decision handling goes into the detail. [Planned URL, live on publication.]

Testing before you go live

The sandbox lets you run the whole flow with test keys and synthetic data. Use it to check:

• your capture screens produce images within the size and quality guidance
• your server handles passed, review and failed correctly
• null signals are treated as "not assessed", not as passes
• a 503 leaves the seller pending and retries later
• you store the checkId and can fetch the result again

Never use genuine personal documents in testing.

Common mistakes

Calling the API from the browser. That exposes your key. Always go through your server.

Treating a missing signal as a pass. Code that checks "not false" will wave through nulls. Check for true.

Waiting for a webhook that will not come. Only approvals fire verification.completed. Handle review and failed results from the response or by fetching the check.

Describing the check as more than it is. "We match your selfie to your ID" is accurate. "We confirm who you are beyond doubt" is not.

Forgetting retention. Document images and selfies are sensitive. By default, TrustVerify deletes due diligence check records after five years. Set your own retention for anything you keep.

When KYC alone is not enough

Identity checks confirm a person. If your seller trades through a company, you also need to check the business. See KYB for UK businesses. And because a selfie match does not confirm how the selfie was captured or what the seller intends, combine it with screening, email and phone checks and device signals for higher-risk sellers.

For what the checks themselves cover, see our KYC software for UK businesses and the guide to choosing KYC software in the UK.

Next step

Run your first KYC check in the sandbox. Open the TrustVerify quickstart.

Related posts

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.