Dispatch real-time events

POST

watch

event

Dispatch events

curl --request POST \
  --url https://api.prelude.dev/v2/watch/event \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "events": [
    {
      "target": {
        "value": "<string>"
      },
      "label": "<string>"
    }
  ]
}
'

import requests

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

payload = { "events": [
        {
            "target": { "value": "<string>" },
            "label": "<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({events: [{target: {value: '<string>'}, label: '<string>'}]})
};

fetch('https://api.prelude.dev/v2/watch/event', 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/event",
  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([
    'events' => [
        [
                'target' => [
                                'value' => '<string>'
                ],
                'label' => '<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/event"

	payload := strings.NewReader("{\n  \"events\": [\n    {\n      \"target\": {\n        \"value\": \"<string>\"\n      },\n      \"label\": \"<string>\"\n    }\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/event")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"events\": [\n    {\n      \"target\": {\n        \"value\": \"<string>\"\n      },\n      \"label\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"events\": [\n    {\n      \"target\": {\n        \"value\": \"<string>\"\n      },\n      \"label\": \"<string>\"\n    }\n  ]\n}"

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

{
  "status": "success",
  "request_id": "<string>"
}

{
  "code": "invalid_events",
  "message": "The provided events are invalid. See `details` field for more information.",
  "type": "bad_request",
  "request_id": "3d19215e-2991-4a05-a41a-527314e6ff6a"
}

Use this endpoint to send custom fraud signals from your application: user actions you label yourself (for example account.banned, payment.chargeback) together with a confidence level. Events let you capture fraud patterns that are specific to your product. They are weighted when Prelude scores traffic alongside network and phone intelligence. Events are not the same as Feedback: feedback is optional and only describes steps in your own phone verification funnel. Many customers use Events alone (plus Predict at gates) without Feedback. Use both when you operate your own verification flow and also emit product fraud labels.

Confidence

Each event must include a confidence value: how much you trust that the label truly reflects fraud or abuse for that user. Allowed values, from lowest to highest trust in the signal, are:

Value	Typical use
`minimum`	Weak or noisy signal — use when you are unsure the event indicates fraud
`low`	Some suspicion, not enough to act alone
`neutral`	Informational; no strong lean either way
`high`	Strong product-side signal of abuse
`maximum`	Definitive action in your systems (for example a confirmed `account.banned`)

Prelude weights events when scoring a phone number: higher confidence increases influence; minimum signals contribute lightly and mainly help filter traffic you already distrust. See Introduction — Event confidence for the full pipeline behavior.

Authorizations

Authorization

string

header

required

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

Body

application/json

events

object[]

required

A list of events to dispatch. A maximum of 100 events can be sent in a single request.

Maximum array length: 100

Show child attributes

Response

status

enum<string>

required

The status of the events dispatch.

Available options:

success

Example:

"success"

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"

Send feedbacksOptional. Report verification-funnel steps (verification.started, verification.completed) when you run phone verification outside Prelude Verify. Feeds Watch abuse-rate counters for your own flow. Call Predict on the same target before verification.started and reuse metadata.correlation_id so auth-start counters receive predict signals; without a linked predict, only attempt-rate counters update on started. Not required if you only use Events and/or Predict, or if Verify already handles verification for that traffic.

Dispatch events

curl --request POST \
  --url https://api.prelude.dev/v2/watch/event \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "events": [
    {
      "target": {
        "value": "<string>"
      },
      "label": "<string>"
    }
  ]
}
'

import requests

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

payload = { "events": [
        {
            "target": { "value": "<string>" },
            "label": "<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({events: [{target: {value: '<string>'}, label: '<string>'}]})
};

fetch('https://api.prelude.dev/v2/watch/event', 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/event",
  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([
    'events' => [
        [
                'target' => [
                                'value' => '<string>'
                ],
                'label' => '<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/event"

	payload := strings.NewReader("{\n  \"events\": [\n    {\n      \"target\": {\n        \"value\": \"<string>\"\n      },\n      \"label\": \"<string>\"\n    }\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/event")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"events\": [\n    {\n      \"target\": {\n        \"value\": \"<string>\"\n      },\n      \"label\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"events\": [\n    {\n      \"target\": {\n        \"value\": \"<string>\"\n      },\n      \"label\": \"<string>\"\n    }\n  ]\n}"

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

{
  "status": "success",
  "request_id": "<string>"
}

{
  "code": "invalid_events",
  "message": "The provided events are invalid. See `details` field for more information.",
  "type": "bad_request",
  "request_id": "3d19215e-2991-4a05-a41a-527314e6ff6a"
}

​Confidence

Authorizations

Body

Response

Confidence