Skip to main content
Watch keeps fraudsters out and lets real users in. It analyzes dozens of digital signals in real time — number portability history, residential proxies, disposable numbers, data breach history, IP and device discrepancies — to block suspicious accounts before KYC and keep your growth secure from the start.
To enable the Watch API on your account, contact us
At signup, pass the user’s identifier in target as a phone number or email address (phone_number or email_address).

​
Usage

Watch exposes three endpoints. You can use one, two, or all three depending on your product — there is no requirement to run phone verification or SMS through Prelude.

​
Predict

Call Predict at signup when you want a real-time risk read on the identifier the user provides — a phone number or email address — before you let the account proceed. Predict is scoring-only: it returns legitimate or suspicious from Prelude’s rules and the signals you pass (IP, device, JA4, etc.). It does not record that a message was sent, that a user completed a challenge, or that any side effect happened in your stack. It also does not by itself update long-lived abuse counters. When you use Feedback for your own verification funnel, call Predict first on the same target, then send verification.started with the same metadata.correlation_id if you use one. That links feedback to the stored prediction so Watch auth-start counters (IP, prefix, JA4, carrier, and related signals) are updated. Feedback without a prior predict still updates attempt-rate counters only.

​
Events

See Dispatch events. Use Events to stream custom fraud signals from your product: labels you define (such as account.banned or payment.chargeback) and a confidence level (minimum through maximum). Prelude weights these when scoring traffic. Many integrations rely primarily on Events (and optionally Predict at key gates), without sending Feedback at all. Events describe what happened in your product; they are not tied to SMS or to Prelude Verify.

​
Feedback

See Send feedbacks. Use Feedback only if you run your own phone verification flow (OTP, flash call, etc.) outside Prelude Verify and want Prelude to track attempt and success rates for abuse detection — the same class of counters Verify maintains for its own customers. Send (after Predict on the same target when you want full counter updates):
  • verification.started when the user begins verification (challenge sent or started) — requires a linked predict for auth-level counters
  • verification.completed when verification succeeds
If verification for a number already goes through Prelude Verify, you usually do not need Feedback for that traffic. If you never verify by phone and only use Events, you do not need Feedback.

​
How the pieces fit together

Events-focused — Dispatch events as abuse happens; optionally call Predict before high-risk steps. No Feedback required.
Own verification funnel — Add Feedback when verification starts and completes on your stack, plus Predict and Events as needed.
Prelude Verify for OTP — Verify feeds shared verification counters. Use Watch for Predict and/or Events; send Feedback only for numbers that never touch Verify.

​
Event confidence

Each event you dispatch must carry a confidence value. Confidence expresses how much this event tells us to trust the end-user’s legitimacy — not how certain you are that the event occurred. Possible values, in increasing order of trust, are minimum, low, neutral, high, and maximum. Labels are freeform: the label names what happened, and confidence says how strongly that event speaks to the user’s trustworthiness.
  • minimum — a very low-trust signal, i.e. an event tied to a user you trust the least to be legitimate (e.g. a payment.chargeback).
  • maximum — a very high-trust signal, i.e. an event tied to a highly trustworthy user (e.g. a confirmed 3DS payment).
  • neutral — no strong signal either way.
Prelude uses these levels to weight your signals when scoring traffic. The end goal of the pipeline is to filter out end-users tied to low-confidence events — those you trust the least to be legitimate — while preserving the experience for users tied to high-confidence events.

​
API

The Prelude v2 API is a REST API and uses standard HTTP features and statuses. The current URL is https://api.prelude.dev/v2.

​
Authentication

To perform requests on the API, you need to provide a v2 API key in the Authorization header. You can create an API key in the Dashboard, under the API Keys section of the settings.
Example request

​
Errors

Prelude uses conventional HTTP statuses to indicate the success or failure of a request:
  • Codes in the 2xx range indicate success.
  • Codes in the 4xx range indicate an error that failed given the information provided (e.g. required parameter was omitted, authentication failed or a rate limit was reached).
  • Codes in the 5xx range indicate an error with Prelude’s servers (these are rare).
The Prelude API returns errors using a JSON object in the response body with a machine-readable code and a human-readable message and a param field. See Errors for more details as well as a list of all possible error codes.

​
Backend SDKs

Integrate effortlessly with Prelude using our Backend SDKs for your platform of choice.

Node.js

Learn how to integrate the Node.js SDK into your application.

Go

Learn how to integrate the Go SDK into your application.

Python

Learn how to integrate the Python SDK into your application.

Kotlin/Java

Learn how to integrate the Kotlin/Java SDK into your application.

Ruby

Learn how to integrate the Ruby SDK into your application.

PHP

Learn how to integrate the PHP SDK into your application.

C#

Learn how to integrate the C# SDK into your application.

​
Frontend SDKs

Explore how you can enhance your fraud detection process with our Frontend SDKs.

Web SDK

Learn how to integrate the Web SDK into your application.

Android SDK

Learn how to integrate the Android SDK into your application.

iOS SDK

Learn how to integrate the iOS SDK into your application.

React Native SDK

Learn how to integrate the React Native SDK into your application.

Flutter SDK

Learn how to integrate the Flutter SDK into your application.