Using the TrustVerify Sandbox: Test Keys and Your First Check

The hardest part of integrating identity and business checks is usually not the happy path. It is the other paths: the failed verification, the sanctions match, the company that needs review. Those are the cases your code must handle well, and they are the hardest to produce on demand with real data.

The TrustVerify sandbox exists for that. This post covers how test keys work, what the sandbox returns, how to force specific outcomes and what it does not cover.

Test keys and live keys

TrustVerify API keys come in two kinds, and you can tell them apart by the prefix:

• Test keys start with tv_test_sk_
• Live keys start with tv_live_sk_

Requests made with a test key run in sandbox mode. Requests made with a live key run real checks against real data sources. Keep live keys out of development environments and CI entirely. If a key starting tv_live_sk_ appears in a test config, treat it as a bug.

The authentication docs cover how to send the key, and the quickstart walks through setup.

What the sandbox returns

For checks that call paid upstream data sources, such as identity, business and AML checks, a test key gets a synthetic response instead of a real lookup. Two properties make these useful:

They are deterministic. The same input gives the same output every time. Your tests will not flake because a third-party service had a slow afternoon.

They are labelled. Sandbox responses include "environment": "sandbox", so your code and your logs can always tell a fixture from a real result. It is worth asserting on this in your integration tests, so a misconfigured key fails loudly.

The response shape matches what you get in live mode. Code that parses a sandbox KYB result will parse a live one.

Forcing specific outcomes

The sandbox recognises a small set of magic values that produce specific results. These let you test every branch of your decision logic.

Business checks (KYB)

• Company number 00000000 returns passed
• Company number 99999999 returns review

AML screening

• A name containing sanction test returns a match
• A name containing pep test returns a potential match

Identity checks (KYC)

• Setting metadata.forceStatus to failed or review forces that status

The full list is in the sandbox docs. Use these values rather than real company numbers or real people's names. There is no reason for personal data to be in your test suite.

Your first check

A simple first test sequence:

1. Create a test key in the dashboard.
2. Run a KYB check with company number 00000000. Confirm you get passed and environment: "sandbox".
3. Run it again with 99999999. Confirm your code routes the review result correctly.
4. Run an AML check on a name containing sanction test. Confirm your code stops the flow.
5. Run a KYC check with metadata.forceStatus set to failed. Confirm the user sees the right message.

Five calls, and every main branch of your onboarding logic has been exercised. The exact request bodies are in the API reference.

What the sandbox does not intercept

Some endpoints are not replaced with fixtures, and it is important to know which:

• fraud score
• trust score
• webhooks
• fetching a check by ID
• phone checks

These run their normal logic even with a test key, so they behave in the sandbox much as they will in production. For the fraud score, that means your test inputs are scored for real, so a sequence of odd-looking test requests can produce higher-risk results. Design those tests with that in mind.

For webhooks, the key point is that your receiving endpoint still needs to verify signatures and handle retries properly. Our post on KYC webhooks and decision handling covers signature checks with the X-TrustVerify-Signature header and idempotent handling with X-TrustVerify-Delivery-Id.

Sandbox data does not linger

Sandbox records are kept for 30 days and then deleted. That is long enough to debug an integration and short enough that test data does not pile up. If you need a test result for longer, for example as a reference in your own test fixtures, save the response in your repository.

Errors and rate limits

Test the failure paths too. Send a request with a missing field and confirm your code handles the error response. Check the errors reference and rate limits so your retry logic backs off rather than hammering the API.

Moving to live

Before switching to a live key:

• Remove every magic value from production code paths.
• Make sure nothing in production depends on environment: "sandbox".
• Confirm your webhook endpoint is reachable, verifies signatures and handles retries.
• Check your handling of unverified and not_screened results, which are more common in live mode when an upstream source is unavailable.
• Store live keys in a secrets manager, not in config files, and rotate any key that has ever been committed to a repository.

Writing good integration tests

A few habits make sandbox testing more useful:

• One test per outcome. Have a named test for each status your code handles: passed, review, failed, unverified, match, potential match. If a new status appears later, you will notice the missing test.
• Assert on the environment field. A test that checks for environment: "sandbox" will fail straight away if someone points the test suite at a live key.
• Keep fixtures small. Store the minimum response your code needs to parse, not entire payloads with every field.
• Test the unhappy network paths. Timeouts, error responses and retries are where integrations most often break in production. Simulate them in your own HTTP client tests.
• Run the suite in CI. Because sandbox responses are deterministic, these tests are safe to run on every commit.

Teams that do this usually find the edge cases in development rather than in their first week live, when real sellers are waiting.

Key takeaways

If you only remember a few points from this post, make them these:

• Test keys start tv_test_sk_; live keys start tv_live_sk_. Keep them apart.
• Sandbox results are deterministic and labelled with environment: sandbox.
• Use the magic values to exercise every branch of your decision logic.
• Remember that fraud score, trust score, webhooks, check lookups and phone checks are not replaced with fixtures.
• Keep genuine personal data out of your test suite.
• Work through the go-live checklist before switching keys.

None of these points requires a large team or a long project. Most can be put in place in a few weeks, and each one makes the next decision easier to explain.

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

Get a test key and run your first five checks. Open the sandbox docs.

Related posts

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.

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

Rate Limits, Retries and Idempotency for Verification APIs

How verification API rate limits work, which errors to retry, how to back off properly and how to keep retries from creating duplicate checks.