Integrate Deceased Check

Before you start

Make sure your RiskOS™ environment is provisioned with:

Choose your environment

Start with Sandbox for development and testing, then move to Production for live applications.

https://riskos.sandbox.socure.com/api/evaluation

https://riskos.socure.com/api/evaluation

Get an API key

  1. In the Sandbox RiskOS™ Dashboard, go to Developer Workbench > API Keys.

  2. Copy your API key securely.

  3. In the Production RiskOS™ Dashboard, go to Developer Workbench > API Keys.

  4. Copy your API key securely.

How it works

  1. Send a POST request to /api/evaluation with identity data.
  2. Socure runs the request through the configured RiskOS™ workflow with the Deceased Check enrichment.
  3. Receive a decision (ACCEPT, REVIEW, or REJECT) and supporting metadata.
  4. Apply your routing logic based on the result (e.g., flag if reason code R907 or R909 is returned).

Start a new evaluation

Endpoint

SandboxProduction

POST https://riskos.sandbox.socure.com/api/evaluation

POST https://riskos.socure.com/api/evaluation

Authentication and headers

Include your API key in the Authorization header as a Bearer token, along with standard JSON headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json
X-API-Version: 2025-01-01.orion   # optional – pins a specific API version

Example request

{
  "id": "APP-123456",
  "timestamp": "2022-07-28T06:10:54.298Z",
  "workflow": "consumer_onboarding",
  "data": {
    "individual": {
      "given_name": "Jessica",
      "family_name": "Roberts",
      "national_id": "123456789",
      "date_of_birth": "1943-09-19",
      "email": "j.roberts@example.com",
      "phone_number": "+13475551234",
      "address": {
        "line_1": "234 Main Street",
        "line_2": "Apt. 3C",
        "locality": "Jersey City",
        "major_admin_division": "NJ",
        "country": "US",
        "postal_code": "07307"
      },
      "additional_context": {
        "user_consent": true,
        "consent_timestamp": "2020-05-26T13:34:43Z"
      }
    }
  }
}

curl --location --request POST 'https://riskos.sandbox.socure.com/api/evaluation' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
  "id": "APP-123456",
  "timestamp": "2022-07-28T06:10:54.298Z",
  "workflow": "consumer_onboarding",
  "data": {
    "individual": {
      "given_name": "Jessica",
      "family_name": "Roberts",
      "national_id": "123456789",
      "date_of_birth": "1943-09-19",
      "email": "j.roberts@example.com",
      "phone_number": "+13475551234",
      "address": {
        "line_1": "234 Main Street",
        "line_2": "Apt. 3C",
        "locality": "Jersey City",
        "major_admin_division": "NJ",
        "country": "US",
        "postal_code": "07307"
      },
      "additional_context": {
        "user_consent": true,
        "consent_timestamp": "2020-05-26T13:34:43Z"
      }
    }
  }
}'

Request schema

Top-level fields

Field Type Required Description Example
id String Required Required, customer-defined unique identifier for the request.
This value must be unique for each evaluation. Reusing an ID causes RiskOS™ to treat the request as a re-run and can impact processing behavior, results, and downstream workflows.		 "APP-123456"
timestamp String Required Timestamp when the evaluation was initiated. "2022-07-28T06:10:54.298Z"
workflow String Required RiskOS™ workflow name configured in your environment.
Note: The workflow name must be unique within your RiskOS™ environment. It is not scoped by use case and must identify a single active workflow for each Evaluation API request.		 "consumer_onboarding"
data Object Required Main payload containing applicant or business information.
→ individual Object Required Primary identity object containing personal information. See individual schema below.

individual fields

Field Type Required Description Example
given_name String Required Applicant’s first name (omit prefixes like Mr., Ms.). "Jessica"
family_name String Required Applicant’s last name (omit suffixes like Jr., III). "Roberts"
national_id String Conditional U.S. SSN (full or last 4 digits); improves precision for identity resolution. "123456789"
date_of_birth String Conditional Date of birth (YYYY-MM-DD, YYYYMMDD, or YYYY/MM/DD). "1943-09-19"
address Object Conditional Street, city, state (ISO 3166-2), postal code, and country (ISO 3166-1 alpha-2). See address schema below.
phone_number String Optional Applicant’s phone number in E.164 format. The API expects the standard E.164 format but tolerates hyphens and spaces for user convenience. "+13475551234"
additional_context Object Conditional Provides supplementary metadata for RiskOS™ workflows (e.g., consent info). See additional_context schema below.

address fields

Field Type Required Description Example
line_1 String Optional Street number/house name and street. "234 Main Street"
line_2 String Optional Additional address data (apartment, landmarks). "Apt. 3C"
locality String Optional City, town, or village. "Jersey City"
minor_admin_division String Optional District or borough. null
major_admin_division String Optional State or province code (ISO 3166-2). "NJ"
country String (ISO 3166-1 alpha-2) Optional Country code. "US"
postal_code String Optional Postal or ZIP code. "07307"

additional_context fields

Field Type Required Description
user_consent Boolean Required Indicates whether the user provided consent.
consent_timestamp String <date-time> Optional The date and time when the user provided consent, specified in ISO 8601 / RFC 3339 format. If not provided, defaults to the current transaction timestamp.

Example response

When you call the Evaluation API, RiskOS™ returns a JSON payload that includes the final decision, evaluation metadata, and enrichment-specific results.

{
  "id": "APP-123456",
  "eval_id": "6dc8f39c-ecc3-4fe0-9283-fc8e5f99e816",
  "workflow": "consumer_onboarding",
  "workflow_id": "dc7f261e-b158-477e-9770-7e4eae066156",
  "workflow_version": "28.16.0",
  "status": "CLOSED",
  "sub_status": "Review",
  "decision": "REVIEW",
  "decision_at": "2025-10-07T23:50:03.738648201Z",
  "tags": [],
  "review_queues": [],
  "data_enrichments": [
    {
      "enrichment_name": "Socure Deceased Check",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {},
      "response": {
        "referenceId": "f3863a33-69ca-43c2-90e0-8b4344a41a09",
        "deceasedCheck": {
          "socureId": "46fd3b11-a130-4915-8cc4-074bbd799669",
          "reasonCodes": [
            "R909",
            "R907"
          ],
          "firstName": "Jessica",
          "middleName": "Marie",
          "surName": "Roberts",
          "nationalId": "123456789",
          "dob": "1943-09-19",
          "dod": "2022-11-19",
          "age": 79,
          "sourceAttribution": [
            "Probate"
          ]
        },
        "customerProfile": {
          "userId": "u-1a2b3c4d",
          "customerUserId": "cust-98765"
        }
      }
    }
  ]
}

Key response fields

RiskOS™ returns a consistent set of top-level fields that describe the outcome of an evaluation, along with enrichment-specific results that depend on your workflow configuration.

Where to find specific results

Area Fields How to use it
Decision and routing decision, decision_at, tags, review_queues, notes, score Primary control signals. Branch application logic using decision. Use tags, queues, notes and score for secondary routing, review, and explanation.
Module results Module-specific fields (for example: reasonCodes, scores, extracted attributes) Evidence and signals produced by workflow modules. Use for escalation, compliance review, investigation, and audit.
Identifiers and traceability id, eval_id Persist these identifiers to correlate API calls, logs, webhooks, GET requests, and support cases.
Enrichment execution data_enrichments[] (response, status_code, total_attempts, is_source_cache) Inspect enrichment outputs and detect provisioning issues, partial failures, retries, or cached responses.
Workflow context workflow, workflow_id, workflow_version Understand which workflow ran and which version produced the result. Useful for debugging and historical analysis.
Evaluation lifecycle eval_status, status, sub_status Execution and case state only. Useful for monitoring and asynchronous workflows. Do not use for business decisions.
Execution context eval_source, eval_start_time, eval_end_time, environment_name Observability and performance metadata for latency tracking, environment validation, and API vs Dashboard attribution.

Evaluation lifecycle and status

Field Type Description Example
eval_status String (enum) Indicates the current state of an evaluation in RiskOS™.
Possible values:
• evaluation_completed
• evaluation_paused
• evaluation_in_progress		 evaluation_completed
status String (enum) Indicates the current state of an evaluation or case.
Possible values:
• OPEN
• CLOSED		 `