TrustCaptcha API

The public TrustCaptcha API consists of one server-side call: fetching a verification result with the verification token your frontend widget produced. Everything else (creating verifications, solving challenges) is done by the widget itself — your backend never calls those endpoints.

Fetch a verification result

curl "https://api.trustcomponent.com/captcha/v2/verifications/{verificationId}/results" \
     -H "Authorization: Bearer ak_your_key_here"

Parameter	Description
`verificationId`	UUID, extracted from the verification token the widget adds to your form
`Authorization`	A Project API key (`ak_…`) as bearer token

Response

{
  "captchaId": "…",
  "verificationId": "…",
  "verificationPassed": true,
  "score": 0.3,
  "decisionType": "STANDARD",
  "decisionAction": "ALLOW",
  "gatewayFailoverActive": false,
  "riskScoringEnabled": true,
  "minimalDataModeEnabled": false,
  "origin": "https://www.example.com",
  "ipAddress": "203.0.113.7",
  "countryCode": "DE",
  "deviceFamily": "Mac",
  "operatingSystem": "Mac OS X",
  "browser": "Firefox",
  "verificationStartedAt": "2026-07-01T10:29:55.000Z",
  "verificationFinishedAt": "2026-07-01T10:30:00.000Z",
  "resultExpiresAt": "2026-07-01T10:45:00.000Z",
  "resultFirstFetchedAt": "2026-07-01T10:30:02.000Z",
  "resultLastFetchedAt": "2026-07-01T10:30:02.000Z"
}

Field	Meaning
`verificationPassed`	The overall pass/fail verdict — the field most integrations act on
`score`	Bot risk score from `0` (human) to `1` (bot)
`decisionType`	How the verdict was reached: `STANDARD`, `BYPASS_KEY`, `CUSTOM_ACCESS_RULE`, `GLOBAL_IP_ACCESS_RULE`, `FAILOVER`, `FAILOVER_TOLERANCE`
`decisionAction`	Recommended action: `NO_ACTION`, `ALLOW`, `BLOCK`, `CUSTOM`
`gatewayFailoverActive`	`true` when the result was synthesized by the failover gateway — see Failover Behavior
`riskScoringEnabled`, `minimalDataModeEnabled`	The captcha configuration that applied
`origin`, `ipAddress`, `countryCode`, `deviceFamily`, `operatingSystem`, `browser`	Request metadata (empty in minimal-data mode)
`verificationStartedAt` / `verificationFinishedAt`	When the widget verification ran
`resultExpiresAt`, `resultFirstFetchedAt`, `resultLastFetchedAt`	Retrieval bookkeeping (see below)

How to evaluate verificationPassed vs. score and the decision fields — including recommended thresholds — is covered in Result Validation.

Retrieval semantics

A result is retrievable for 15 minutes after the verification — fetch it right when the form is submitted.
By default a result can be fetched exactly once; a second fetch returns 429. Both the validity period and the allowed fetch count are configurable per captcha environment.

Status codes

Code	Meaning
`200`	Result returned
`403`	Authorization header missing or API key invalid
`404`	Unknown `verificationId`
`410`	Result expired (older than its validity period)
`423`	Result not yet released — the verification hasn’t finished
`429`	Allowed fetch count exceeded (result already retrieved)

Testing your integration

Fixed test verification IDs return canned responses without a real verification — the last digit selects the outcome:

`verificationId`	Response
`00000000-0000-0000-0000-000000000000`	`200` with a sample passed result (requires the test key `ak_` + 49 × `x`)
`…-000000000001`	`404`
`…-000000000002`	`423`
`…-000000000003`	`410`
`…-000000000004`	`429`