Reference · Server API

POST /api/v1/verdict

The server-to-server check. This is the one that can refuse.

The server-to-server check. This is the only endpoint that can actually refuse anybody.

POST /api/v1/verdict

Why it exists#

The verdict the SDK hands the page is advisory: it arrives after the page was served, it is drawn by JavaScript, and a scripted client never runs it. This endpoint is where your backend asks before answering.

Authentication#

The site secret, in the x-api-key header. Never the public key.

It deliberately sends no CORS headers, a browser must not be able to reach it.

Request#

{
  "visitorId": "<fpc_vid cookie>",
  "requestId": "<optional, from the SDK verdict>",
  "ip": "<the client's address>",
  "userAgent": "<user-agent header>",
  "headers": { "accept-language": "..." },
  "payment": { "card": "<processor card fingerprint>", "amount": 12.5, "currency": "USD" }
}

The payment block is optional; sending it makes the request a payment attempt. See Payments.

Reply#

{
  "verdict": "allow",
  "score": 0,
  "reasons": [],
  "source": "visit",
  "visitorId": "...",
  "payment": { "attemptId": "...", "measured": true }
}

source says which case answered:

Value	Meaning
`visit`	A stored visit for this visitor answered
`request`	Never seen, so judged from the user agent, address and headers you forwarded

This lets you tell "we have never seen this visitor" from "we have, and they looked fine".

How far an identity is trusted#

The stored visit decides identity. A visitorId you send is only used to find a record; when none is found, the verdict is judged from the request rather than the claim.

No outbound IP lookup#

Address reputation is read off the stored visit. Putting a third party in the path of your checkout puts their downtime in your revenue.