> Source: https://kaidn.io/docs/reference
> Full documentation index: https://kaidn.io/llms.txt

Docs menuAll pages, quickstarts and this page’s contentsDocs
- [Introduction](https://kaidn.io/docs)
- [Quickstarts](https://kaidn.io/docs/quickstart)
- [Core concepts](https://kaidn.io/docs/concepts)
- [API reference](https://kaidn.io/docs/api)
- [API explorer](https://kaidn.io/docs/reference)
- [Guides](https://kaidn.io/docs/guides)
- [Keys & dashboard](https://kaidn.io/docs/keys)
- [Glossary](https://kaidn.io/glossary)

Web
- [JavaScript](https://kaidn.io/docs/quickstart/javascript)
- [React](https://kaidn.io/docs/quickstart/react)
- [Next.js](https://kaidn.io/docs/quickstart/nextjs)
- [Preact](https://kaidn.io/docs/quickstart/preact)
- [Vue](https://kaidn.io/docs/quickstart/vue)
- [Nuxt](https://kaidn.io/docs/quickstart/nuxt)
- [Angular](https://kaidn.io/docs/quickstart/angular)
- [Svelte](https://kaidn.io/docs/quickstart/svelte)

Mobile
- Androidsoon
- iOSsoon
- React Nativesoon
- Fluttersoon

Server
- [Node.js](https://kaidn.io/docs#quickstart)
- [PHP](https://kaidn.io/docs/quickstart/php)
- C#/.NETsoon
- Gosoon
- Javasoon
- [Python](https://kaidn.io/docs/quickstart/python)

On this page
- [Scoring](#scoring)
- [Checks](#checks)
- [Bulk](#bulk)
- [Events](#events)
- [Lists](#lists)
- [Config](#config)
- [Privacy](#privacy)
- [Service](#service)

# API explorer

Every operation on the keyed `/v1` surface, 25 of them across 23 paths, generated from the same OpenAPI document the server publishes. It cannot drift from what the API accepts, because nothing here is written by hand.

For what a verdict means, what each reason code implies and worked examples in your language, read the [API reference](https://kaidn.io/docs/api) instead. This page is the contract; that one is the explanation.

Base URL

https://api.kaidn.io

Auth

x-api-key: YOUR_KEY

Your tenant API key. A `Bearer` token in `Authorization` is also accepted.

Raw document

[/v1/openapi.json](https://api.kaidn.io/v1/openapi.json)

OpenAPI 3.0.3. No key needed. Import it into Postman or generate a client.

## Scoring

Score an event and record its outcome.

post`/v1/score`

### Score an event

The core call. Describe a signup, login, checkout or any other event and get back a score from 0 to 100, a verdict of `allow`, `review` or `block`, and the reasons that produced it. Rules decide the verdict; the AI layer only writes the explanation.

Request body · required
- `event` `string` required min length 1 · max length 64
- `user_id` `string` max length 256
- `ip` `string` max length 45
- `email` `string` max length 320
- `device_id` `string` max length 256
- `device_token` `string` max length 512
- `device` `object` 20 fields `is_headless` `boolean`
- `ua_consistent` `boolean`
- `is_emulated` `boolean`
- `is_noise_injected` `boolean`
- `is_tampered` `boolean`
- `is_context_mismatch` `boolean`
- `is_engine_mismatch` `boolean`
- `is_os_mismatch` `boolean`
- `is_font_standardized` `boolean`
- `antidetect_score` `integer` min 0 · max 100
- `antidetect_confidence` `"low" | "medium" | "high"`
- `is_emulator` `boolean`
- `is_rooted` `boolean`
- `is_cloned` `boolean`
- `is_hooked` `boolean`
- `is_sideloaded` `boolean`
- `is_adb_enabled` `boolean`
- `is_mock_location` `boolean`
- `is_vpn_active` `boolean`
- `is_debuggable` `boolean`

- `timezone` `string` max length 64
- `phone` `string` max length 32
- `phone_country` `string` max length 8
- `event_country` `string` max length 8
- `ip_country` `string` max length 8
- `source` `string` max length 64
- `site` `string` max length 256
- `campaign` `string` max length 256
- `affiliate` `string` max length 256
- `link` `string` max length 512

Responses`200` Success.
- `event_id` `string` required
- `score` `number` required
- `verdict` `"allow" | "review" | "block"` required
- `reasons` `string[]` required
- `reason_text` `string` required
- `checks` `object[]` required 6 fields `check` `string` required
- `key` `string`
- `weight` `number` required
- `reason` `string` required
- `message` `string` required
- `evidence` `object`

- `device` `object` 26 fields `id` `string`
- `resolved_id` `string`
- `resolution` `"deterministic" | "probabilistic"`
- `resolution_rung` `integer`
- `collision_risk` `number`
- `risk_measured` `boolean`
- `token_rejected` `"malformed" | "bad_signature" | "expired"`
- `account_count` `integer`
- `account_count_same_network` `integer`
- `distinct_ips` `integer`
- `unique` `boolean`
- `connection_type` `"datacenter" | "residential"`
- `os` `string | null`
- `browser` `string | null`
- `mobile` `boolean | null`
- `is_headless` `boolean | null`
- `ua_consistent` `boolean | null`
- `is_emulated` `boolean | null`
- `is_noise_injected` `boolean | null`
- `is_tampered` `boolean | null`
- `is_context_mismatch` `boolean | null`
- `is_engine_mismatch` `boolean | null`
- `is_os_mismatch` `boolean | null`
- `timezone` `string | null`
- `ja4` `boolean`
- `ja4_known_tool` `string | null`

- `device_token` `string`
- `identity` `object` 3 fields `email_canonical` `string`
- `email_is_aliased` `boolean`
- `email_alias_tricks` `string[]`

- `warnings` `string[]`

`400` The request body or query string failed validation.
- `error` `string` required

`401` Missing or invalid API key.
- `error` `string` required

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required

`500` Unexpected server error.
- `error` `string` required

operationId postScore

post`/v1/label`

### Record what actually happened

The feedback loop. Tell Kaidn whether an event you scored turned out to be fraud or legitimate, so accuracy can be measured against real outcomes.

Request body · required
- `label` `"fraud" | "chargeback" | "legit"` required
- `event_id` `string` max length 64
- `entities` `object` 3 fields `ip` `string` max length 45
- `email` `string` max length 320
- `device_id` `string` max length 256

- `note` `string` max length 500

Responses`200` Success.

A JSON object whose fields this route does not yet declare in its schema. [The API reference](https://kaidn.io/docs/api#feedback) documents what comes back.

`400` The request body or query string failed validation.
- `error` `string` required What went wrong.

`401` Missing or invalid API key.
- `error` `string` required What went wrong.

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required What went wrong.

operationId postLabel

## Checks

Look up a single email, IP or phone.

post`/v1/check`

### Check any identifier

Pass an email, IP or phone and get its risk back without recording an event.

Request body · required
- `email` `string` max length 320
- `ip` `string` max length 45

Responses`200` Success.

A JSON object whose fields this route does not yet declare in its schema. [The API reference](https://kaidn.io/docs/api#services) documents what comes back.

`400` The request body or query string failed validation.
- `error` `string` required What went wrong.

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required What went wrong.

operationId postCheck

post`/v1/check/email`

### Check an email address

Disposable-domain, MX and address-integrity checks for one address.

Request body · required
- `email` `string` required min length 3 · max length 320

Responses`200` Success.
- `email` `object` 12 fields `fraud_score` `number` required
- `is_disposable` `boolean`
- `mx_valid` `boolean`
- `catch_all` `boolean`
- `looks_gibberish` `boolean`
- `has_plus_tag` `boolean`
- `canonical` `string | null`
- `is_aliased` `boolean`
- `alias_tricks` `string[]`
- `is_malformed` `boolean`
- `reject_reason` `string | null`
- `recent_abuse` `boolean`

- `reputation` `object` 4 fields `recent_abuse` `boolean`
- `network_risk` `number`
- `network_operators` `integer`
- `honeypot_hits` `integer`

- `summary` `string`

`400` The request body or query string failed validation.
- `error` `string` required

`401` Missing or invalid API key.
- `error` `string` required

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required

`500` Unexpected server error.
- `error` `string` required

operationId postCheckEmail

post`/v1/check/ip`

### Check an IP address

Datacenter, proxy and ASN classification for one address.

Request body · required
- `ip` `string` required min length 3 · max length 45

Responses`200` Success.
- `ip` `object` 10 fields `fraud_score` `number` required
- `is_datacenter` `boolean`
- `datacenter_provider` `string | null`
- `is_proxy` `boolean`
- `is_tor` `boolean`
- `country` `string | null`
- `city` `string | null`
- `isp` `string | null`
- `asn` `integer | null`
- `recent_abuse` `boolean`

- `reputation` `object` 4 fields `recent_abuse` `boolean`
- `network_risk` `number`
- `network_operators` `integer`
- `honeypot_hits` `integer`

- `summary` `string`

`400` The request body or query string failed validation.
- `error` `string` required

`401` Missing or invalid API key.
- `error` `string` required

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required

`500` Unexpected server error.
- `error` `string` required

operationId postCheckIp

post`/v1/check/phone`

### Check a phone number

Request body · required
- `phone` `string` required min length 3 · max length 32
- `country` `string` min length 2 · max length 2

Responses`200` Success.
- `phone` `object` 8 fields `fraud_score` `number` required
- `valid` `boolean`
- `is_voip` `boolean`
- `is_disposable` `boolean`
- `line_type` `string | null`
- `country` `string | null`
- `carrier` `string | null`
- `recent_abuse` `boolean`

- `reputation` `object` 4 fields `recent_abuse` `boolean`
- `network_risk` `number`
- `network_operators` `integer`
- `honeypot_hits` `integer`

- `summary` `string`

`400` The request body or query string failed validation.
- `error` `string` required

`401` Missing or invalid API key.
- `error` `string` required

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required

`500` Unexpected server error.
- `error` `string` required

operationId postCheckPhone

## Bulk

The same checks over many rows at once.

post`/v1/batch/score`

### Score many events at once

Request body · required
- `rows` `object[]` required min 1 items · max 1000 items17 fields `event` `string` required min length 1 · max length 64
- `user_id` `string` max length 256
- `ip` `string` max length 45
- `email` `string` max length 320
- `device_id` `string` max length 256
- `device_token` `string` max length 512
- `device` `object` 20 fields `is_headless` `boolean`
- `ua_consistent` `boolean`
- `is_emulated` `boolean`
- `is_noise_injected` `boolean`
- `is_tampered` `boolean`
- `is_context_mismatch` `boolean`
- `is_engine_mismatch` `boolean`
- `is_os_mismatch` `boolean`
- `is_font_standardized` `boolean`
- `antidetect_score` `integer` min 0 · max 100
- `antidetect_confidence` `"low" | "medium" | "high"`
- `is_emulator` `boolean`
- `is_rooted` `boolean`
- `is_cloned` `boolean`
- `is_hooked` `boolean`
- `is_sideloaded` `boolean`
- `is_adb_enabled` `boolean`
- `is_mock_location` `boolean`
- `is_vpn_active` `boolean`
- `is_debuggable` `boolean`

- `timezone` `string` max length 64
- `phone` `string` max length 32
- `phone_country` `string` max length 8
- `event_country` `string` max length 8
- `ip_country` `string` max length 8
- `source` `string` max length 64
- `site` `string` max length 256
- `campaign` `string` max length 256
- `affiliate` `string` max length 256
- `link` `string` max length 512

Responses`200` Success.

A JSON object whose fields this route does not yet declare in its schema. [The API reference](https://kaidn.io/docs/api) documents what comes back.

`400` The request body or query string failed validation.
- `error` `string` required What went wrong.

`401` Missing or invalid API key.
- `error` `string` required What went wrong.

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required What went wrong.

operationId postBatchScore

post`/v1/batch/check/email`

### Check many email addresses at once

Request body · required
- `rows` `object[]` required min 1 items · max 1000 items1 fields `email` `string` required min length 3 · max length 320

Responses`200` Success.

A JSON object whose fields this route does not yet declare in its schema. [The API reference](https://kaidn.io/docs/api) documents what comes back.

`400` The request body or query string failed validation.
- `error` `string` required What went wrong.

`401` Missing or invalid API key.
- `error` `string` required What went wrong.

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required What went wrong.

operationId postBatchCheckEmail

post`/v1/batch/check/ip`

### Check many IP addresses at once

Request body · required
- `rows` `object[]` required min 1 items · max 1000 items1 fields `ip` `string` required min length 3 · max length 45

Responses`200` Success.

A JSON object whose fields this route does not yet declare in its schema. [The API reference](https://kaidn.io/docs/api) documents what comes back.

`400` The request body or query string failed validation.
- `error` `string` required What went wrong.

`401` Missing or invalid API key.
- `error` `string` required What went wrong.

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required What went wrong.

operationId postBatchCheckIp

post`/v1/batch/check/phone`

### Check many phone numbers at once

Request body · required
- `rows` `object[]` required min 1 items · max 1000 items2 fields `phone` `string` required min length 3 · max length 32
- `country` `string` min length 2 · max length 2

Responses`200` Success.

A JSON object whose fields this route does not yet declare in its schema. [The API reference](https://kaidn.io/docs/api) documents what comes back.

`400` The request body or query string failed validation.
- `error` `string` required What went wrong.

`401` Missing or invalid API key.
- `error` `string` required What went wrong.

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required What went wrong.

operationId postBatchCheckPhone

post`/v1/batch/lists`

### Add many list entries at once

Request body · required
- `rows` `object[]` required min 1 items · max 1000 items3 fields `list` `"allow" | "block"` required
- `type` `"ip" | "email" | "device" | "user"` required
- `value` `string` required min length 1 · max length 320

Responses`200` Success.

A JSON object whose fields this route does not yet declare in its schema. [The API reference](https://kaidn.io/docs/api) documents what comes back.

`400` The request body or query string failed validation.
- `error` `string` required What went wrong.

`401` Missing or invalid API key.
- `error` `string` required What went wrong.

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required What went wrong.

operationId postBatchLists

## Events

Read back what was scored.

get`/v1/events`

### List scored events

Newest first. Filter by verdict or event type, and page with limit and offset.

query parameters
- `limit` `string` pattern ^\d+$
- `offset` `string` pattern ^\d+$
- `verdict` `"allow" | "review" | "block"`
- `event` `string` max length 64

Responses`200` Success.

A JSON object whose fields this route does not yet declare in its schema. [The API reference](https://kaidn.io/docs/api#events) documents what comes back.

`400` The request body or query string failed validation.
- `error` `string` required What went wrong.

`401` Missing or invalid API key.
- `error` `string` required What went wrong.

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required What went wrong.

operationId getEvents

get`/v1/stats`

### Verdict totals

Counts and average score per verdict over a rolling window.

query parameters
- `window_hours` `string` pattern ^\d+$

Responses`200` Success.

A JSON object whose fields this route does not yet declare in its schema. [The API reference](https://kaidn.io/docs/api#events) documents what comes back.

`400` The request body or query string failed validation.
- `error` `string` required What went wrong.

`401` Missing or invalid API key.
- `error` `string` required What went wrong.

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required What went wrong.

operationId getStats

get`/v1/device/{deviceId}/observations`

### Device timeline

Everything observed for one device id, for investigating a suspected ring.

query parameters
- `hours` `string` pattern ^\d+$
- `deviceId` `string` required max length 256

Responses`200` Success.

A JSON object whose fields this route does not yet declare in its schema. [The API reference](https://kaidn.io/docs/api#events) documents what comes back.

`400` The request body or query string failed validation.
- `error` `string` required What went wrong.

`401` Missing or invalid API key.
- `error` `string` required What went wrong.

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required What went wrong.

operationId getDeviceByDeviceIdObservations

## Lists

Your own allowlists and blocklists.

get`/v1/lists`

### List your allowlist and blocklist entries

Responses`200` Success.

A JSON object whose fields this route does not yet declare in its schema. [The API reference](https://kaidn.io/docs/api#lists) documents what comes back.

`400` The request body or query string failed validation.
- `error` `string` required What went wrong.

`401` Missing or invalid API key.
- `error` `string` required What went wrong.

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required What went wrong.

operationId getLists

post`/v1/lists`

### Add an allowlist or blocklist entry

Request body · required
- `list` `"allow" | "block"` required
- `type` `"ip" | "email" | "device" | "user"` required
- `value` `string` required min length 1 · max length 320

Responses`200` Success.

A JSON object whose fields this route does not yet declare in its schema. [The API reference](https://kaidn.io/docs/api#lists) documents what comes back.

`400` The request body or query string failed validation.
- `error` `string` required What went wrong.

`401` Missing or invalid API key.
- `error` `string` required What went wrong.

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required What went wrong.

operationId postLists

delete`/v1/lists/{id}`

### Delete a list entry

path parameters
- `id` `string` required pattern ^\d+$

Responses`200` Success.

A JSON object whose fields this route does not yet declare in its schema. [The API reference](https://kaidn.io/docs/api#lists) documents what comes back.

`400` The request body or query string failed validation.
- `error` `string` required What went wrong.

`401` Missing or invalid API key.
- `error` `string` required What went wrong.

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required What went wrong.

operationId deleteListsById

## Config

Per-tenant weights and thresholds.

get`/v1/config`

### Read your scoring configuration

The per-tenant check weights and the review and block thresholds in force.

Responses`200` Success.

A JSON object whose fields this route does not yet declare in its schema. [The API reference](https://kaidn.io/docs/api#rules) documents what comes back.

`400` The request body or query string failed validation.
- `error` `string` required What went wrong.

`401` Missing or invalid API key.
- `error` `string` required What went wrong.

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required What went wrong.

operationId getConfig

put`/v1/config`

### Update your scoring configuration

Responses`200` Success.

A JSON object whose fields this route does not yet declare in its schema. [The API reference](https://kaidn.io/docs/api#rules) documents what comes back.

`400` The request body or query string failed validation.
- `error` `string` required What went wrong.

`401` Missing or invalid API key.
- `error` `string` required What went wrong.

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required What went wrong.

operationId putConfig

## Privacy

Erasure and suppression, for GDPR requests.

post`/v1/forget`

### Erase a data subject

GDPR Article 17. Removes every row Kaidn holds for the identifier and compacts the store, so the data is gone from the file rather than merely hidden from a query.

Request body · required
- `email` `string` max length 320
- `phone` `string` max length 32
- `ip` `string` max length 45
- `device_id` `string` max length 256
- `user_id` `string` max length 256

Responses`200` Success.

A JSON object whose fields this route does not yet declare in its schema. [The API reference](https://kaidn.io/docs/api#privacy) documents what comes back.

`400` The request body or query string failed validation.
- `error` `string` required What went wrong.

`401` Missing or invalid API key.
- `error` `string` required What went wrong.

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required What went wrong.

operationId postForget

post`/v1/subject`

### Export what is held about a subject

GDPR Article 15, scoped to your own tenant. Built so a controller can answer a subject access request from their backend; it is not a route a data subject calls directly.

Request body · required
- `email` `string` max length 320
- `phone` `string` max length 32
- `ip` `string` max length 45
- `device_id` `string` max length 256
- `user_id` `string` max length 256
- `limit` `integer` min 1 · max 5000

Responses`200` Success.

A JSON object whose fields this route does not yet declare in its schema. [The API reference](https://kaidn.io/docs/api#privacy) documents what comes back.

`400` The request body or query string failed validation.
- `error` `string` required What went wrong.

`401` Missing or invalid API key.
- `error` `string` required What went wrong.

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required What went wrong.

operationId postSubject

get`/v1/suppressions`

### Suppression audit trail

Local suppressions from labels and erasures. Hashes only, never raw identifiers.

query parameters
- `limit` `string` pattern ^\d+$

Responses`200` Success.

A JSON object whose fields this route does not yet declare in its schema. [The API reference](https://kaidn.io/docs/api#privacy) documents what comes back.

`400` The request body or query string failed validation.
- `error` `string` required What went wrong.

`401` Missing or invalid API key.
- `error` `string` required What went wrong.

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required What went wrong.

operationId getSuppressions

## Service

Health and metadata.

get`/v1/health`

### Service health and intel-feed freshness

Responses`200` Success.
- `status` `string`

`400` The request body or query string failed validation.
- `error` `string` required What went wrong.

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required What went wrong.

operationId getHealth

get`/v1/ip`

### Echo the caller's IP

Returns the public IP Kaidn sees for this request, for pre-filling a checker.

Responses`200` Success.

A JSON object whose fields this route does not yet declare in its schema. [The API reference](https://kaidn.io/docs/api) documents what comes back.

`400` The request body or query string failed validation.
- `error` `string` required What went wrong.

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required What went wrong.

operationId getIp

get`/v1/lookups`

### Lookup history

Past email, IP and phone checks made by this tenant.

Responses`200` Success.

A JSON object whose fields this route does not yet declare in its schema. [The API reference](https://kaidn.io/docs/api) documents what comes back.

`400` The request body or query string failed validation.
- `error` `string` required What went wrong.

`401` Missing or invalid API key.
- `error` `string` required What went wrong.

`429` Rate limit exceeded. Back off and retry.
- `error` `string` required What went wrong.

operationId getLookups

[PreviousAPI referenceEvery endpoint, field and reason code](https://kaidn.io/docs/api)[NextGuidesWorking code for the common jobs](https://kaidn.io/docs/guides)