Send a check

curl -X POST 'https://protection-api-service.vercel.app/v1/protection' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "flow": "signup",
    "event_id": "signup:user_123",
    "email": "person@example.com",
    "device_token": "dtok_...",
    "client": {
      "ip": "203.0.113.10",
      "user_agent": "Mozilla/5.0 ...",
      "accept_language": "en-US,en;q=0.9",
      "ip_source": "explicit",
      "ip_trusted": true
    },
    "context": { "surface": "password_signup" }
  }'

{
  "contract_version": "1",
  "flow": "signup",
  "recommendation": "review",
  "check_id": "chk_123",
  "event_id": "signup:user_123",
  "policy": {
    "id": "signup_protection",
    "version": 4,
    "configured": true,
    "action": "review",
    "reasons": [{ "code": "R3", "label": "Disposable email" }]
  },
  "data_quality": {
    "confidence": "verified",
    "gaps": []
  },
  "diagnostics": {
    "device": { "token_present": true, "token_valid": true, "reason": null },
    "ip_source": "explicit",
    "ip_trusted": true,
    "velocity": {
      "status": "none",
      "contributors": [],
      "reason": "No velocity detector reached a monitoring threshold."
    }
  },
  "reasons": [
    { "rule": "R3", "label": "Disposable email", "expr": "email.is_disposable = true", "contribution": "matched -> review" }
  ]
}

curl -X POST 'https://protection-api-service.vercel.app/v1/protection' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "flow": "signup",
    "event_id": "signup:user_123",
    "email": "person@example.com",
    "device_token": "dtok_...",
    "client": {
      "ip": "203.0.113.10",
      "user_agent": "Mozilla/5.0 ...",
      "accept_language": "en-US,en;q=0.9",
      "ip_source": "explicit",
      "ip_trusted": true
    },
    "context": { "surface": "password_signup" }
  }'

{
  "contract_version": "1",
  "flow": "signup",
  "recommendation": "review",
  "check_id": "chk_123",
  "event_id": "signup:user_123",
  "policy": {
    "id": "signup_protection",
    "version": 4,
    "configured": true,
    "action": "review",
    "reasons": [{ "code": "R3", "label": "Disposable email" }]
  },
  "data_quality": {
    "confidence": "verified",
    "gaps": []
  },
  "diagnostics": {
    "device": { "token_present": true, "token_valid": true, "reason": null },
    "ip_source": "explicit",
    "ip_trusted": true,
    "velocity": {
      "status": "none",
      "contributors": [],
      "reason": "No velocity detector reached a monitoring threshold."
    }
  },
  "reasons": [
    { "rule": "R3", "label": "Disposable email", "expr": "email.is_disposable = true", "contribution": "matched -> review" }
  ]
}

Evaluates one signup or login against the policy for its flow and returns a recommendation. Call it from your backend with a Secret key. The server SDKs build this request for you; use the HTTP API directly only if there is no SDK for your stack.

POST https://protection-api-service.vercel.app/v1/protection
Authorization: Bearer sk_...
Content-Type: application/json

Draft value. The Risk API address and check path are placeholders until the final public address is set.

curl -X POST 'https://protection-api-service.vercel.app/v1/protection' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "flow": "signup",
    "event_id": "signup:user_123",
    "email": "person@example.com",
    "device_token": "dtok_...",
    "client": {
      "ip": "203.0.113.10",
      "user_agent": "Mozilla/5.0 ...",
      "accept_language": "en-US,en;q=0.9",
      "ip_source": "explicit",
      "ip_trusted": true
    },
    "context": { "surface": "password_signup" }
  }'

{
  "contract_version": "1",
  "flow": "signup",
  "recommendation": "review",
  "check_id": "chk_123",
  "event_id": "signup:user_123",
  "policy": {
    "id": "signup_protection",
    "version": 4,
    "configured": true,
    "action": "review",
    "reasons": [{ "code": "R3", "label": "Disposable email" }]
  },
  "data_quality": {
    "confidence": "verified",
    "gaps": []
  },
  "diagnostics": {
    "device": { "token_present": true, "token_valid": true, "reason": null },
    "ip_source": "explicit",
    "ip_trusted": true,
    "velocity": {
      "status": "none",
      "contributors": [],
      "reason": "No velocity detector reached a monitoring threshold."
    }
  },
  "reasons": [
    { "rule": "R3", "label": "Disposable email", "expr": "email.is_disposable = true", "contribution": "matched -> review" }
  ]
}

Request body

Send at least one of email, phone, client.ip or device_token.

string

required

The business flow: signup or login. The Risk Platform runs the policy mapped to this flow.

string

Your correlation key for this check, up to 128 characters. Generate it on your server. A retry with the same event ID and the same inputs returns the existing check; the same event ID with different inputs returns 409 event_conflict. Strongly recommended.

string

The email address used in the signup or login.

string

The phone number, when your flow collects one.

string

The device token from the x-abstract-device-token header of the browser request. Opaque and single-use; don’t parse it. See Device tokens.

object

The original browser context, read from the user’s request to your server.

Show properties

string

The original client IP address. This is the IP signal for the check.

string

The original browser user agent.

string

The original Accept-Language header.

string

Where you got the IP: explicit, platform, proxy_header, socket or unavailable.

boolean

Whether you trust that source. A forwarded header you haven’t validated is untrusted.

object

Small, non-sensitive metadata of your own, such as the signup surface. Never put passwords, cookies, session data or authorization headers here.

object

Returns a fixed test response instead of running a live check. Test checks aren’t stored, and test responses carry the X-Protection-Test-Mode: true header.

Show properties

string

required

allow, review, block, device_invalid or timeout.

integer

Delay for the timeout fixture, from 1 to 5000 milliseconds.

Response

string

Response contract version. Currently "1".

string

The flow you sent.

string | null

allow, review or block. null when no policy is configured for the flow.

string

The unique ID of this check. Use it to find the check in the dashboard and to report outcomes.

string

The event ID you sent.

object

The policy that scored the check.

Show properties

string | null

Policy ID. null when no policy is configured.

integer | null

The policy version that scored the check.

boolean

false when the flow has no policy yet.

string | null

Same value as recommendation.

array

The rules behind the recommendation. Each has a stable code (the rule ID) and an optional display label.

object

How complete the evidence was: confidence (verified, partial or unverifiable) and gaps, the fields a rule needed but couldn’t resolve.

object

Request quality: device (token_present, token_valid, reason), ip_source, ip_trusted, and the velocity assessment (status of none, watch or high, contributors, reason).

array

The rule trace: for each rule, rule, label, expr (the condition as text) and contribution.

object

The email signal used by the check, from Email Reputation.

object

The phone signal used by the check, from Phone Intelligence.

object

The IP signal used by the check, from IP Intelligence.

object

The device evidence from the device token: browser, automation and integrity flags.

object

The context the check was evaluated with.

Compatibility fields

Responses also include call_id, run_id, verdict, risk_level, decision_phase, score, policy_applied, policy_version, data_gaps and check_confidence. They are kept for older integrations and are deprecated. Use check_id, recommendation, policy and data_quality instead.

Errors

Status	`error`	Common `reason`	What to do
400	`bad_request`	`malformed_json`	Fix the request body. Send at least one signal.
401	`unauthorized`	`unauthorized`	Check the Secret key.
403	`forbidden`	`sandbox_fixture_required`	The public test key only works with `test_mode.fixture`.
409	`conflict`	`event_conflict`	The event ID was reused with different inputs, or is still processing. Use a new event ID for a new action.
429	`rate_limited`		Back off and retry after `Retry-After`.
429	`rate_limited`	`unconfigured_flow_limit_exceeded`	The flow has no policy and reached its limit. Create a policy for it. See Flows without a policy.
500	`internal_error`		Retry only with the same event ID.
503	`service_unavailable`		Continue your flow as allow.

See Errors for the error format.

Introduction

Popular APIs

Risk Platform

APIs to verify

APIs to Look up

APIs to create

Integrations

Request body

Response

Compatibility fields

Errors

​Request body

​Response

​Compatibility fields

​Errors

Request body

Response

Compatibility fields

Errors