Skip to main content
POST
Entity Deep Check

Authorizations

X-API-Key
string
header
required

Body

application/json

Request for POST /v1/entity/deep-check (#396, #403).

Takes entity fields rather than an entity_id from a prior check: the audit trail is keyed by sha256(entity_name) and is one-way, so an id could not be resolved back to the name the screens have to query. kvk_number is optional and only consulted by the insolvency source (#403): the Centraal Insolventieregister keys searchUndertaking on the KvK number, which is an exact lookup where a trade-name search is a fuzzy one.

entity_name
string
required

Legal entity or person name

Required string length: 1 - 500
country
string
required

ISO 3166-1 alpha-2 country code

Required string length: 2
kvk_number
string | null

Dutch KVK number (8 digits); enables an exact insolvency-register lookup

Response

Successful Response

Response from /v1/entity/deep-check (#396, #402, #403).

sources_returned is built from payment.DEEP_CHECK_TIER_ADDS[tier] -- the same table enhanced_check_hint advertises -- so what was promised and what was delivered are one value. A name may only join that table together with the field that fills it on that tier.

entity_name
string
required
country
string
required
sources_returned
string[]
required

Sources actually run; equals EnhancedCheckHint.adds

pep_extended
PepScreenResult · object
required

Result of the pep_extended source. screened is never False on a 200.

There is no code path that returns this model without having queried OpenSanctions: app/services/pep.py raises rather than fabricating a clean screen, and the router turns that into a 503 so the payment is never settled (#284, #396).

processing_time_ms
integer
required
Required range: x >= 0
quality
string
default:deep

deep (fresh) or extended (enhanced); see DEEP_CHECK_TIER_NAMES

adverse_media
AdverseMediaResult · object | null

Populated only on a tier whose adds include adverse_media. None means the tier did not include it -- never that a screen ran and found nothing.

insolvency_records
InsolvencyRecordsResult · object | null

Dutch Centraal Insolventieregister screen; on every tier since #403. applicable: false (never null) when country is not NL.

credit_report
CreditReportResult · object | null

Populated only on a tier whose adds include credit_report, and only for a country with a registered provider. None means the tier did not include it -- never that a screen ran and found no credit risk.

disclaimers
string[]
sandbox
boolean
default:false
version
string
default:1.0