Check Endpoint

Run fraud checks on emails, phones, and devices.

POST /check

Perform a fraud check and get a risk score.

Request

curl -X POST https://api.simplr-ai.com/v1/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_xxxxx" \
  -d '{
    "email": "user@example.com",
    "event_type": "signup",
    "event_id": "signup_123",
    "metadata": { "campaign": "launch" }
  }'

Parameters

Parameter	Type	Required	Description
email	string	No*	Email address to check
phone	string	No*	Phone number (E.164 format)
device	object	No*	Device fingerprint and platform signals from an SDK
behavior	object	No	Behavioral signals from SDK
event_type	string	No	Context such as signup, login, checkout, payment, kyc, withdrawal, or transfer
event_id	string	No	Your idempotency/correlation identifier (maximum 128 characters)
metadata	object	No	Additional JSON context

*At least one of email, phone, or device is required. The service derives the client IP from trusted forwarding/request headers; do not put ip_address in the JSON body.

Response

{
  "success": true,
  "message": "Check completed",
  "content": {
    "check_id": "chk_abc123xyz",
    "email": "user@example.com",
    "risk_score": 35,
    "risk_level": "medium",
    "signals": {
      "domain_age_score": 0,
      "mx_score": 0,
      "disposable_score": 0,
      "velocity_score": 10
    },
    "tier": "standard",
    "credits_used": 2,
    "is_sandbox": false
  }
}

Risk Levels

Score	Level	Recommendation
0-24	low	allow
25-49	medium	allow
50-69	high	challenge
70-100	critical	block

Error Responses

400 Bad Request

{
  "success": false,
  "message": "At least one of 'phone', 'email', or 'device' is required"
}

401 Unauthorized

{
  "success": false,
  "message": "Invalid API key"
}

429 Rate Limited

{
  "success": false,
  "message": "API rate limit exceeded. Please upgrade your plan for higher limits.",
  "content": {
    "retry_after": 60
  }
}

GET /check/{id}

Retrieve a previous check result.

Request

curl https://api.simplr-ai.com/v1/check/chk_abc123xyz \
  -H "X-API-Key: sk_live_xxxxx"

Response

Same as POST /check response.

GET /check/sandbox

Returns the current catalogue of predictable sandbox email addresses, phone numbers, event types, and request examples. Use those values with a test key on POST /check; test-key usage is recorded but consumes no credits.

Request

Send a test or live secret key in X-API-Key. This read does not run a check.

Response

{
  "success": true,
  "message": "Sandbox test data",
  "content": {
    "phone_numbers": [],
    "emails": [],
    "event_types": {},
    "examples": {}
  }
}