---
title: "Should you engage? A fast, deterministic engage-or-not answer"
method: POST
path: "/v1/screen"
tags: ["screen"]
---

# Should you engage? A fast, deterministic engage-or-not answer

`POST /v1/screen`

## Request

- Base URL: `https://jid.com`
- URL: `https://jid.com/v1/screen`
- Auth: one of:
  - none
  - HTTP bearer

No key: free tier (rate-limited per IP). With a key: 1 check. No AI in the decision. Pass any of domain, url, email, phone or company_name; the context; an amount; a policy. Returns engage (true/false), risk, confidence, subject_type, reasons with sources, mitigations, checks, a read (headline, engage | verify_first | do_not_engage, failed checks, lookup links: render the read for humans), the matched Jid file and a signed receipt. Hard rules (engage=false under every policy): confirmed exclusion, possible sanctions or export-list name match (manual review, never a finding), registry hard failure, phishing or malware listing, disposable e-mail, domain with no MX and no website, domain under 30 days old with an amount of $1,000 or more, and (strict only) an affiliation mismatch. Individuals get technical signals only. engage is advisory. Rules version 2026-10-05.2: https://jid.com/screen-rules

## Request body

- object
  - `domain` string
  - `url` string: Only the host is used.
  - `email` string
  - `phone` string: Ideally +E.164.
  - `company_name` string
  - `name` string: A person's name: accepted, never looked up.
  - `context` 'lead' | 'inbound_email' | 'partnership' | 'vendor' | 'purchase' | 'marketplace_seller' | 'agent_action': Default lead, or purchase when only a url or domain is given.
  - `policy` 'strict' | 'balanced' | 'permissive'
  - `amount` number: USD at stake
  - `country` string: Default country for a phone number without +
  - `retain` boolean: Keep the receipt 13 months instead of 30 days
  - `ip_country` string: Location check: country of the request (e.g. x-vercel-ip-country)
  - `ip_region` string: Location check: ISO 3166-2 region of the request
  - `ip_city` string: Accepted, not compared, not stored
  - `ip_asn` integer: Location check: ASN of the request's network (hosting/VPN recognition)
  - `ip` string: Optional raw IP: used in memory for the Tor and ASN lookups only, never stored or returned
  - `browser_timezone` string: Location check: IANA time zone from the browser
  - `stated_country` string: Location check: the country the counterparty stated
  - `signal` string: Jid Signals token from the visitor's browser (the jid_signal form field set by https://jid.com/s/1.js; jid_signal is also accepted). When it verifies, its country, region, city, network type and time zone replace the ip_* fields and browser_timezone. Expired, altered or other-site tokens are skipped, never negative. See /signals.
  - `site` string: The submitting website's domain. Binds the signal token loosely: a token issued to another site is skipped.

## Response `200`

Screen result

- ScreenResult
  - `engage` boolean
  - `risk` 'low' | 'medium' | 'high' | 'unknown'
  - `confidence` number
  - `subject_type` 'business' | 'individual_or_unverified' | 'website'
  - `summary` string
  - `hard_rules` string[]
  - `risk_points` number
  - `reasons` object[]
    - `code` string
    - `kind` 'hard' | 'negative' | 'positive' | 'info' | 'skipped'
    - `points` number
    - `text` string
    - `source` string
    - `source_url` string, nullable
    - `checked_at` string, nullable
  - `mitigations` object[]
    - `code` string
    - `text` string
  - `entity` object, nullable
    - `id` string
    - `name` string
    - `url` string
    - `match_confidence` string
    - `relied_on` boolean
  - `checks` Check[]
    - `id` string: Stable id: registered, sanctions, threat_feeds, email_address, mail_domain, domain_age, website, affiliation, adverse_records, licence, phone, location, enquiry, funding, complaints, lookalike_domain, email_auth, history
    - `label` string
    - `group` 'identity' | 'legitimacy' | 'safety' | 'location' | 'capacity' | 'history'
    - `status` 'pass' | 'fail' | 'unknown' | 'na'
    - `severity` 'block' | 'warn' | 'info': What a fail means: block = do not engage, warn = verify first, info = never changes the recommendation
    - `evidence` string
    - `lookup` object
      - `label` string
      - `url` string
    - `phrase` string
  - `read` Read: What to show a human: render this and nothing else.
    - `headline` string
    - `recommendation` 'engage' | 'verify_first' | 'do_not_engage'
    - `passed` integer
    - `total` integer: Checks that ran (status pass or fail) and decide (severity block or warn), plus location consistency, which is counted but never decides
    - `reason` string: Why a read with no registry match is not engage, e.g. "Not found on the registers Jid checks for Indonesia (LEI records only)". Also in the headline, followed by ", so: verify first".
    - `not_checked` string[]: Labels of deciding checks that did not run or did not finish
    - `sender` string: Qualify only, response only (never stored): the Jid Signals location next to the stated place and the company domain's age
    - `failed` object[]
      - `label` string
      - `evidence` string
      - `lookup` object
    - `lookups` object[]
      - `label` string
      - `url` string
    - `file_url` string
    - `subject` string, nullable
  - `website_declared` WebsiteDeclared: What a company's own website states about itself (provenance tier website_declared): identity context only, never a registry result. Present only when no Jid file holds or is associated with the domain.
    - `tier` 'website_declared'
    - `domain` string
    - `legal_name` string: As printed, with its legal form
    - `trade_name` string, nullable
    - `address` string, nullable: As printed; null when the site prints addresses in several states
    - `state` string, nullable
    - `postal_code` string, nullable
    - `source_url` string
    - `read_at` string, date-time
    - `how` string
    - `note` string
  - `outcome_links` OutcomeLinks: Keyed calls only: signed one-click URLs that record an outcome (POST /v1/outcomes) without a login.
    - `legit` string
    - `sales_pitch` string
    - `spam` string
    - `scam` string
    - `closed` string
    - `good` string: 2026-10-05 button, still accepted
    - `junk` string: 2026-10-05 button, still accepted
  - `check_runs` object: Which live lookups ran (this was `checks` before 2026-10-05).
  - `receipt_id` string
  - `receipt_url` string
  - `rules_version` string
  - `latency_ms` number
  - `checks_used` number
  - `location` object: Present when location inputs were given
    - `consistent` union: true, false or "unknown"
      - boolean
      - string
    - `reference` object, nullable
    - `signals` object[]
    - `network` object
      - `type` 'tor' | 'hosting_or_vpn' | 'other' | 'unknown'
      - `asn` integer, nullable
      - `source` string
    - `detail` string

## Other responses

- `400`: Error
- `402`: Error
- `429`: Error

---

[API](https://skmtc.dev/jid/apis/jid-api.md) · [All operations](https://skmtc.dev/jid/apis/jid-api/llms.txt) · [OpenAPI document](https://skmtc.dev/jid/apis/jid-api/revisions/453a19ce3d5d?raw)