Score API

The main endpoint. Send what you know about a visitor; get back a risk verdict.

POST /api/v1/score

Request fields

Field		Description
`email`	optional	Visitor's email address.
`ip`	optional	Visitor's IP address.
`user_agent`	optional	Visitor's browser user agent string.
`identifier`	optional	Any stable identifier you use for this visitor/lead (your own ID, phone, etc.).
`source` / `subsource`	optional	Your own traffic-source labels, for reporting only. Never affects the score.
`custom`	optional	Up to 10 of your own key/value pairs for reporting. See Custom Fields. Never affects the score.
`browser_telemetry`	optional	Only needed if you're collecting it yourself instead of the browser script — see Browser Telemetry.
`revylta_token`	optional	Only used in Signup Page Mode, to attach telemetry staged earlier by the signup script.

Note: at least one of email, ip, or user_agent is required.

Optional header

X-Request-ID A UUID you generate. Echoed back so you can correlate logs. Auto-generated if omitted or invalid.

Example request

curl -X POST "https://revylta.com/api/v1/score" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_SERVER_API_KEY" \
  -d '{
  "email": "jane.doe@example.com",
  "ip": "203.0.113.42",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
  "source": "paid_search",
  "subsource": "brand_campaign",
  "custom": {
    "offer_id": "8842"
  }
}'

const response = await fetch("https://revylta.com/api/v1/score", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-KEY": "YOUR_SERVER_API_KEY"
  },
  body: JSON.stringify({
  "email": "jane.doe@example.com",
  "ip": "203.0.113.42",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
  "source": "paid_search",
  "subsource": "brand_campaign",
  "custom": {
    "offer_id": "8842"
  }
})
});

const result = await response.json();
console.log(result);

import requests

response = requests.post(
    "https://revylta.com/api/v1/score",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "YOUR_SERVER_API_KEY"
    },
    json={
  "email": "jane.doe@example.com",
  "ip": "203.0.113.42",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
  "source": "paid_search",
  "subsource": "brand_campaign",
  "custom": {
    "offer_id": "8842"
  }
}
)

print(response.status_code)
print(response.json())

require "net/http"
require "json"
require "uri"

uri = URI("https://revylta.com/api/v1/score")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == "https"

request = Net::HTTP::Post.new(uri)
request["Content-Type"] = "application/json"
request["X-API-KEY"] = "YOUR_SERVER_API_KEY"
request.body = JSON.generate({
  "email": "jane.doe@example.com",
  "ip": "203.0.113.42",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
  "source": "paid_search",
  "subsource": "brand_campaign",
  "custom": {
    "offer_id": "8842"
  }
})

response = http.request(request)
puts response.code
puts response.body

<?php
$payload = [
    "email" => "jane.doe@example.com",
    "ip" => "203.0.113.42",
    "user_agent" => "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    "source" => "paid_search",
    "subsource" => "brand_campaign",
    "custom" => [
        "offer_id" => "8842"
    ]
];

$ch = curl_init("https://revylta.com/api/v1/score");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "X-API-KEY: YOUR_SERVER_API_KEY"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response . PHP_EOL;

Example response

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "input": {
    "email": "jane.doe@example.com",
    "ip": "203.0.113.42"
  },
  "findings": [
    {
      "key": "chk_1",
      "score": 0,
      "status": "completed",
      "warnings": []
    },
    {
      "key": "chk_2",
      "score": 40,
      "status": "completed",
      "warnings": [
        "Elevated risk signal detected"
      ]
    }
  ],
  "missing_inputs": [],
  "skipped_modules": [],
  "pending_modules": [],
  "summary": {
    "score": 40,
    "risk_level": "medium",
    "block": false,
    "warnings": [
      "Elevated risk signal detected"
    ],
    "validation_passed": true,
    "degraded": false,
    "timeout_modules": [],
    "errored_modules": [],
    "skipped_modules": []
  }
}

Response fields

`request_id`	Echo of the request ID (yours or auto-generated). Save this — you'll need it for telemetry and to fetch background results.
`status`	`completed` or `pending` (a slower check is still running in the background — see Fetch a Result).
`findings`	One entry per check that ran, each with a short reference `key`, a `score`, a `status`, and any human-readable `warnings`. Build against `score`/`status`/`warnings` — the set of checks and their internal names aren't published and can change.
`missing_inputs`	Which of email/ip/user_agent you didn't send — some checks can't run without them.
`skipped_modules`	Checks that didn't run, and why.
`summary.score`	Overall numeric risk score for this request.
`summary.risk_level`	`low`, `medium`, or `high` — the score bucketed against your account's configured bands.
`summary.block`	Our recommendation: `true` means block/reject this lead.
`summary.degraded`	`true` if one or more checks timed out or errored — the score is still valid, just based on partial evidence.