Schemas

Your own reference for the subject, echoed nowhere but carried through the assessment for audit.

The subject's date of birth. A year alone (1975) is enough — every comparison is made on the birth year, with a two-year tolerance, so day and month differences never eliminate a result on their own. This is the single most useful attribute to supply: it is the only evidence that can eliminate a sanctions listing.

The subject's gender. Corroborating evidence only — never eliminates a result by itself, since given names are frequently unisex across cultures.

The subject's nationalities and citizenships as ISO 3166-1 alpha-2 codes. Second only to date of birth in eliminating power: a listing whose own nationality sits in an unrelated region with no migration or diaspora link is a different person, and that alone is enough to rule it out. Send every nationality you hold — one shared country anywhere across the two records defeats the contradiction, so an incomplete list risks eliminating a true match. Matched against the listing's nationality and citizenship, never against the jurisdiction that designated it.

The subject's country of residence, ISO 3166-1 alpha-2. Deliberately weaker than nationalities — expatriate work and cross-border residence are ordinary, so where someone lives never eliminates a result on its own. Supply it as corroboration, not as a substitute for nationality.

The subject's place of birth.

A date on which the subject is evidenced to have been alive — an identity document issue date, say. Supply it to eliminate results recorded as deceased before then; without it, no such date is assumed.

Full name of the subject to search for. Optional: a search needs either a name or idNumbers, so an identification number alone is a complete query.

A pre-analysed name breakdown from breakdownNameQuery. Only used by fuzzy mode; token mode reads fullName (falling back to this query name).

Name matching strategy. Defaults to "token". Pass "fuzzy" to use the legacy phrase-variation search.

The kind of subject to search. Defaults to "individual". Individuals are matched part-by-part against a name-variation dictionary. Entities (organizations, vessels and aircraft) have no such structure, so they are matched on their identity-bearing words instead: incorporation suffixes (Ltd, LLC, PJSC, Company) and word order are ignored, every remaining word must appear in the listed name or an alias, and relevance orders what survives. A listing carrying extra words is ranked down rather than excluded. See includeFuzzy to allow near-spellings.

Entity searches only. Whether near-spellings are allowed, word by word. Defaults to true — pass false to demand letter-perfect words. On by default because the differences it covers are the norm in this corpus, not the exception: sanctions lists are published by British and American authorities and transliterated consistently by neither, so Academy of National Defense Science and ...Defence Science are one organization and a strict search finds whichever spelling it was typed with. Words of five characters or more tolerate two edits; nothing shorter moves at all, so Iran never becomes Iraq and a vessel 3 never becomes a 4. The first letter must always match. Ignored for individual searches, whose spelling variants are resolved by the name-part dictionary instead.

Filter by specific sanctions sources. If omitted, all sources are searched.

Filter by ISO 3166-1 alpha-2 country codes to narrow results to specific jurisdictions

Identification document numbers (NIC, passport, etc.) to match against any ID on a record. Matches any record whose stored ID contains at least one of the provided values. Non-alphanumeric characters are stripped and matching is case-insensitive and substring-based, so values are matched even when embedded in surrounding text. Usable without a name: passed alone, the search returns every record carrying one of these numbers, each with nameMatch.matchType: "id".

Drop results whose nameMatch.matchConfidence is below this, 0.0-1.0. Defaults to 0 — no filtering. This confidence is name-only, so a floor applied here runs before the corroborating evidence a screening caller holds: a strong partial match can score 0.44 on the name alone and clear 0.6 once a matching date of birth is folded in, but only if the search still returned it. Apply the floor after corroboration instead, or pass a value here when you want the search to do it. Results with no confidence (id hits) are never dropped — a filter on a score they do not have would silently hide them.

What you know about the person you are screening, beyond their name. Supplying it runs a second, attribute-based pass over every result and annotates each with a disambiguation verdict built from date of birth, geography and entity kind. A date of birth is by far the most useful field to send. Every result, not only the weak ones: two people who share a name share it exactly, so a perfect name match is where a contradicting date of birth is most decisive. Nothing is filtered out on the verdict and no result is ever removed from the response because of it; filter on disambiguation.decision === "discard" yourself, so the reasoning behind every elimination stays in your audit trail. Individual searches only.

Full name of the individual to search for

When true, bypasses cached results and runs a fresh search against all data sources. Default: false.

When true, only returns profiles flagged as high-risk (PEPs, sanctioned individuals, adverse media matches). Set to false to include all matching profiles. Default: true.

Name matching strategy. "token" (default) matches culturally-aware name-part tokens for precise results; "fuzzy" restores the legacy similarity search.

Drop results whose nameMatch.matchConfidence is below this, 0.0-1.0. Defaults to 0 — no filtering. This confidence is name-only, so a floor applied here runs before the corroborating evidence a screening caller holds: a strong partial match can score 0.44 on the name alone and clear 0.6 once a matching date of birth is folded in, but only if the search still returned it. Apply the floor after corroboration instead, or pass a value here when you want the search to do it. Results with no confidence (id hits) are never dropped — a filter on a score they do not have would silently hide them.

What you know about the person you are screening, beyond their name. Supplying it runs a second, attribute-based pass over every result and annotates each with a disambiguation verdict. Alongside date of birth and geography, a high-risk profile's dated positions are read as a role timeline: an office held in 1975 implies a birth year that a customer born in 1990 cannot have. Every result, not only the weak ones: two people who share a name share it exactly, so a perfect name match is where a contradicting date of birth is most decisive. Nothing is filtered out on the verdict and no result is ever removed from the response because of it; filter on disambiguation.decision === "discard" yourself, so the reasoning behind every elimination stays in your audit trail.

Document type (e.g. "passport", "national_id")

Document number or identifier

Additional details about the document

IDs of source documents referencing this identification

Full name of the associate or relative

Relationship to the dossier subject (e.g. "spouse", "business partner", "sibling")

Brief description of the association

IDs of source documents supporting this association

Title or role held (e.g. "Minister of Finance")

Organization or body where the position was held

Time period of the position (e.g. "2015–2020")

Description of the role and responsibilities

Date this information was current as of

IDs of source documents supporting this position

Excerpt from source material

PEP likelihood score from 0.0 (unlikely) to 1.0 (certain)

PEP category (e.g. "Head of State", "Senior Government Official", "State-Owned Enterprise Executive")

Step-by-step reasoning explaining how the PEP score was derived

Overall risk score from 0.0 (low risk) to 1.0 (high risk)

Narrative explanation of the risk assessment

Risk category classification (e.g. "high", "medium", "low")

PEP-specific scoring breakdown (present when PEP indicators are found)

The queried name part. Absent on a ruled_out candidate leftover the query never contained.

The stored name part this query token paired with, or the leftover candidate part when status is ruled_out. Absent when the query part did not match.

full (same name-part group), partial (initial ↔ spelled-out), unmatched (query part with no counterpart), ruled_out (candidate part the query cannot account for).

How the result was reached, strongest first. Sanctions search returns id (an identification number matched), exact (the name equalled the listed name or an alias), full (every queried name part was accounted for), partial (only some were) or text (keyword match only). High-risk search returns exact, full or partial. Absent for fuzzy searches, which have no notion of match type.

How well the names matched, 0.0–1.0: the share of the queried name that was accounted for. Each part starts at an equal 1/n, then moves with the listed part's popularity and name-part type — a rare surname takes more than 1/n, a common given name or a particle takes less — and is credited in full, by initial (half), or not at all. Every queried part spelled out scores 1.0; the same name in abbreviated form scores lower. An extra rare leftover listed part is discounted further than an extra common patronymic — searching "Abram Goldman" scores the listed "Abram Borisovich Goldman" at 0.77 rather than 1.0. Always 1.0 for id and exact.

The stored name the match was licensed by — the primary name, or the alias that matched. Records are frequently matched on an alias, so comparing this against the result name shows why it was returned.

How distinctive the MATCHED name is, 0.0–1.0, from the popularity of each of its name parts. Low means a common name, where even an exact match is weak evidence of identity ("John Smith" ≈ 0.21); high means a distinctive one, where the same match is strong. Read it alongside matchScore, which says how well the names matched but not how much that matching is worth. Scored per result from matchedName, so it varies across a single search — a listing carrying a patronymic or a rarer surname scores above a bare one. Falls back to the searched name only for exact (the two names are equal) and text (no token analysis). Absent for id hits. Individuals only — organizations, vessels and aircraft have no person-name statistics behind them.

The nameUniqueness score as a band, calibrated against the sanctions corpus so it can be acted on without knowing the scale: very_common (bottom ~10% — the names false positives cluster on), common (~36%), uncommon (~37%), distinctive (top ~17%). Present whenever nameUniqueness is.

How likely this result is the person searched for, 0.0–1.0 — matchScore and nameUniqueness combined into one rankable number. How the names matched dominates: every exact hit scores at least 0.75 however common the name, because an exact match on a common name is still an exact match. Within that, distinctiveness decides position, measured as the matched name's percentile against the sanctions corpus rather than its raw uniqueness (which saturates and never spans 0–1). Roughly: exact on a very common name ≈ 0.75, exact on a distinctive one ≈ 1.0, a partial match on a common name ≈ 0.39. Name-derived only — raise it against any corroborating date of birth, document number or country you hold, which the search never saw. Absent for id hits, which are not name matches. Filter on it with minConfidence.

How each name part compared, including candidate leftovers. A part that appears on the listed name and not in the query is ruled_out: the result is kept so that leftover is visible. Absent for id and text hits. An exact hit has analysis only when a longer recorded name carries leftovers.

Labels for match situations that matchType does not capture. unaccounted_listed_parts means a listed name part is absent from the query — including when the hit was licensed by a shorter alias of a longer recorded name. The result is returned so the leftover is visible.

The date of birth supplied on the screened subject.

Every date of birth recorded on this result.

Birth-year window inferred from the result's dated roles where it carries no date of birth, as { from, to }. Present only when the age rule was reached.

Which dated role or event the inferred birth-year window was derived from.

Countries read off the screened subject — nationality, place of birth and residence.

Countries recorded on this result.

Corroborating signals that pointed the same way as the primary contradiction.

Whether the verdict leaned on public knowledge about a named individual rather than on the supplied records. Confidence is capped at medium when it did.

discard where attribute evidence positively contradicts identity, retain otherwise. Retain is the default: absence of confirming evidence is not contradiction, so a sparse record is always retained. Results are never dropped from the response on this verdict — filter on it yourself, so the reasoning for every elimination stays in your audit trail.

How to queue the result. false_positive and possible_match are confident calls; likely_false_positive marks one the evidence points at but which did not clear the discard confidence floor, so it can be deprioritised without leaving the queue; needs_review means nothing decisive was found.

Confidence in the verdict. A discard is only ever emitted at high; anything weaker is returned as a retain carrying likely_false_positive.

hard for a date-of-birth contradiction, an entity-type mismatch, an inferred-age window missed by more than the margin, or a nationality conflict; soft for jurisdiction or residence geography, gender, and a near-miss age window; none where nothing contradicted. A result on a sanctions or asset-freeze list is never discarded on soft evidence alone.

The rules that fired, from a closed vocabulary: DOB_CONTRADICTION, DOB_WITHIN_TOLERANCE, DATA_ARTIFACT_SUSPECTED, PLACEHOLDER_DOB_UNRELIABLE, MULTIPLE_CANDIDATE_DOBS_PARTIALLY_CONSISTENT, AGE_IMPLAUSIBLE_FOR_ROLE_TIMELINE, DECEASED_BEFORE_CUSTOMER_ACTIVITY, ENTITY_TYPE_MISMATCH, GEOGRAPHY_INCONSISTENT_CORROBORATED, NATIONALITY_CONFLICT, GENDER_MISMATCH_CORROBORATED, INSUFFICIENT_DATA_TO_ELIMINATE, SANCTIONS_CONSERVATIVE_RETENTION, NO_CONTRADICTION_FOUND.

One to three sentences naming the specific field values that were compared.

The field values the verdict was reached on.

What the assessment could not settle — the attributes that, if supplied, would have let it decide.

Unique identifier for this individual

Full name of the individual

Countries associated with this individual

Known aliases and alternative names

Identification documents linked to this individual

Known close associates and family members

Known dates of birth (multiple entries when sources disagree)

One-line summary describing the individual

Known locations and addresses

Classification keywords (e.g. "pep", "sanctions", "adverse-media")

Political and professional positions held

AI-generated narrative summary of the individual and their risk profile

Timestamp when this dossier was created

IDs of supporting source documents

Full source documents used to compile this dossier

AI-generated risk scorecard including PEP analysis and overall risk assessment

Whether this result was served from cache

How this dossier was matched against the searched name. Fuzzy searches report only a score.

Why this profile is, or is not, a false positive, decided from date of birth, role timeline, geography and entity kind rather than from the name. Present on every result where the search was given a subject carrying at least one comparable attribute (a date of birth, nationality, country or place of birth) — a profile without it was never assessed, which is not the same as retain.

Deprecated — use nameMatch.matchScore. How closely this dossier's names match the searched name (0-1).

Deprecated — use nameMatch.matchType. Token-search verdict: "exact", "full" or "partial". Absent for fuzzy searches.

The id of the deleted alert.

Always true. The call is only successful once the alert and everything raised with it are gone.

Document type (e.g. "passport", "national_id", "drivers_license")

Document number or identifier

ISO 3166-1 alpha-2 country code of the issuing country

Full name of the individual to screen

Your own reference ID for this screening request (e.g. customer ID, case number). Useful for correlating results with your internal systems.

Identification document details to improve match accuracy. When provided, the screening engine uses these details to reduce false positives.

Date of birth in YYYY-MM-DD format

ISO 3166-1 alpha-2 country code of the individual's nationality or residence

Unique ID of the created screening request. Use this to track the request status and retrieve results.

External reference ID from your system.

Customer display name.

Customer email address.

Customer identity fields. When email and name are provided, an invitation email with the session link is sent automatically.

Session expiry duration in milliseconds. Defaults to 1 hour (3,600,000 ms).

Optional Workflow ID to use for this session. If not provided, the organization default is used.

Explicit FlowConfig defining the steps the customer will go through. If omitted, the config is derived from the workflow or the system default is used.

Integrator-asserted claim values for the workflow's session-sourced claims, keyed by canonical claim field (e.g. { dateOfBirth: '1990-01-15' }). Unknown fields and missing required claims are rejected.

When true, the session is fully purged after the final verdict — customer media, pipeline artifacts, check data and the session itself are deleted from Dossiers, leaving only a PII-free tombstone with deletion counts. A kycSessions.session.purged webhook confirms it. Fetch any evidence you need to retain during the grace window.

Ephemeral sessions only: grace period in milliseconds between the final verdict and the purge, during which media and results remain fetchable. Defaults to 24 hours (86,400,000 ms). Use 0 to purge immediately.

Current session checkpoint.

Embedded attempt records for this session.

Whether the session has been flagged as suspicious.

Reason the session was flagged, if applicable.

Display label for this media item.

Object-storage key for the media file.

Media type, e.g. document-front, liveness-video, signature.

Rendering hint: 'image' or 'video'.

Short-lived signed URL for viewing the media.

Client-captured capture-quality metadata (liveness only).

Submission processing status.

Timestamp the submission started (Unix ms).

Media captured for this submission, with signed viewing URLs.

Session this submission belongs to. Stamped at mapper read-time, not persisted.

Session attempt this submission was made under.

Step-scoped retry identity, set by the client once sent.

Resolved input for this submission (user + system + mapped values). Shape varies by step type.

Canonical output (form data, verification result, etc.). Shape varies by step type.

Document-processor instance backing this submission, if async.

Error message if the submission failed, null otherwise.

Timestamp the submission completed (Unix ms). Null while in progress.

Workflow step ID.

Step type.

Overall step status (reflects the latest submission).

Full ordered submission history for this step.

The latest submission, for quick reads.

Every workflow step with its full submission history.

Best (latest completed) submission per step, keyed by stepId.

Normalized category — switch on this.

Original machine code or rule id. Stable; audit-safe.

Whether a customer retry can plausibly clear this reason.

Customer-safe explanation.

Categorical verdict.

0–100. Omitted for face distance.

Provider-native value: rule confidence 0–1, or face DISTANCE (lower = better).

Face match only: decision threshold on the same scale as raw.

Deduplicated blocking failures across all checks.

True while the session is active and the failing step has attempts remaining.

Admin decision message intended for the applicant.

Admin-internal note. Never shown to the applicant by Dossiers surfaces.

Reserved in 1.0.

Reserved in 1.0.

Name in original script, when the document carries one.

Latin/English transliteration.

Reserved — no name splitting in 1.0.

Reserved — no name splitting in 1.0.

Reserved — no name splitting in 1.0.

Reserved — no name splitting in 1.0.

ISO 3166-1 alpha-2.

Source schema field name.

Latin transliteration of the full extracted address.

ISO 3166-1 alpha-2. Reserved in 1.0.

Verbatim country value. Reserved in 1.0.

Reserved in 1.0.

Reserved in 1.0.

Reserved in 1.0.

YYYY-MM-DD.

Normalized gender; U = present but unparseable.

Latin transliteration.

ISO 3166-1 alpha-2, when convertible.

Short-lived /media/:token URL. Fetch promptly.

Stable storage key (matches result.media[].key).

Reserved in 1.0.

Normalized type — switch on this.

The workflow step that produced this document.

Variant discriminator, e.g. 'OLD' | 'NEW'.

Verbatim internal document type id. Stable; audit-safe.

Primary document number.

Secondary personal number, e.g. NIC number on a passport.

ISO 3166-1 alpha-2.

Verbatim extracted value (alpha-3).

Latin transliteration.

YYYY-MM-DD.

YYYY-MM-DD.

As printed on this document.

As printed on this document.

Raw extracted value: 'm' | 'f' | 'o'.

Every template field, keyed by field name: { value, confidence, originalText, originalLanguage, isHandwritten, source }.

From visual-match + tampering checks.

Reserved in 1.0.

Reserved in 1.0.

raw is a DISTANCE — lower is better; compare against threshold.

Face model identifier.

Portrait crop from the document.

Liveness best frame.

Colour flashed.

Colour the face reflected; '-' when unmeasurable.

Match verdict. 'warning': ambient light too strong for the screen to register — non-blocking. 'void': the capture could not be judged (e.g. the browser throttled the flashes).

Fraction of flashed colours the face visibly reflected, 0–1.

How strongly the face reflected the screen at all.

Ambient light on the face before the flashes, 0–255 luma.

'bright' when ambient light swamped the screen.

Machine reason for a non-pass verdict, e.g. 'SEQUENCE_MISMATCH'.

'COLOR_FLASH' when the capture answered a server-issued colour nonce; see colorFlash.

1:1 match — document portrait vs. liveness best frame.

Reserved in 1.0.

Raw rule id. Stable.

The workflow step that produced this check.

Two to four sentences over the evidence and the verdicts.

Specific points worth a reviewer's attention. Absent when the case is unremarkable.

Model that wrote this summary.

Prompt revision. Changing it re-generates every summary.

Monotonic per session. A higher version supersedes every lower one.

ISO 8601.

Contract version of this object ('1.0').

The KYC session id.

Always 'INDIVIDUAL' in 1.0.

Normalized lifecycle outcome. See docs/kyc-verification-output-spec.md §4.1.

ISO 8601.

Reserved — always [] in 1.0 (AML screening is not session-wired).

Every executed rule, deduped.

Integrator reference: customer.externalId from session creation.

ISO 8601.

ISO 8601.

Present when an identity step completed.

Reserved — KYB is not a session subject type in 1.0.

Present when the workflow has a liveness step.

Reserved in 1.0.

Claimed-vs-extracted reconciliation, keyed by field: { claimed, extracted, match: MATCH|MISMATCH|PARTIAL|NOT_COMPARED, confidence }.

Reviewer-facing prose over the evidence. Advisory — it describes the decision and never contributes to it.

Which evaluation produced the relational verdicts. Absent while the first run is still pending — see kycSessions.session.checksCompleted.

Not populated by Dossiers Cloud — the sibling result field is the verbatim payload.

The reminder rule this state belongs to.

Reminders sent so far in the current idle cycle.

Manual per-rule override — true silences this rule regardless of its own schedule.

Timestamp of the last reminder sent for this rule (Unix ms). Null if none sent yet.

The session's lastActivityAt as of this rule's last send. Lets a caller detect whether the idle cycle has since reset (compare against the session's current lastActivityAt) — used to estimate when the next reminder is due. Null if none sent yet.

Per-rule send counters and pause state for this session.

Unique session identifier.

Customer identity fields.

Customer in-progress state: checkpoint, data, attempts, step tracking.

Session status.

Whether the session is invalid (manually invalidated or superseded).

Suspicious session flag.

Timestamp when the session was created (Unix ms).

Workflow snapshot used for this session.

Derived admin read layer: every step with its full submission history (input, output, signed media) plus a per-step rollup of the best result.

Normalized, versioned verification result — the stable typed contract for integrators. See docs/kyc-verification-output-spec.md.

Reminder-email pause state and per-rule send counters for this session.

Current active tab/user holding the session lock.

Timestamp when the session expires (Unix ms). Null if no expiry.

Timestamp when the session was completed (Unix ms). Null while in progress.

FlowConfig specifying the ordered steps the customer goes through.

Per-step preview data with signed media URLs, keyed by stepId.

Admin decision record (approve/reject) with reason and timestamp. Null until a decision has been made.

Timestamp of the most recent genuine customer activity (Unix ms). Null if none recorded yet.

The created KYC session.

Short-lived JWT token for customer access to the session.

Full URL the customer should visit to complete KYC verification.

Free-text search across session ID, external ID, customer name, and email.

Filter by session checkpoint.

Filter by completion status.

Filter by invalid/flagged status.

Filter by creation date range (start/end as ISO 8601 strings).

Field to sort by.

Sort direction.

Maximum number of results to return (1–100).

Number of results to skip for pagination.

List of KYC sessions matching the query.

Total number of sessions matching the filters (before pagination).

Whether the deletion was successful.

MIME type of the file (e.g., image/jpeg, application/pdf)

Base64 encoded file data (required if url is not provided)

URL to fetch the file from (required if base64Data is not provided)

Original filename (optional)

ID of the document processor to use.

Array of files to process (provide base64 data or URL for each file)

Optional key-value context about the document's subject, recorded against the instance and used to label it. It is never sent to the AI, so it cannot influence extraction; comparing these values against the document happens in a KYC session's claims check, not here. Keys a processor does not declare are recorded alongside the rest but have no effect.

SRI_LANKA_ID — supported keys:

• name — Full name to match against the document
• dateOfBirth — Expected date of birth (YYYY-MM-DD)
• idNumber — NIC or passport number to verify
• address — Residential address to compare (warning-level check)

Optional key-value metadata for syncing purposes (e.g., Bitnomi record IDs). Stored on the instance but not sent to the AI.

Whether to crop images before processing (default: true). When true, document images are cropped before validation and extraction.

Whether processing should happen in the background (default: true). If true, validation and extraction are performed asynchronously; if false, waits for all processing to complete before returning a response.

The KYC session to export.

BUNDLE returns a ZIP containing report.pdf, every captured asset, the raw verification payload and a checksum manifest. PDF returns the rendered report alone.

Include the reviewer-internal note on the decision. Off by default — the note is written for internal audit and is not intended to leave the organization.

Embed document, portrait and signature images in the PDF. Disable for a text-only report.

Path of this asset inside the ZIP bundle.

SHA-256 of the file bytes, lowercase hex.

Storage key of the generated file. Stable; audit-safe.

Short-lived signed download URL.

ISO 8601 expiry of downloadUrl.

SHA-256 of the delivered file, lowercase hex. Recompute after download to prove the archived copy is byte-identical to what was generated.

ISO 8601 generation timestamp.

Report contract version, e.g. "1.0".

Every asset included in the bundle, with its checksum. Empty for the PDF format.

Assets that could not be included, with the reason. Non-empty here means the bundle is incomplete — surface it to the caller rather than treating the export as clean.

Endpoint that receives the POST deliveries.

Event types to deliver.

Display name. Defaults to the URL's host when creating.

Cloud API version deliveries are shaped for and labelled with. Defaults to 2026-10-01 when creating; kept when updating.

Installation that owns the destination. Defaults to the Dossiers-Installation-Id header.

An upsert never re-enables a destination disabled in the dashboard.

HMAC-SHA256 signing secret. Kept across updates.

True when this call created the destination.