API REFERENCE · SCHEMA
RetainedScreeningResult schema
Required fields are always present in their containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.
All endpoints and schemasGET /results/{id} adds the retained subject and reference to the original result. Both keys are always present here and are null for minimal retention. POST /screenings and GET /results list items return ScreeningResult without these additions.
idRequired- string
Screening UUID; use it to retrieve retained result/evidence and locate linked review cases.
Format: uuid.
environmentRequired- enum
Environment owned by the API key. Sandbox evidence is synthetic.
Values: "sandbox", "production".
statusRequired- enum
potential_match requires review of candidates; no_match means no returned candidates within the selected coverage and matching rules. Neither is a business approval or legal clearance.
Values: "potential_match", "no_match".
createdAtRequired- string
Screening creation timestamp in ISO 8601 UTC.
Format: date-time.
matchesRequired- object[]
Candidate records with field evidence and conflicts. Always an array; empty for no_match. No silent truncation is performed.
matches item fields
Each array item: object.
matches[]Required.record - objectView SourceRecord schema
matches[].record fields and rules
See all SourceRecord fields for the complete structure, required properties and constraints.
matches[]Required.score - number
Similarity measure, not probability of wrongdoing.
Minimum: 0. Maximum: 100.
matches[]Required.evidence - object[]
matches[].evidence item fields
Each array item: object.
matches[]Required.evidence[] .field - string
matches[]Required.evidence[] .queryValue - string
matches[]Required.evidence[] .sourceValue - string
matches[]Required.evidence[] .method - string
matches[]Required.evidence[] .contribution - number
matches[]Required.evidence[] .explanation - string
matches[]Required.conflicts - string[]
matches[].conflicts item fields
Each array item: string.
coverageRequired- Coverage[]
Exact source versions used, including freshness and retained publisher notices. Always present, including no_match.
coverage item fields
Each array item: Coverage.
coverage[]Required.sourceId - string
coverage[]Required.version - string
coverage[]Required.retrievedAt - string
Format: date-time.
coverage[]Optional.publishedAt - string
Authority-supplied publication date (YYYY-MM-DD) or RFC 3339 timestamp, preserving the precision supplied by the publisher. A date-only value does not imply midnight or a timezone. Omitted when no genuine publication date or timestamp is supplied.
coverage[].publishedAt fields and rules
Choose exactly one option
- string
Format: date.
- string
Format: date-time.
- string
coverage[]Required.fresh - boolean
coverage[]Optional.sourceNotice - object
Included in new production screening results, including no-match results. Absent from synthetic sandbox coverage and older retained evidence; historical evidence is not rewritten.
View SourceNotice schema coverage[].sourceNotice fields and rules
See all SourceNotice fields for the complete structure, required properties and constraints.
versionsRequired- object
Dataset, matching engine and policy versions used for this result. package is included only for package-based coverage.
versions fields and rules
versionsRequired.dataset - string
versionsRequired.matchingEngine - string
versionsRequired.policy - string
versionsOptional.package - string
disclaimerRequired- string
Interpretation limits supplied with this result; preserve them when presenting or exporting evidence.
policySnapshotOptional- object
Immutable organization policy applied at screening time, when one was selected. Omitted when no organization policy applied.
View ScreeningPolicySnapshot schema policySnapshot fields and rules
policySnapshotRequired.name - string
Minimum length: 2. Maximum length: 120.
policySnapshotRequired.purpose - string
Minimum length: 3. Maximum length: 1000.
policySnapshotRequired.jurisdictions - string[]
Minimum items: 1. Maximum items: 30.
policySnapshot.jurisdictions item fields
Each array item: string.
Minimum length: 2. Maximum length: 100.
policySnapshotRequired.requiredSources - object
Allowed keys: "person", "organization", "vessel", "aircraft", "other". Default: {}.
policySnapshot.requiredSources fields and rules
Each additional key uses the following value structure.
Maximum items: 512.
Each array item: string.
Minimum length: 1. Maximum length: 80.
policySnapshotRequired.optionalSources - object
Allowed keys: "person", "organization", "vessel", "aircraft", "other". Default: {}.
policySnapshot.optionalSources fields and rules
Each additional key uses the following value structure.
Maximum items: 512.
Each array item: string.
Minimum length: 1. Maximum length: 80.
policySnapshotRequired.exclusions - string[]
Maximum items: 30. Default: [].
policySnapshot.exclusions item fields
Each array item: string.
Minimum length: 3. Maximum length: 500.
policySnapshotRequired.externalChecks - string[]
Maximum items: 20. Default: [].
policySnapshot.externalChecks item fields
Each array item: string.
Minimum length: 3. Maximum length: 200.
policySnapshotOptional.externalCheckGuidance - object[]
Maximum items: 20.
policySnapshot.externalCheckGuidance item fields
Each array item: object.
policySnapshotRequired.externalCheckGuidance[] .label - string
Minimum length: 3. Maximum length: 200.
policySnapshotRequired.externalCheckGuidance[] .instructions - string
Minimum length: 3. Maximum length: 2000.
policySnapshotOptional.externalCheckGuidance[] .evidenceExample - string
Minimum length: 3. Maximum length: 1000.
Additional fields are not accepted.
policySnapshotRequired.review - object
Default: {}.
policySnapshot.review fields and rules
policySnapshotOptional.review .requireSecondReview - boolean
Default: false.
policySnapshotOptional.review .secondReviewFor - string[]
Maximum items: 4. Default: [].
policySnapshot.review.secondReviewFor item fields
Each array item: string.
Values: "same_identity", "allow", "restrict", "escalate".
policySnapshotOptional.review .approverRoles - string[]
Minimum items: 1. Maximum items: 3. Default: ["owner","admin","analyst"].
policySnapshot.review.approverRoles item fields
Each array item: string.
Values: "owner", "admin", "analyst".
Additional fields are not accepted.
policySnapshotRequired.monitoringIntervalHours - 6 or 24 or 168
Default: 24.
policySnapshot.monitoringIntervalHours fields and rules
Allowed alternatives
- 6
Must equal 6.
- 24
Must equal 24.
- 168
Must equal 168.
- 6
policySnapshotRequired.retentionTrigger - string
Values: "review_completed", "relationship_ended", "business_event". Default: "review_completed".
policySnapshotRequired.id - string
Format: uuid.
policySnapshotRequired.version - integer
Minimum: 0.
policySnapshotRequired.environment - string
Values: "sandbox", "production".
policySnapshotRequired.createdAt - string
Format: date-time.
Additional fields are not accepted.
subjectRequired- Subject or null
May be null.
subject fields and rules
Allowed alternatives
- Subject
subjectRequired.name - string
Name to compare with publisher records. Leading and trailing whitespace is removed; provide the fullest reliable name available.
Minimum length: 2. Maximum length: 300.
subjectOptional.entityType - string
Type of subject. Defaults to person when omitted. Every selected source must support this type.
Values: "person", "organization", "vessel", "aircraft", "other". Default: "person".
subjectOptional.identifiers - object[]
Typed identifiers used for exact matching, such as passport, national_id, registration, lei, imo or mmsi. Defaults to an empty array. Use the publisher’s identifier scheme; custom scheme names are accepted.
Maximum items: 20. Default: [].
subject.identifiers item fields
Each array item: object.
subjectRequired.identifiers[] .type - string
Identifier scheme, such as passport, national_id, registration, lei, imo or mmsi. Matching normalizes supported scheme aliases.
Minimum length: 1. Maximum length: 80.
subjectRequired.identifiers[] .value - string
Identifier value. Send the original value; scheme-specific normalization is applied during matching.
Minimum length: 1. Maximum length: 160.
subjectOptional.identifiers[] .issuer - string
Optional issuing authority or country. Omit when unknown; do not send null.
Minimum length: 1. Maximum length: 100.
Additional fields are not accepted.
subjectOptional.birthDate - string
Known date or partial date: YYYY, YYYY-MM or YYYY-MM-DD. Preserve known precision; do not invent a month or day. Year 0000 and invalid dates are rejected.
subject.birthDate fields and rules
Allowed alternatives
- string
Pattern: ^(?!0000)\d{4}$.
- string
Pattern: ^(?!0000)\d{4}-(0[1-9]|1[0-2])$.
- string
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$.
Pattern: ^(?!0000).
- string
subjectOptional.country - string
Known country name or code used as supporting identity evidence. It is not a source-selection or geographic coverage filter.
Minimum length: 2. Maximum length: 100.
Additional fields are not accepted.
- null
May be null.
- Subject
referenceRequired- string or null
May be null.
reference fields and rules
Allowed alternatives
- string
- null
May be null.