Quickstart

Five minutes from nothing to a scored event.

1. Get an API key

Sign in to the dashboard and open API keys for your project. Create a secret key (ak_...).

A tenant has live and sandbox projects, so there are two kinds of key:

Key	Project	Use
ak_sandbox_...	sandbox	Integration and testing. Rules, keys, thresholds and cases are separate from live; account identity is shared across the tenant's projects.
ak_live_...	live	Production traffic.

Start with a sandbox key. A key is shown once; store it as a secret.

2. Send an event

curl

curl -X POST https://api-test.defraudo.com/v1/events \
  -H "Authorization: Bearer $DEFRAUDO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "0b7b1c2e-5d0a-4f6e-9c1d-2a3b4c5d6e7f",
    "event_type": "payment",
    "external_account_id": "user-1001",
    "context": { "ip": "203.0.113.7", "user_agent": "Mozilla/5.0" },
    "user": { "email": "jane@example.com" },
    "payment": { "amount_cents": 4999, "currency": "EUR", "bin": "411111", "last4": "1234" }
  }'

Node.js

import crypto from 'node:crypto';

const response = await fetch('https://api-test.defraudo.com/v1/events', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.DEFRAUDO_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    event_id: crypto.randomUUID(),
    event_type: 'payment',
    external_account_id: 'user-1001',
    context: { ip: '203.0.113.7', user_agent: 'Mozilla/5.0' },
    user: { email: 'jane@example.com' },
    payment: { amount_cents: 4999, currency: 'EUR', bin: '411111', last4: '1234' }
  })
});

const { data } = await response.json();
console.log(data.decision, data.risk_score);

Python

import os
import uuid

import requests

response = requests.post(
    'https://api-test.defraudo.com/v1/events',
    headers={'Authorization': f"Bearer {os.environ['DEFRAUDO_KEY']}"},
    json={
        'event_id': str(uuid.uuid4()),
        'event_type': 'payment',
        'external_account_id': 'user-1001',
        'context': {'ip': '203.0.113.7', 'user_agent': 'Mozilla/5.0'},
        'user': {'email': 'jane@example.com'},
        'payment': {'amount_cents': 4999, 'currency': 'EUR', 'bin': '411111', 'last4': '1234'},
    },
    timeout=5,
)

data = response.json()['data']
print(data['decision'], data['risk_score'])

PHP

<?php

$bytes = random_bytes(16);
$bytes[6] = chr(ord($bytes[6]) & 0x0f | 0x40);
$bytes[8] = chr(ord($bytes[8]) & 0x3f | 0x80);

$payload = [
    'event_id' => vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($bytes), 4)),
    'event_type' => 'payment',
    'external_account_id' => 'user-1001',
    'context' => ['ip' => '203.0.113.7', 'user_agent' => 'Mozilla/5.0'],
    'user' => ['email' => 'jane@example.com'],
    'payment' => ['amount_cents' => 4999, 'currency' => 'EUR', 'bin' => '411111', 'last4' => '1234'],
];

$ch = curl_init('https://api-test.defraudo.com/v1/events');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 5,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('DEFRAUDO_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$data = json_decode(curl_exec($ch), true)['data'];
echo $data['decision'], ' ', $data['risk_score'], PHP_EOL;

event_id is a UUID you generate. Resending the same body is safe and does not score the event twice.

3. Read the decision

{
  "status": 1,
  "data": {
    "event_id": "0b7b1c2e-5d0a-4f6e-9c1d-2a3b4c5d6e7f",
    "risk_score": 0,
    "max_possible": 935,
    "decision": "allow",
    "breakdown": [],
    "flags": [],
    "trust_override": false,
    "hard_block_hit": false,
    "latency_ms": 3,
    "account_public_id": "acc_01k6hs3ybb7xhrm2b5ce6jw7mt",
    "enrichment_status": { "mx-check": "ok", "disposable-email": "ok", "maxmind": "ok" },
    "environment": "sandbox"
  },
  "errors": []
}

Act on data.decision: allow, review (hold the action; a case is open for an analyst) or block. breakdown lists the active rules that were evaluated (shadow rules are omitted; a trust or hard-block verdict returns only the winning rule). actions, degraded and account_public_id appear only when they have a value. The values above are illustrative; real scores depend on the project's rules.

4. Read the score later

Any scored event can be fetched by its event_id:

curl https://api-test.defraudo.com/v1/scores/0b7b1c2e-5d0a-4f6e-9c1d-2a3b4c5d6e7f \
  -H "Authorization: Bearer $DEFRAUDO_KEY"

The response has "status": "pending" while an async event is still queued and "status": "scored" with the score, decision and breakdown afterwards. It does not repeat degraded, latency_ms or account_public_id. An unknown event_id returns 404.

Next

• Add the device fingerprint for much stronger signals.
• Set up webhooks to receive decisions and case outcomes.
• Browse every field in the API reference.