Docs menuAll pages, quickstarts and this page’s contents
Docs
Web
Mobile
  • Androidsoon
  • iOSsoon
  • React Nativesoon
  • Fluttersoon
Server
On this page

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 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

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<ip>

      max length 45

    • email string<email>

      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 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<ip>

    max length 45

Responses
200 Success.

A JSON object whose fields this route does not yet declare in its schema. The API reference 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<ip> 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<phone> required

    min length 3 · max length 32

  • country string<iso-country>

    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 items

    17 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 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 items

    1 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 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 items

    1 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 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 items

    2 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 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 items

    3 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 codeNextGuidesWorking code for the common jobs