API Reference

Predict the outcome of a verification

At signup, score the user’s phone number or email address (target) as legitimate or suspicious. Scoring-only — does not update counters by itself. When using Feedback, call predict before verification.started on the same target (and correlation_id when used) so feedback can warm Watch auth-start counters. Use Events for product fraud labels; use Feedback only if you run your own phone verification funnel outside Prelude Verify.

POST

watch

predict

Predict outcome

curl --request POST \
  --url https://api.prelude.dev/v2/watch/predict \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "target": {
    "value": "+30123456789"
  },
  "signals": {
    "ip": "203.0.113.123",
    "device_id": "8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2",
    "device_platform": "ios",
    "device_model": "iPhone17,2",
    "os_version": "18.0.1",
    "app_version": "1.2.34",
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1",
    "ja4_fingerprint": "t13d1516h2_8daaf6152771_e5627efa2ab1",
    "is_trusted_user": false,
    "existing_user": false
  },
  "dispatch_id": "123e4567-e89b-12d3-a456-426614174000",
  "metadata": {
    "correlation_id": "<string>"
  }
}
'

import requests

url = "https://api.prelude.dev/v2/watch/predict"

payload = {
    "target": { "value": "+30123456789" },
    "signals": {
        "ip": "203.0.113.123",
        "device_id": "8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2",
        "device_platform": "ios",
        "device_model": "iPhone17,2",
        "os_version": "18.0.1",
        "app_version": "1.2.34",
        "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1",
        "ja4_fingerprint": "t13d1516h2_8daaf6152771_e5627efa2ab1",
        "is_trusted_user": False,
        "existing_user": False
    },
    "dispatch_id": "123e4567-e89b-12d3-a456-426614174000",
    "metadata": { "correlation_id": "<string>" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    target: {value: '+30123456789'},
    signals: {
      ip: '203.0.113.123',
      device_id: '8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2',
      device_platform: 'ios',
      device_model: 'iPhone17,2',
      os_version: '18.0.1',
      app_version: '1.2.34',
      user_agent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1',
      ja4_fingerprint: 't13d1516h2_8daaf6152771_e5627efa2ab1',
      is_trusted_user: false,
      existing_user: false
    },
    dispatch_id: '123e4567-e89b-12d3-a456-426614174000',
    metadata: {correlation_id: '<string>'}
  })
};

fetch('https://api.prelude.dev/v2/watch/predict', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.prelude.dev/v2/watch/predict",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'target' => [
        'value' => '+30123456789'
    ],
    'signals' => [
        'ip' => '203.0.113.123',
        'device_id' => '8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2',
        'device_platform' => 'ios',
        'device_model' => 'iPhone17,2',
        'os_version' => '18.0.1',
        'app_version' => '1.2.34',
        'user_agent' => 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1',
        'ja4_fingerprint' => 't13d1516h2_8daaf6152771_e5627efa2ab1',
        'is_trusted_user' => false,
        'existing_user' => false
    ],
    'dispatch_id' => '123e4567-e89b-12d3-a456-426614174000',
    'metadata' => [
        'correlation_id' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prelude.dev/v2/watch/predict"

	payload := strings.NewReader("{\n  \"target\": {\n    \"value\": \"+30123456789\"\n  },\n  \"signals\": {\n    \"ip\": \"203.0.113.123\",\n    \"device_id\": \"8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2\",\n    \"device_platform\": \"ios\",\n    \"device_model\": \"iPhone17,2\",\n    \"os_version\": \"18.0.1\",\n    \"app_version\": \"1.2.34\",\n    \"user_agent\": \"Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1\",\n    \"ja4_fingerprint\": \"t13d1516h2_8daaf6152771_e5627efa2ab1\",\n    \"is_trusted_user\": false,\n    \"existing_user\": false\n  },\n  \"dispatch_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"metadata\": {\n    \"correlation_id\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.prelude.dev/v2/watch/predict")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"target\": {\n    \"value\": \"+30123456789\"\n  },\n  \"signals\": {\n    \"ip\": \"203.0.113.123\",\n    \"device_id\": \"8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2\",\n    \"device_platform\": \"ios\",\n    \"device_model\": \"iPhone17,2\",\n    \"os_version\": \"18.0.1\",\n    \"app_version\": \"1.2.34\",\n    \"user_agent\": \"Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1\",\n    \"ja4_fingerprint\": \"t13d1516h2_8daaf6152771_e5627efa2ab1\",\n    \"is_trusted_user\": false,\n    \"existing_user\": false\n  },\n  \"dispatch_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"metadata\": {\n    \"correlation_id\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.prelude.dev/v2/watch/predict")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"target\": {\n    \"value\": \"+30123456789\"\n  },\n  \"signals\": {\n    \"ip\": \"203.0.113.123\",\n    \"device_id\": \"8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2\",\n    \"device_platform\": \"ios\",\n    \"device_model\": \"iPhone17,2\",\n    \"os_version\": \"18.0.1\",\n    \"app_version\": \"1.2.34\",\n    \"user_agent\": \"Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1\",\n    \"ja4_fingerprint\": \"t13d1516h2_8daaf6152771_e5627efa2ab1\",\n    \"is_trusted_user\": false,\n    \"existing_user\": false\n  },\n  \"dispatch_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"metadata\": {\n    \"correlation_id\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "prd_01jc0t6fwwfgfsq1md24mhyztj",
  "prediction": "legitimate",
  "request_id": "3d19215e-2991-4a05-a41a-527314e6ff6a",
  "risk_factors": [
    "proxy_network",
    "fraud_database"
  ]
}

{
  "code": "invalid_phone_number",
  "message": "The provided phone number is invalid. Provide a valid E.164 phone number.",
  "type": "bad_request",
  "request_id": "3d19215e-2991-4a05-a41a-527314e6ff6a",
  "param": "phone_number"
}

Call Predict at signup for a real-time legitimate or suspicious outcome on the identifier the user provides. Set target.type to phone_number or email_address with the corresponding value. Predict is scoring-only. It evaluates forwarded signals (IP, device, JA4, and more) and does not imply that you sent a message, started a verification step, or triggered any other side effect. It does not update long-lived abuse counters by itself. If you use Feedback for your own verification funnel, call Predict before verification.started on the same target and reuse metadata.correlation_id on both requests. Prelude links the feedback to the stored prediction so auth-start counters in the Watch pool receive those signals. Feedback alone without a prior predict only updates attempt-rate counters.

If you need…	Use
Product-specific fraud labels (`account.banned`, …)	Events
Counters for your own verification funnel (not Prelude Verify)	Feedback, after Predict on the same target

You can use Predict without Events or Feedback, or combine all three. See Introduction: How the pieces fit together.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

target

object

required

The signup identifier to score — a phone number or email address.

Show child attributes

signals

object

The signals used for anti-fraud. For more details, refer to Signals.

Show child attributes

dispatch_id

string

The identifier of the dispatch that came from the front-end SDK.

Required string length: 36

Example:

"123e4567-e89b-12d3-a456-426614174000"

metadata

object

The metadata for this prediction.

Show child attributes

Response

string

required

The prediction identifier.

Example:

"prd_01jc0t6fwwfgfsq1md24mhyztj"

prediction

enum<string>

required

The prediction outcome.

Available options:

legitimate,

suspicious

request_id

string

required

A string that identifies this specific request. Report it back to us to help us diagnose your issues.

Example:

"3d19215e-2991-4a05-a41a-527314e6ff6a"

risk_factors

enum<string>[]

The risk factors that contributed to the suspicious prediction. Only present when prediction is "suspicious" and the anti-fraud system detected specific risk signals.

account_risk_profile - The request matches a risk profile derived from the outcomes reported on your own account.
automation_signature - The request appears to come from an automated client rather than a person.
carrier_not_permitted - The destination carrier is one this account does not accept traffic for.
client_fingerprint_mismatch - The client does not appear to be the platform it identifies itself as.
custom_policy - A rule configured for your account matched this request.
device_emulator - The request appears to come from an emulator rather than a physical device.
device_not_permitted - The device platform is one your account blocks.
device_reuse - One device is driving verifications for an unusual number of phone numbers.
expired_signals - The SDK signals were collected too long before the request to still attest to it.
fraud_database - The phone number is flagged in one or more of the fraud databases Prelude consults.
invalid_signature - The SDK signature did not verify, so the request cannot be attributed to the device it claims to come from.
ip_concentration - The request shares its origin with an unusual volume of other verifications.
ip_reputation - The originating IP address is not trusted.
location_mismatch - The network location and the phone number's country are inconsistent.
missing_signals - The verification expected Prelude SDK signals and none arrived.
number_range_abuse - The phone number belongs to a range currently associated with abuse.
poor_conversion_history - Traffic resembling this request rarely completes a verification.
proxy_network - The request did not arrive over the subscriber's own access network.
repeated_attempts - The phone number exceeded the allowed number of verification attempts in a short period.
temporary_phone_number - The phone number belongs to a disposable or short-lived numbering service.

Available options:

account_risk_profile,

automation_signature,

carrier_not_permitted,

client_fingerprint_mismatch,

custom_policy,

device_emulator,

device_not_permitted,

device_reuse,

expired_signals,

fraud_database,

invalid_signature,

ip_concentration,

ip_reputation,

location_mismatch,

missing_signals,

number_range_abuse,

poor_conversion_history,

proxy_network,

repeated_attempts,

temporary_phone_number

Example:

["proxy_network", "fraud_database"]

Predict outcome

curl --request POST \
  --url https://api.prelude.dev/v2/watch/predict \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "target": {
    "value": "+30123456789"
  },
  "signals": {
    "ip": "203.0.113.123",
    "device_id": "8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2",
    "device_platform": "ios",
    "device_model": "iPhone17,2",
    "os_version": "18.0.1",
    "app_version": "1.2.34",
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1",
    "ja4_fingerprint": "t13d1516h2_8daaf6152771_e5627efa2ab1",
    "is_trusted_user": false,
    "existing_user": false
  },
  "dispatch_id": "123e4567-e89b-12d3-a456-426614174000",
  "metadata": {
    "correlation_id": "<string>"
  }
}
'

import requests

url = "https://api.prelude.dev/v2/watch/predict"

payload = {
    "target": { "value": "+30123456789" },
    "signals": {
        "ip": "203.0.113.123",
        "device_id": "8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2",
        "device_platform": "ios",
        "device_model": "iPhone17,2",
        "os_version": "18.0.1",
        "app_version": "1.2.34",
        "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1",
        "ja4_fingerprint": "t13d1516h2_8daaf6152771_e5627efa2ab1",
        "is_trusted_user": False,
        "existing_user": False
    },
    "dispatch_id": "123e4567-e89b-12d3-a456-426614174000",
    "metadata": { "correlation_id": "<string>" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    target: {value: '+30123456789'},
    signals: {
      ip: '203.0.113.123',
      device_id: '8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2',
      device_platform: 'ios',
      device_model: 'iPhone17,2',
      os_version: '18.0.1',
      app_version: '1.2.34',
      user_agent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1',
      ja4_fingerprint: 't13d1516h2_8daaf6152771_e5627efa2ab1',
      is_trusted_user: false,
      existing_user: false
    },
    dispatch_id: '123e4567-e89b-12d3-a456-426614174000',
    metadata: {correlation_id: '<string>'}
  })
};

fetch('https://api.prelude.dev/v2/watch/predict', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.prelude.dev/v2/watch/predict",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'target' => [
        'value' => '+30123456789'
    ],
    'signals' => [
        'ip' => '203.0.113.123',
        'device_id' => '8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2',
        'device_platform' => 'ios',
        'device_model' => 'iPhone17,2',
        'os_version' => '18.0.1',
        'app_version' => '1.2.34',
        'user_agent' => 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1',
        'ja4_fingerprint' => 't13d1516h2_8daaf6152771_e5627efa2ab1',
        'is_trusted_user' => false,
        'existing_user' => false
    ],
    'dispatch_id' => '123e4567-e89b-12d3-a456-426614174000',
    'metadata' => [
        'correlation_id' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prelude.dev/v2/watch/predict"

	payload := strings.NewReader("{\n  \"target\": {\n    \"value\": \"+30123456789\"\n  },\n  \"signals\": {\n    \"ip\": \"203.0.113.123\",\n    \"device_id\": \"8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2\",\n    \"device_platform\": \"ios\",\n    \"device_model\": \"iPhone17,2\",\n    \"os_version\": \"18.0.1\",\n    \"app_version\": \"1.2.34\",\n    \"user_agent\": \"Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1\",\n    \"ja4_fingerprint\": \"t13d1516h2_8daaf6152771_e5627efa2ab1\",\n    \"is_trusted_user\": false,\n    \"existing_user\": false\n  },\n  \"dispatch_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"metadata\": {\n    \"correlation_id\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.prelude.dev/v2/watch/predict")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"target\": {\n    \"value\": \"+30123456789\"\n  },\n  \"signals\": {\n    \"ip\": \"203.0.113.123\",\n    \"device_id\": \"8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2\",\n    \"device_platform\": \"ios\",\n    \"device_model\": \"iPhone17,2\",\n    \"os_version\": \"18.0.1\",\n    \"app_version\": \"1.2.34\",\n    \"user_agent\": \"Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1\",\n    \"ja4_fingerprint\": \"t13d1516h2_8daaf6152771_e5627efa2ab1\",\n    \"is_trusted_user\": false,\n    \"existing_user\": false\n  },\n  \"dispatch_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"metadata\": {\n    \"correlation_id\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.prelude.dev/v2/watch/predict")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"target\": {\n    \"value\": \"+30123456789\"\n  },\n  \"signals\": {\n    \"ip\": \"203.0.113.123\",\n    \"device_id\": \"8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2\",\n    \"device_platform\": \"ios\",\n    \"device_model\": \"iPhone17,2\",\n    \"os_version\": \"18.0.1\",\n    \"app_version\": \"1.2.34\",\n    \"user_agent\": \"Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1\",\n    \"ja4_fingerprint\": \"t13d1516h2_8daaf6152771_e5627efa2ab1\",\n    \"is_trusted_user\": false,\n    \"existing_user\": false\n  },\n  \"dispatch_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"metadata\": {\n    \"correlation_id\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "prd_01jc0t6fwwfgfsq1md24mhyztj",
  "prediction": "legitimate",
  "request_id": "3d19215e-2991-4a05-a41a-527314e6ff6a",
  "risk_factors": [
    "proxy_network",
    "fraud_database"
  ]
}

{
  "code": "invalid_phone_number",
  "message": "The provided phone number is invalid. Provide a valid E.164 phone number.",
  "type": "bad_request",
  "request_id": "3d19215e-2991-4a05-a41a-527314e6ff6a",
  "param": "phone_number"
}

Documentation

API Reference

Management API

Predict the outcome of a verification

Authorizations

Body

Response