About the API
Base URL, conventions and the stability promise behind every endpoint
The reference pages under this section are generated directly from the TrustWix OpenAPI document, so they describe exactly what each endpoint accepts and returns. The document itself is published at /openapi.json if you want to generate a client, mock server or types from it.
What is documented here is what your integration calls. Setup work is not: your API keys and your flows are managed in your dashboard, which is the only surface that has the whole lifecycle for either, so you will not find endpoints for them. See Authentication and Flows.
Base URL
https://api.trustwix.comOne host serves both environments. Which one you are in is decided by the key you authenticate with. The environment is set on the key when it is created and shown against it in your dashboard, rather than encoded in the key string. See Authentication.
Conventions
Requests and responses are JSON. Send Content-Type: application/json on anything with a body.
Timestamps are RFC 3339 strings in UTC. Most object ids are prefixed by type, so vs_ is a
verification, chk_ a check, flw_ a flow, whe_ a webhook endpoint and evt_ a webhook event,
which makes a stray id in a log self-describing.
Not all of them are. Manual reviews are identified by a bare UUID, so starting_after takes a UUID
when you page that list and a prefixed id when you page the others. Read the parameter on the
endpoint rather than assuming.
Every response carries X-Request-Id. You can supply your own and it is echoed back.
List endpoints are cursor-paginated and newest first. Pass limit and starting_after, and read
has_more and next_cursor from the response rather than counting.
Stability
The API is versioned in the path at /v1. Within a version, changes are additive: new endpoints, new
optional request fields and new response properties can appear without notice, and existing fields
do not change meaning or disappear. Anything incompatible ships as a new version, and /v1 keeps
working.
Do not use strict object mappers
Because new response properties can appear at any time, a deserializer configured to throw on unknown keys will break on a routine, backwards-compatible change. Configure yours to ignore what it does not recognise.
The same applies to enumerated values. New reason codes, new webhook event types and new check types are additive, so always have a default branch.
Reliability
Send an Idempotency-Key when you create a verification, the one call that honours it, see
Idempotency. Respect the rate limit headers and back off with jitter, see
Rate limits. Every failure uses one envelope, see Errors.
Where to start
Verifications is the endpoint set almost every integration needs. Everything else exists to support it.