Check an identifier for scam indications

Consumes credit on every call, including misses (anti-enumeration). A miss is always billed at the minimal rate even when detail=full was requested. Exactly one of input (structured, normalized server-side) or query (pre-normalized searchQueryIndex, used by the SDKs) must be present.

Auth: Bearer <access_token>scope: scammer.checkcreditSource: USER

Parameter header

Nama

Tipe

Keterangan

Idempotency-Key

string

Dedup key for retries: same key + same payload returns the stored result without charging again; same key + different payload answers 409. Hashed exactly as received — no trimming — so the value a partner records is the value that reconciles. The SDKs send one on every call.

Request body

Exactly one of input or query must be present.

Nama

Tipe

Keterangan

creditSource

USER | PARTNER | AUTO

Who pays. USER: the consenting user's subscription credits (Stage 1). PARTNER: the org's prepaid balance [Stage 2]. AUTO: user first, fall back to partner [Stage 2].

detail

minimal | full

minimal omits topChronologies/comments and is always English (no translation cost). full adds them; every partner may request it.

locale

string

BCP-47; only honored for detail=full (translation of tags and chronologies). On the USER path it follows the user's own premium subscription (403 translation_not_permitted without it).

input

CheckInput

Structured identifier, normalized server-side with the same helpers the report pipeline uses. DOMAIN is deliberately not a supported type: the backend has no domain index, so such a key could never hit while the miss would still bill.

query

string

Escape hatch: a pre-normalized searchQueryIndex as built by the SDKs (e.g. PHONE_+62812...). Validated against a per-type whitelist; prefer input.

Dikirim sebagai application/json.

Respons

Respons sukses berbentuk ScammerCheckResult.

Katalog error

400
invalid_request
400
unsupported_input_type
400
unsupported_credit_source: PARTNER/AUTO before Stage 2
401
expired_token: refresh and retry
401
invalid_token: terminal: discard the grant, re-consent
401
grant_revoked: terminal: discard the grant, re-consent
401
invalid_api_key: Only the two terminal codes end a session.
402
insufficient_user_credits
402
insufficient_partner_balance
402
insufficient_credits: Identical for hit and miss — the error never leaks whether the identifier exists.
403
missing_scope
403
translation_not_permitted: a translated full result for a user without an active premium subscription
403
credential_mismatch
403
partner_suspended
409
idempotency_conflict: same key, different payload
429
rate_limited: the balance this check would charge was being written by another check at the same instant; nothing was charged, so honor the Retry-After header and the retry runs the check for real
429
daily_quota_exceeded: sandbox only: the org's 1,000 checks a day are spent; Retry-After points at the reset at 00:00 UTC (07.00 WIB). Do not retry before then.