API REFERENCE · SCHEMA

ScreeningEvidence 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 schemas
formatRequired
"sanctionskit-evidence@1"

Must equal "sanctionskit-evidence@1".

resultRequired
object

Result returned by POST /screenings and plain GET /results items. Its required fields are always present. A successful result is either potential_match or no_match; failures use the Error envelope instead.

View ScreeningResult schema
result fields and rules
result.idRequired
string

Screening UUID; use it to retrieve retained result/evidence and locate linked review cases.

Format: uuid.

result.environmentRequired
enum

Environment owned by the API key. Sandbox evidence is synthetic.

Values: "sandbox", "production".

result.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".

result.createdAtRequired
string

Screening creation timestamp in ISO 8601 UTC.

Format: date-time.

result.matchesRequired
object[]

Candidate records with field evidence and conflicts. Always an array; empty for no_match. No silent truncation is performed.

result.matches item fields

Each array item: object.

result.matches[].recordRequired
objectView SourceRecord schema
result.matches[].record fields and rules

See all SourceRecord fields for the complete structure, required properties and constraints.

result.matches[].scoreRequired
number

Similarity measure, not probability of wrongdoing.

Minimum: 0. Maximum: 100.

result.matches[].evidenceRequired
object[]
result.matches[].evidence item fields

Each array item: object.

result.matches[].evidence[].fieldRequired
string
result.matches[].evidence[].queryValueRequired
string
result.matches[].evidence[].sourceValueRequired
string
result.matches[].evidence[].methodRequired
string
result.matches[].evidence[].contributionRequired
number
result.matches[].evidence[].explanationRequired
string
result.matches[].conflictsRequired
string[]
result.matches[].conflicts item fields

Each array item: string.

result.coverageRequired
Coverage[]

Exact source versions used, including freshness and retained publisher notices. Always present, including no_match.

result.coverage item fields

Each array item: Coverage.

See all Coverage fields for the complete structure, required properties and constraints.

result.versionsRequired
object

Dataset, matching engine and policy versions used for this result. package is included only for package-based coverage.

result.versions fields and rules
result.versions.datasetRequired
string
result.versions.matchingEngineRequired
string
result.versions.policyRequired
string
result.versions.packageOptional
string
result.disclaimerRequired
string

Interpretation limits supplied with this result; preserve them when presenting or exporting evidence.

result.policySnapshotOptional
object

Immutable organization policy applied at screening time, when one was selected. Omitted when no organization policy applied.

View ScreeningPolicySnapshot schema
result.policySnapshot fields and rules
result.policySnapshot.nameRequired
string

Minimum length: 2. Maximum length: 120.

result.policySnapshot.purposeRequired
string

Minimum length: 3. Maximum length: 1000.

result.policySnapshot.jurisdictionsRequired
string[]

Minimum items: 1. Maximum items: 30.

result.policySnapshot.jurisdictions item fields

Each array item: string.

Minimum length: 2. Maximum length: 100.

result.policySnapshot.requiredSourcesRequired
object

Allowed keys: "person", "organization", "vessel", "aircraft", "other". Default: {}.

result.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.

result.policySnapshot.optionalSourcesRequired
object

Allowed keys: "person", "organization", "vessel", "aircraft", "other". Default: {}.

result.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.

result.policySnapshot.exclusionsRequired
string[]

Maximum items: 30. Default: [].

result.policySnapshot.exclusions item fields

Each array item: string.

Minimum length: 3. Maximum length: 500.

result.policySnapshot.externalChecksRequired
string[]

Maximum items: 20. Default: [].

result.policySnapshot.externalChecks item fields

Each array item: string.

Minimum length: 3. Maximum length: 200.

result.policySnapshot.externalCheckGuidanceOptional
object[]

Maximum items: 20.

result.policySnapshot.externalCheckGuidance item fields

Each array item: object.

result.policySnapshot.externalCheckGuidance[].labelRequired
string

Minimum length: 3. Maximum length: 200.

result.policySnapshot.externalCheckGuidance[].instructionsRequired
string

Minimum length: 3. Maximum length: 2000.

result.policySnapshot.externalCheckGuidance[].evidenceExampleOptional
string

Minimum length: 3. Maximum length: 1000.

Additional fields are not accepted.

result.policySnapshot.reviewRequired
object

Default: {}.

result.policySnapshot.review fields and rules
result.policySnapshot.review.requireSecondReviewOptional
boolean

Default: false.

result.policySnapshot.review.secondReviewForOptional
string[]

Maximum items: 4. Default: [].

result.policySnapshot.review.secondReviewFor item fields

Each array item: string.

Values: "same_identity", "allow", "restrict", "escalate".

result.policySnapshot.review.approverRolesOptional
string[]

Minimum items: 1. Maximum items: 3. Default: ["owner","admin","analyst"].

result.policySnapshot.review.approverRoles item fields

Each array item: string.

Values: "owner", "admin", "analyst".

Additional fields are not accepted.

result.policySnapshot.monitoringIntervalHoursRequired
6 or 24 or 168

Default: 24.

result.policySnapshot.monitoringIntervalHours fields and rules

Allowed alternatives

  • 6

    Must equal 6.

  • 24

    Must equal 24.

  • 168

    Must equal 168.

result.policySnapshot.retentionTriggerRequired
string

Values: "review_completed", "relationship_ended", "business_event". Default: "review_completed".

result.policySnapshot.idRequired
string

Format: uuid.

result.policySnapshot.versionRequired
integer

Minimum: 0.

result.policySnapshot.environmentRequired
string

Values: "sandbox", "production".

result.policySnapshot.createdAtRequired
string

Format: date-time.

Additional fields are not accepted.

retentionRequired
string

Values: "standard", "minimal".

expires_atRequired
string or null

Null while evidence is protected by an open review, unrecorded retention trigger or indefinite hold; inspect case governance.

May be null.

expires_at fields and rules

Allowed alternatives

  • string

    Format: date-time.

  • null

    May be null.

subjectRequired
Subject or null

Retained subject; null for minimal retention or when no subject was retained.

May be null.

subject fields and rules

Allowed alternatives

  • Subject
    subject.nameRequired
    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.

    subject.entityTypeOptional
    string

    Type of subject. Defaults to person when omitted. Every selected source must support this type.

    Values: "person", "organization", "vessel", "aircraft", "other". Default: "person".

    subject.identifiersOptional
    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.

    subject.identifiers[].typeRequired
    string

    Identifier scheme, such as passport, national_id, registration, lei, imo or mmsi. Matching normalizes supported scheme aliases.

    Minimum length: 1. Maximum length: 80.

    subject.identifiers[].valueRequired
    string

    Identifier value. Send the original value; scheme-specific normalization is applied during matching.

    Minimum length: 1. Maximum length: 160.

    subject.identifiers[].issuerOptional
    string

    Optional issuing authority or country. Omit when unknown; do not send null.

    Minimum length: 1. Maximum length: 100.

    Additional fields are not accepted.

    subject.birthDateOptional
    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).

    subject.countryOptional
    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.

referenceRequired
string or null

Retained caller reference; null for minimal retention or if absent.

May be null.

reference fields and rules

Allowed alternatives

  • string
  • null

    May be null.

requestRequired
ScreeningRequest or null

Retained complete request; null for minimal retention or when inputs were not retained.

May be null.

request fields and rules

Allowed alternatives

  • ScreeningRequest

    Single subject input. Exactly one of sources or package is required. Only subject is unconditionally required; coverage and approved policy also have conditional requirements described below.

    request.subjectRequired
    object

    Identity to screen. name is required; entityType defaults to person and identifiers defaults to an empty array.

    request.subject fields and rules
    request.subject.nameRequired
    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.

    request.subject.entityTypeOptional
    string

    Type of subject. Defaults to person when omitted. Every selected source must support this type.

    Values: "person", "organization", "vessel", "aircraft", "other". Default: "person".

    request.subject.identifiersOptional
    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: [].

    request.subject.identifiers item fields

    Each array item: object.

    request.subject.identifiers[].typeRequired
    string

    Identifier scheme, such as passport, national_id, registration, lei, imo or mmsi. Matching normalizes supported scheme aliases.

    Minimum length: 1. Maximum length: 80.

    request.subject.identifiers[].valueRequired
    string

    Identifier value. Send the original value; scheme-specific normalization is applied during matching.

    Minimum length: 1. Maximum length: 160.

    request.subject.identifiers[].issuerOptional
    string

    Optional issuing authority or country. Omit when unknown; do not send null.

    Minimum length: 1. Maximum length: 100.

    Additional fields are not accepted.

    request.subject.birthDateOptional
    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.

    request.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).

    request.subject.countryOptional
    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.

    request.counterpartyIdOptional
    string

    Optional existing active counterparty UUID in the same organization and environment. The submitted subject must match its current identity; this does not create a counterparty.

    Format: uuid. Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$.

    request.policyConditional
    object

    Approved organization policy reference. Required when GET /policies returns requirePolicy=true. A supplied policy must be current and compatible with the subject and requested coverage.

    Required when GET /policies returns requirePolicy=true for the current API key environment.

    request.policy fields and rules
    request.policy.idRequired
    string

    Policy UUID from GET /policies.

    Format: uuid. Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$.

    request.policy.versionRequired
    integer

    Exact approved policy version from GET /policies. Reload the policy if that version is no longer available.

    Maximum: 9007199254740991. Must be greater than 0.

    Additional fields are not accepted.

    request.referenceOptional
    string

    Optional caller reference (up to 160 characters). It is retained with standard evidence and returned by GET /results/{id}; it is null in minimal-retention retrieval.

    Maximum length: 160.

    request.sourcesConditional
    string[]

    Explicit source IDs from GET /sources. Provide sources or package, exactly one. Every selected source must be available, fresh and support the subject type; unavailable coverage fails closed.

    Minimum items: 1. Maximum items: 512.

    request.sources item fields

    Each array item: string.

    Minimum length: 1. Maximum length: 80.

    request.packageConditional
    string

    One versioned coverage package, mutually exclusive with sources. Sandbox accepts only sandbox@1. Use only a package available to the selected environment; no implicit global coverage is applied.

    Minimum length: 1. Maximum length: 80.

    request.retentionOptional
    string

    standard retains inputs and evidence under organization/case policy. minimal is available only for individual API-key screenings, lasts 24 hours, omits submitted inputs, and cannot create a review case. Governance requirements can require standard. Defaults to standard.

    Values: "standard", "minimal". Default: "standard".

    Choose exactly one option

    • Provide request.sources. Do not provide request.package.
    • Provide request.package. Do not provide request.sources.

    Additional fields are not accepted.

  • null

    May be null.

retainedInputsRequired
boolean

Whether both subject and request inputs were retained. A false value means full historical input replay is unavailable.

replayLimitRequired
string or null

Explanation of replay limitations for minimal retention; otherwise null.

May be null.

replayLimit fields and rules

Allowed alternatives

  • string
  • null

    May be null.