Documentation

Integrate in under an hour.

REST API. Webhook events. Score response with contributing factors. No SDK required to get started.

Quickstart

Get your first score in three steps.

You need an API key. Request access via the contact form and we will issue a sandbox key within one business day. Sandbox keys are free and give you access to the full scoring API in test mode, including the synthetic transaction generator.

Step 1: Get your API key

Sandbox keys are prefixed fpls_test_. Live keys are prefixed fpls_live_. Keep your live key secret. Never commit it to version control.

Step 2: Send your first score request

curl node.js python
curl -X POST https://api.fraudpulsar.com/v1/score \
-H "Authorization: Bearer fpls_test_8f2e14..." \
-H "Content-Type: application/json" \
-d '{'
"account_id": "acc_8f2e14b9",
"transaction": {
"amount_usd": 142.00,
"merchant_category": "5411",
"timestamp_ms": 1751630412843
},
"device": {
"fingerprint": "fp_a3c7...",
"ip": "198.51.100.42"
}
'}'

Step 3: Read the response

A successful response returns HTTP 200 with a JSON body. The risk_score field is the primary signal. Read contributing factors to understand what drove the score.

response
{
"risk_score": 0.04,
"confidence": 0.91,
"latency_ms": 6,
"decision": "pass",
"factors": [
"amount_within_account_norm",
"known_device",
"typical_merchant_category"
]
}
Endpoints
POST /v1/score GET /v1/account/:id/history Webhook events
API Reference

POST /v1/score

Score a single transaction event against the per-account behavioral model. Returns synchronously in the authorization path. p50 latency under 8ms, p99 under 25ms, measured on pilot infrastructure.

POST https://api.fraudpulsar.com/v1/score

Request fields

field type required description
account_idstringyesYour internal account identifier. Consistent per user.
transaction.amount_usdfloatyesTransaction amount in USD. Fractions of a cent accepted.
transaction.merchant_categorystringyesISO 18245 MCC code (4 digits).
transaction.timestamp_msintegeryesUnix timestamp in milliseconds at event occurrence.
device.fingerprintstringrecommendedYour device fingerprint token. Improves device consistency signals.
device.ipstringrecommendedIPv4 or IPv6 address of originating request.

Response fields

field type description
risk_scorefloat0-1 score. Higher = higher risk. Set your own thresholds.
confidencefloat0-1 model confidence. Low confidence on new accounts with few events.
latency_msintegerServer-side processing time in milliseconds.
decisionstringSuggested decision: pass, review, or block. Based on default thresholds. Override with your own.
factorsstring[]Array of human-readable factor strings explaining the score.
model_age_daysintegerDays since this account's model was first initialized.

GET /v1/account/:id/history

Retrieve the score history for an account. Useful for building review UI or debugging model behavior.

GET https://api.fraudpulsar.com/v1/account/:id/history

Returns an array of up to 200 most recent score events for the account, ordered newest-first. Each entry matches the POST /v1/score response shape plus a resolved timestamp.

Webhook event schema

When a post-authorization risk signal changes, Fraudpulsar fires a POST to your configured webhook endpoint. Triggers include: chargeback filed, confirmed fraud on a linked account, or a behavioral cluster pattern identified across accounts. The event body:

webhook event
{
"event": "risk.signal.updated",
"account_id": "acc_8f2e14b9",
"signal_type": "chargeback_filed",
"updated_risk_score": 0.87,
"timestamp_ms": 1751630412843
}
Libraries
Node.js Python
SDKs and libraries

Node.js client

A lightweight Node.js wrapper is in beta. It handles authentication headers, request body formatting, error parsing, and retry logic on transient failures. Install via npm:

npm
npm install @fraudpulsar/client // beta

The REST API is always available and does not require the client library. All features are accessible directly via HTTP with any language.

Python client

A Python client is in planning. In the meantime, the REST API works directly with the requests or httpx libraries. If Python client timeline affects your integration planning, email us and we will give you a realistic estimate.

The raw REST API is always the primary interface. All features, including async webhook subscriptions, are accessible directly via HTTP from any language or runtime.