Skip to main content
POST
identity.screening.check

Authorizations

Authorization
string
header
required

API key: sk_live_…

Headers

Idempotency-Key
string
required

Required: this capability has an external effect.

Maximum string length: 255
Pramaan-Max-Price-Micro
string

Optional. The most this request may be priced at, in micro-USD (a whole number above 0). It replaces the capability's own price ceiling for this request, lower or higher. Sources that could cost more are left out; when none is left the answer is 400 with the lowest limit that would work.

Pattern: ^[1-9]\d{0,14}$

Body

application/json
fullName
string
required

Full name of the person or company to screen, at least 2 characters.

Required string length: 2 - 256
entityType
enum<string>

What is being screened. Default person.

Available options:
person,
company
dateOfBirth
string

Date of birth (a person) or incorporation date (a company), YYYY-MM-DD. Makes matches more precise.

Pattern: ^\d{4}-\d{2}-\d{2}$
nationality
string

Nationality or country of the entity, as a two-letter code. Makes matches more precise.

Pattern: ^[A-Za-z]{2}$
documentNumber
string

Identity document number. When it matches a listed entry exactly, that entry is treated as a certain match.

Required string length: 1 - 50
adverseMedia
boolean

Also screen negative news coverage. Not available yet: true is refused, because that screening takes longer than one call allows. Leave it out.

saveRecord
boolean

False (default): nothing is kept — the name is screened for this one answer and not stored. True: the screening is kept as a retrievable verification record (it stays until deleted, and you get a ref for the follow-up calls).

endUserId
string

Your own stable id for the person or company (an opaque id, never a name or an email). It is sent to the verification service with the check, also when nothing is saved: the service uses it to tie the check to their other records.

Maximum string length: 256

Response

The result

status
enum<string>
required

The screening service's own outcome. In practice it is clear or review (possible matches worth a human look); hit is returned only for an account set up to decline outright, so do not wait for it. A clear outcome can still come with entries in hits, including a sanctions entry: always read hits and decide from them.

Available options:
clear,
review,
hit
totalHits
integer
required

How many list entries are in hits.

Required range: -9007199254740991 <= x <= 9007199254740991
hits
object[]
required

The list entries that matched above the match cutoff: each one's name, how strongly it matched and what it is listed as. Not a score or ranking of the person screened.

ref
string

Reference to what this call created. Pass it as ref to identity.verification.get or identity.verification.delete (only set when saveRecord was true).