API REFERENCE · Screening and evidence

Screen one subject against explicitly selected coverage

Complete request parameters, body fields, response formats, examples, and errors for POST /screenings.

Base URL: https://www.sanctionskit.com/api/v1. Documentation examples are saved and require no API key to read.

POST/screeningsScreen one subject against explicitly selected coverage

Authentication: Authorization: Bearer YOUR_API_KEY (required). Use a server-side key for the intended environment and scopes.

Required API key scope: screenings:write. Standard retention saves subject details and evidence for review. Only individual API-key requests can choose minimal retention: the reduced result lasts 24 hours, omits submitted subject inputs, and cannot create a review case. Dashboard requests require standard retention. Organization or policy requirements for review, external checks or event-triggered retention reject minimal mode with standard_retention_required. Governed no-match results can create required due-diligence cases.

Request parameters

Path parameters: None.
Query parameters: None.
Headers: Authorization (required), Idempotency-Key
JSON body fields: subject, counterpartyId, policy, reference, sources, package, retention

Send JSON body fields as application/json, not as query parameters. Field definitions and nested properties follow below.

Headers, path and query parameters

Idempotency-KeyheaderRequired

string

Reuse for identical retries. Reuse with different input returns 409.

Pattern: ^[\w:.-]{8,128}$. Minimum length: 8. Maximum length: 128.

Request body

Required body. JSON properties belong in the request body, separately from headers and URL parameters.

JSON request body. Send Content-Type: application/json with UTF-8 encoding; fields marked required must be present. Omit optional fields unless needed. Null is accepted only where explicitly shown. Unknown properties are rejected for validated request objects. Duplicate keys and nesting beyond 32 levels are rejected. Maximum body size: 1,048,576 bytes (1 MiB).

application/jsonView ScreeningRequest schema

Request body fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

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.

subjectRequired

object

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

subject fields and rules

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.

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

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.

policy fields and rules

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

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.

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.

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.

sources item fields

Each array item: string.

Minimum length: 1. Maximum length: 80.

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.

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 sources. Do not provide package.
Provide package. Do not provide sources.

Additional fields are not accepted.

Example request

{
  "subject": {
    "name": "Alex Morgan",
    "entityType": "person"
  },
  "package": "sandbox@1",
  "retention": "standard"
}

Responses

201Successful response. JSON object with the required data key. All properties marked required are present, including keys whose value may be null. Unmarked properties can be omitted; clients should tolerate additional response properties.

Response headers

X-Request-Id

string

Server-generated request correlation identifier.

Format: uuid.

application/json

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

dataRequired

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

data fields and rules

data.idRequired

string

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

Format: uuid.

data.environmentRequired

enum

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

Values: "sandbox", "production".

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

data.createdAtRequired

string

Screening creation timestamp in ISO 8601 UTC.

Format: date-time.

data.matchesRequired

object[]

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

data.matches item fields

Each array item: object.

data.matches[].recordRequired

objectView SourceRecord schema

data.matches[].record fields and rules

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

data.matches[].scoreRequired

number

Similarity measure, not probability of wrongdoing.

Minimum: 0. Maximum: 100.

data.matches[].evidenceRequired

object[]

data.matches[].evidence item fields

Each array item: object.

data.matches[].evidence[].fieldRequired: string
data.matches[].evidence[].queryValueRequired: string
data.matches[].evidence[].sourceValueRequired: string
data.matches[].evidence[].methodRequired: string
data.matches[].evidence[].contributionRequired: number
data.matches[].evidence[].explanationRequired: string

data.matches[].conflictsRequired

string[]

data.matches[].conflicts item fields

Each array item: string.

data.coverageRequired

Coverage[]

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

data.coverage item fields

Each array item: Coverage.

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

data.versionsRequired

object

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

data.versions fields and rules

data.versions.datasetRequired: string
data.versions.matchingEngineRequired: string
data.versions.policyRequired: string
data.versions.packageOptional: string

data.disclaimerRequired

string

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

data.policySnapshotOptional

object

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

View ScreeningPolicySnapshot schema

data.policySnapshot fields and rules

data.policySnapshot.nameRequired

string

Minimum length: 2. Maximum length: 120.

data.policySnapshot.purposeRequired

string

Minimum length: 3. Maximum length: 1000.

data.policySnapshot.jurisdictionsRequired

string[]

Minimum items: 1. Maximum items: 30.

data.policySnapshot.jurisdictions item fields

Each array item: string.

Minimum length: 2. Maximum length: 100.

data.policySnapshot.requiredSourcesRequired

object

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

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

data.policySnapshot.optionalSourcesRequired

object

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

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

data.policySnapshot.exclusionsRequired

string[]

Maximum items: 30. Default: [].

data.policySnapshot.exclusions item fields

Each array item: string.

Minimum length: 3. Maximum length: 500.

data.policySnapshot.externalChecksRequired

string[]

Maximum items: 20. Default: [].

data.policySnapshot.externalChecks item fields

Each array item: string.

Minimum length: 3. Maximum length: 200.

data.policySnapshot.externalCheckGuidanceOptional

object[]

Maximum items: 20.

data.policySnapshot.externalCheckGuidance item fields

Each array item: object.

data.policySnapshot.externalCheckGuidance[].labelRequired: string
Minimum length: 3. Maximum length: 200.
data.policySnapshot.externalCheckGuidance[].instructionsRequired: string
Minimum length: 3. Maximum length: 2000.
data.policySnapshot.externalCheckGuidance[].evidenceExampleOptional: string
Minimum length: 3. Maximum length: 1000.

Additional fields are not accepted.

data.policySnapshot.reviewRequired

object

Default: {}.

data.policySnapshot.review fields and rules

data.policySnapshot.review.requireSecondReviewOptional: boolean
Default: false.
data.policySnapshot.review.secondReviewForOptional: string[]
Maximum items: 4. Default: [].; data.policySnapshot.review.secondReviewFor item fields
Each array item: string.
Values: "same_identity", "allow", "restrict", "escalate".
data.policySnapshot.review.approverRolesOptional: string[]
Minimum items: 1. Maximum items: 3. Default: ["owner","admin","analyst"].; data.policySnapshot.review.approverRoles item fields
Each array item: string.
Values: "owner", "admin", "analyst".

Additional fields are not accepted.

data.policySnapshot.monitoringIntervalHoursRequired

6 or 24 or 168

Default: 24.

data.policySnapshot.monitoringIntervalHours fields and rules

Allowed alternatives

6
Must equal 6.
24
Must equal 24.
168
Must equal 168.

data.policySnapshot.retentionTriggerRequired

string

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

data.policySnapshot.idRequired

string

Format: uuid.

data.policySnapshot.versionRequired

integer

Minimum: 0.

data.policySnapshot.environmentRequired

string

Values: "sandbox", "production".

data.policySnapshot.createdAtRequired

string

Format: date-time.

Additional fields are not accepted.

Example response

Recorded from the real application handler against an isolated synthetic database. IDs, times and nonfunctional temporary secrets are normalized. No customer data or live provider request.

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "environment": "sandbox",
    "status": "no_match",
    "createdAt": "2026-09-17T12:00:00.000Z",
    "matches": [],
    "coverage": [
      {
        "sourceId": "sandbox-synthetic",
        "version": "1",
        "retrievedAt": "2026-09-17T12:00:00.000Z",
        "fresh": true
      }
    ],
    "versions": {
      "dataset": "sandbox-synthetic-v1",
      "matchingEngine": "deterministic-1.1.1",
      "policy": "review-1.1.0",
      "package": "sandbox@1"
    },
    "disclaimer": "Potential matches support analyst review. No match means no match in the selected sources and dataset, not legal clearance. Scores are similarity measures, not probabilities of wrongdoing."
  }
}

Potential match from the real engine against synthetic sandbox records

Recorded from the real application handler against an isolated synthetic database. IDs, times and nonfunctional temporary secrets are normalized. No customer data or live provider request.

{
  "data": {
    "policySnapshot": {
      "name": "Synthetic onboarding policy",
      "purpose": "Document vendor onboarding checks",
      "jurisdictions": [
        "Example jurisdiction"
      ],
      "requiredSources": {},
      "optionalSources": {},
      "exclusions": [],
      "externalChecks": [
        "Ownership review"
      ],
      "review": {
        "requireSecondReview": false,
        "secondReviewFor": [],
        "approverRoles": [
          "owner",
          "admin",
          "analyst"
        ]
      },
      "monitoringIntervalHours": 24,
      "retentionTrigger": "business_event",
      "id": "00000000-0000-4000-8000-000000000001",
      "version": 1,
      "environment": "sandbox",
      "createdAt": "2026-09-17T12:00:00.000Z"
    },
    "id": "00000000-0000-4000-8000-000000000002",
    "environment": "sandbox",
    "status": "potential_match",
    "createdAt": "2026-09-17T12:00:00.000Z",
    "matches": [
      {
        "record": {
          "id": "sandbox:person-001",
          "sourceId": "sandbox-synthetic",
          "authority": "SanctionsKit synthetic examples",
          "list": "Synthetic demonstration records",
          "sourceUrl": "https://sanctionskit.com/demo",
          "entityType": "person",
          "names": [
            {
              "value": "Alex Morgan",
              "kind": "primary"
            },
            {
              "value": "Алекс Морган",
              "kind": "alias"
            }
          ],
          "identifiers": [
            {
              "type": "passport",
              "value": "DEMO-001",
              "issuer": "Fictional authority"
            }
          ],
          "birthDates": [
            {
              "value": "1984",
              "precision": "year",
              "original": "1984"
            }
          ],
          "addresses": [],
          "nationalities": [],
          "designations": [
            {
              "category": "other",
              "programs": [
                "Synthetic demonstration only"
              ],
              "legalReferences": [],
              "wording": "Invented example, not a government designation."
            }
          ],
          "extensions": {
            "synthetic": true
          }
        },
        "score": 96,
        "evidence": [
          {
            "field": "name",
            "queryValue": "Alex Morgan",
            "sourceValue": "Alex Morgan",
            "method": "normalized_name_exact",
            "contribution": 96,
            "explanation": "Name similarity is a review signal, not a probability or finding of wrongdoing."
          }
        ],
        "conflicts": []
      }
    ],
    "coverage": [
      {
        "sourceId": "sandbox-synthetic",
        "version": "1",
        "retrievedAt": "2026-09-17T12:00:00.000Z",
        "fresh": true
      }
    ],
    "versions": {
      "dataset": "sandbox-synthetic-v1",
      "matchingEngine": "deterministic-1.1.1",
      "policy": "review-1.1.0",
      "package": "sandbox@1"
    },
    "disclaimer": "Potential matches support analyst review. No match means no match in the selected sources and dataset, not legal clearance. Scores are similarity measures, not probabilities of wrongdoing."
  }
}

400invalid_request — Correct the request fields, resource identifiers, JSON body or query parameters before retrying. idempotency_key_required — Include an Idempotency-Key matching this operation’s documented format. sandbox_coverage_required — Use package sandbox@1 in the sandbox; choose approved sources or a qualified package in production.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

Optional JSON details for client and validation failures. Validation failures return an array of { path, message } issues; other 4xx codes may return a code-specific object. Server failures omit details. Never assume this key is present.

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Recorded from the real application handler against an isolated synthetic database. IDs, times and nonfunctional temporary secrets are normalized. No customer data or live provider request.

{
  "error": {
    "code": "sandbox_coverage_required",
    "message": "Sandbox accepts only the explicitly synthetic sandbox@1 package.",
    "requestId": "00000000-0000-4000-8000-000000000001"
  }
}

Mutations require an idempotency key

Recorded from the real application handler against an isolated synthetic database. IDs, times and nonfunctional temporary secrets are normalized. No customer data or live provider request.

{
  "error": {
    "code": "idempotency_key_required",
    "message": "Provide an Idempotency-Key of 8 to 128 URL-safe characters.",
    "requestId": "00000000-0000-4000-8000-000000000001"
  }
}

Invalid subject input is rejected before screening

Recorded from the real application handler against an isolated synthetic database. IDs, times and nonfunctional temporary secrets are normalized. No customer data or live provider request.

{
  "error": {
    "code": "invalid_request",
    "message": "The request is invalid.",
    "requestId": "00000000-0000-4000-8000-000000000001",
    "details": [
      {
        "path": "subject.name",
        "message": "Too small: expected string to have >=2 characters"
      }
    ]
  }
}

invalid request

Synthetic error example. Correct the request fields, resource identifiers, JSON body or query parameters before retrying.

{
  "error": {
    "code": "invalid_request",
    "message": "The request is invalid.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

idempotency key required

Synthetic error example. Include an Idempotency-Key matching this operation’s documented format.

{
  "error": {
    "code": "idempotency_key_required",
    "message": "Provide an Idempotency-Key of 8 to 128 URL-safe characters.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

sandbox coverage required

Synthetic error example. Use package sandbox@1 in the sandbox; choose approved sources or a qualified package in production.

{
  "error": {
    "code": "sandbox_coverage_required",
    "message": "Sandbox accepts only the explicitly synthetic sandbox@1 package.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

401authentication_required — Send Authorization: Bearer with a valid API key. An omitted header can produce authentication_required; invalid supplied credentials produce invalid_api_key. invalid_api_key — Use an active key for the intended environment.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

WWW-Authenticate

string

Bearer authentication challenge.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Recorded from the real application handler against an isolated synthetic database. IDs, times and nonfunctional temporary secrets are normalized. No customer data or live provider request.

{
  "error": {
    "code": "invalid_api_key",
    "message": "A valid Bearer API key is required.",
    "requestId": "00000000-0000-4000-8000-000000000001"
  }
}

authentication required

Synthetic error example. Send Authorization: Bearer with a valid API key. An omitted header can produce authentication_required; invalid supplied credentials produce invalid_api_key.

{
  "error": {
    "code": "authentication_required",
    "message": "Sign in to continue.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

invalid api key

Synthetic error example. Use an active key for the intended environment.

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is invalid, expired, or revoked.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

402subscription_required — Use the synthetic sandbox or arrange an active production subscription before retrying.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Synthetic error example. Use the synthetic sandbox or arrange an active production subscription before retrying.

{
  "error": {
    "code": "subscription_required",
    "message": "An active subscription is required for production screening.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

403permission_denied — Ask an organization owner to grant the required role or API-key scope. insufficient_scope — Use a key with the scope stated in this operation.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Recorded from the real application handler against an isolated synthetic database. IDs, times and nonfunctional temporary secrets are normalized. No customer data or live provider request.

{
  "error": {
    "code": "permission_denied",
    "message": "Your role does not allow this action.",
    "requestId": "00000000-0000-4000-8000-000000000001"
  }
}

permission denied

Synthetic error example. Ask an organization owner to grant the required role or API-key scope.

{
  "error": {
    "code": "permission_denied",
    "message": "Your role does not allow this action.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

insufficient scope

Synthetic error example. Use a key with the scope stated in this operation.

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key does not grant this action.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

404not_found — Check the identifier and selected environment. The resource must belong to your organization and remain available.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Synthetic error example. Check the identifier and selected environment. The resource must belong to your organization and remain available.

{
  "error": {
    "code": "not_found",
    "message": "Counterparty not found.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

405method_not_allowed — Use a method in the Allow response header. OPTIONS lists supported methods; HEAD follows GET authorization and returns no body.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

Allow

string

Comma-separated supported HTTP methods.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Synthetic error example. Use a method in the Allow response header. OPTIONS lists supported methods; HEAD follows GET authorization and returns no body.

{
  "error": {
    "code": "method_not_allowed",
    "message": "This method is not supported for this endpoint.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

408invalid_request — Reconnect and retry using the same idempotency key and identical input where supported.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Synthetic error example. Reconnect and retry using the same idempotency key and identical input where supported.

{
  "error": {
    "code": "invalid_request",
    "message": "The request body was not received within 10 seconds.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

409idempotency_conflict — Reuse a key only with identical input. Use a new key for genuinely new work. screening_policy_changed — Reload GET /policies and use the current version after reviewing its coverage. counterparty_archived — Restore the active identity or omit the optional counterparty link. counterparty_changed — Reload the counterparty and use its current subject; names do not automatically merge identities.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Recorded from the real application handler against an isolated synthetic database. IDs, times and nonfunctional temporary secrets are normalized. No customer data or live provider request.

{
  "error": {
    "code": "idempotency_conflict",
    "message": "This idempotency key was used with a different request.",
    "requestId": "00000000-0000-4000-8000-000000000001"
  }
}

idempotency conflict

Synthetic error example. Reuse a key only with identical input. Use a new key for genuinely new work.

{
  "error": {
    "code": "idempotency_conflict",
    "message": "This idempotency key was used with a different request.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

screening policy changed

Synthetic error example. Reload GET /policies and use the current version after reviewing its coverage.

{
  "error": {
    "code": "screening_policy_changed",
    "message": "The policy has a newer version. Review its coverage before screening again.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

counterparty archived

Synthetic error example. Restore the active identity or omit the optional counterparty link.

{
  "error": {
    "code": "counterparty_archived",
    "message": "Restore this counterparty before screening it.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

counterparty changed

Synthetic error example. Reload the counterparty and use its current subject; names do not automatically merge identities.

{
  "error": {
    "code": "counterparty_changed",
    "message": "Screening input differs from the current counterparty identity.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

410result_expired — Run a new screening and review its retained evidence. Expired evidence is not reconstructed.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Synthetic error example. Run a new screening and review its retained evidence. Expired evidence is not reconstructed.

{
  "error": {
    "code": "result_expired",
    "message": "The evidence has expired. Run a new screening before reviewing it.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

413response_too_large — Reduce the requested page size or use the documented segmented case archive. No evidence is silently truncated. invalid_request — Reduce the JSON request size to the documented limit.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Recorded from the real application handler against an isolated synthetic database. IDs, times and nonfunctional temporary secrets are normalized. No customer data or live provider request.

{
  "error": {
    "code": "invalid_request",
    "message": "The request body exceeds this endpoint's size limit.",
    "requestId": "00000000-0000-4000-8000-000000000001"
  }
}

response too large

Synthetic error example. Reduce the requested page size or use the documented segmented case archive. No evidence is silently truncated.

{
  "error": {
    "code": "response_too_large",
    "message": "This response exceeds the size limit. Request a smaller page or a segmented export.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

invalid request

Synthetic error example. Reduce the JSON request size to the documented limit.

{
  "error": {
    "code": "invalid_request",
    "message": "REQUEST_TOO_LARGE",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

415invalid_request — Use Content-Type: application/json and an uncompressed UTF-8 body.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Synthetic error example. Use Content-Type: application/json and an uncompressed UTF-8 body.

{
  "error": {
    "code": "invalid_request",
    "message": "Send application/json with UTF-8 encoding.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

422standard_retention_required — Use standard retention for required review, external checks or business-event retention. screening_policy_required — Load GET /policies and supply the current id and version with the required coverage. policy_entity_type_unsupported — Choose an approved policy with required sources for this subject type. policy_coverage_mismatch — For production policy-based requests use explicit sources, include all required sources and only permitted optional sources; do not substitute a package. screening_policy_unavailable — Reload the current policy before retrying. Do not substitute a different scope silently. invalid_coverage — Check GET /sources and select coverage available to the requested environment and subject type. unsupported_entity_type — Check source capabilities and remove incompatible sources, or choose coverage for this subject type. matching_variant_limit — Provide a more precise name or identifier and retry. candidate_limit_exceeded — Add reliable identifying information before screening again. No all-clear result was produced. result_too_large — Use more precise screening input. Large results are rejected rather than silently truncated.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Synthetic error example. Use standard retention for required review, external checks or business-event retention.

{
  "error": {
    "code": "standard_retention_required",
    "message": "The organization or screening policy requires retained evidence.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

screening policy required

Synthetic error example. Load GET /policies and supply the current id and version with the required coverage.

{
  "error": {
    "code": "screening_policy_required",
    "message": "Choose an approved organization screening policy.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

policy entity type unsupported

Synthetic error example. Choose an approved policy with required sources for this subject type.

{
  "error": {
    "code": "policy_entity_type_unsupported",
    "message": "This policy has no required coverage for the selected subject type.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

policy coverage mismatch

Synthetic error example. For production policy-based requests use explicit sources, include all required sources and only permitted optional sources; do not substitute a package.

{
  "error": {
    "code": "policy_coverage_mismatch",
    "message": "Include every required source and only permitted optional sources for this policy.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

screening policy unavailable

Synthetic error example. Reload the current policy before retrying. Do not substitute a different scope silently.

{
  "error": {
    "code": "screening_policy_unavailable",
    "message": "The selected policy version is unavailable.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

invalid coverage

Synthetic error example. Check GET /sources and select coverage available to the requested environment and subject type.

{
  "error": {
    "code": "invalid_coverage",
    "message": "Choose a supported coverage package or explicit sources.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

unsupported entity type

Synthetic error example. Check source capabilities and remove incompatible sources, or choose coverage for this subject type.

{
  "error": {
    "code": "unsupported_entity_type",
    "message": "The selected source does not support this subject type. No screening was completed.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

matching variant limit

Synthetic error example. Provide a more precise name or identifier and retry.

{
  "error": {
    "code": "matching_variant_limit",
    "message": "This name has too many spelling variants for complete screening. No screening was completed.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

candidate limit exceeded

Synthetic error example. Add reliable identifying information before screening again. No all-clear result was produced.

{
  "error": {
    "code": "candidate_limit_exceeded",
    "message": "This query has too many candidates for reliable screening. Add a precise identifier or more complete name.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

result too large

Synthetic error example. Use more precise screening input. Large results are rejected rather than silently truncated.

{
  "error": {
    "code": "result_too_large",
    "message": "A retained result exceeds the response size limit. No matches were truncated or skipped.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

429rate_limited — Wait for the request window to reset and retry with backoff. usage_cap_reached — Wait for the allowance reset or have an owner review the configured cap and plan.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

Retry-After

string

When present, a delay in seconds or an HTTP-date before which the client should not retry. Service-unavailable responses default to a one-second delay unless another safe value is supplied. A usage allowance error may require quota recovery instead of retrying.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Recorded from the real application handler against an isolated synthetic database. IDs, times and nonfunctional temporary secrets are normalized. No customer data or live provider request.

{
  "error": {
    "code": "rate_limited",
    "message": "The per-minute request limit has been reached.",
    "requestId": "00000000-0000-4000-8000-000000000001",
    "details": {
      "retryAfterSeconds": 60
    }
  }
}

The configured subject allowance fails closed without charging overage

Recorded from the real application handler against an isolated synthetic database. IDs, times and nonfunctional temporary secrets are normalized. No customer data or live provider request.

{
  "error": {
    "code": "usage_cap_reached",
    "message": "The subject allowance or configured spending cap has been reached. No overage was charged.",
    "requestId": "00000000-0000-4000-8000-000000000001"
  }
}

rate limited

Synthetic error example. Wait for the request window to reset and retry with backoff.

{
  "error": {
    "code": "rate_limited",
    "message": "The per-minute request limit has been reached.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

usage cap reached

Synthetic error example. Wait for the allowance reset or have an owner review the configured cap and plan.

{
  "error": {
    "code": "usage_cap_reached",
    "message": "The subject allowance or configured spending cap has been reached. No overage was charged.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

500internal_error — Retry with backoff. For writes reuse the same idempotency key and identical input; include requestId when contacting support.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Recorded from the real application handler against an isolated synthetic database. IDs, times and nonfunctional temporary secrets are normalized. No customer data or live provider request.

{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed.",
    "requestId": "00000000-0000-4000-8000-000000000001"
  }
}

internal error

Synthetic error example. Retry with backoff. For writes reuse the same idempotency key and identical input; include requestId when contacting support.

{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

503screening_busy — Wait for Retry-After, then retry with backoff using the same idempotency key and input. temporarily_unavailable — Honor Retry-After when present and retry with bounded backoff. Follow this endpoint’s retry contract; preserve the same key and input for idempotent writes. Contact support with requestId if the failure persists. coverage_unavailable — Do not treat this failure as no-match. Retry only when the selected coverage is available. stale_coverage — Wait for fresh selected coverage. Do not interpret this failure as a no-match result. production_screening_disabled — Wait until production screening is available; the synthetic sandbox remains separate.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

Retry-After

string

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Recorded from the real application handler against an isolated synthetic database. IDs, times and nonfunctional temporary secrets are normalized. No customer data or live provider request.

{
  "error": {
    "code": "production_screening_disabled",
    "message": "Production screening is temporarily unavailable. No screening was completed.",
    "requestId": "00000000-0000-4000-8000-000000000001"
  }
}

screening busy

Synthetic error example. Wait for Retry-After, then retry with backoff using the same idempotency key and input.

{
  "error": {
    "code": "screening_busy",
    "message": "Screening capacity is temporarily busy. Retry with the same idempotency key.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

temporarily unavailable

Synthetic error example. Honor Retry-After when present and retry with bounded backoff. Follow this endpoint’s retry contract; preserve the same key and input for idempotent writes. Contact support with requestId if the failure persists.

{
  "error": {
    "code": "temporarily_unavailable",
    "message": "The service is temporarily unavailable. Retry shortly.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

coverage unavailable

Synthetic error example. Do not treat this failure as no-match. Retry only when the selected coverage is available.

{
  "error": {
    "code": "coverage_unavailable",
    "message": "The selected coverage is temporarily unavailable. No screening was completed.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

stale coverage

Synthetic error example. Wait for fresh selected coverage. Do not interpret this failure as a no-match result.

{
  "error": {
    "code": "stale_coverage",
    "message": "The selected coverage is stale. No screening was completed.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

production screening disabled

Synthetic error example. Wait until production screening is available; the synthetic sandbox remains separate.

{
  "error": {
    "code": "production_screening_disabled",
    "message": "Production screening is temporarily unavailable. No screening was completed.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

Back to request parameters