Integration Guide

Socure Deceased Check API integration guide

This guide walks you through how to integrate with Socure’s /api/evaluation endpoint using the Deceased Check enrichment. You’ll learn how to send identity data, parse the response, and apply decision logic to support fraud prevention, risk operations, and compliance workflows.

Before you start

Make sure your RiskOS™ environment is provisioned with:

A workflow configured for the Deceased Check enrichment.

Regional support coverage for the Deceased Check enrichment (available exclusively in the United States).

Choose your environment

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

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

No real customer data
Free testing environment
Unlimited API calls

Get an API key

In the Sandbox RiskOS™ Dashboard, go to Developer Workbench > API Keys.
Copy your API key securely.

How it works

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

Start a new evaluation

Endpoint

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": "[email protected]",
      "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": "[email protected]",
      "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.	`"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.	`"+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. Although optional, it is required for eCBSV to meet the 90-day consent window set by the SSA. Example: `2022-07-28T06:10:54Z`.

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": "047-66-4618",
          "dob": "1943-09-19",
          "dod": "2022-11-19",
          "age": "79",
          "sourceAttribution": "Probate"
        }
      }
    }
  ]
}

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.

Decision and routing (primary control signals)

Use these fields to determine what action your application should take.

decision values are workflow-specific and may differ from the examples shown in this guide.

Field	Type	Description	Example
`decision`	String (enum)	Final evaluation result. Possible values: • `ACCEPT` • `REVIEW` • `REJECT` Note: The fields returned can be customized to fit your integration or business needs.	`"REVIEW"`
`decision_at`	String `<Date-Time>`	RFC 3339 timestamp when the decision was finalized.	`"2025-10-07T23:50:03.738648201Z"`
`score`	Number	If configured for a workflow, provides an aggregate score of all steps. This can be used for risk banding, additional routing, or analytics alongside the primary `decision` value.
`tags`	Array of Strings	Array of labels applied during the workflow to highlight routing choices, notable signals, or rule outcomes. Useful for reporting, segmentation, or UI highlighting in the RiskOS™ Dashboard.	`[]`
`review_queues`	Array of Strings	Lists any manual review queues the evaluation was sent to. Empty when the case is fully auto-resolved without human review.	`[]`
`notes`	String	Freeform text field for analyst or system comments about the evaluation. Often used to capture manual review rationale or investigation context.

Evaluation lifecycle and status

These fields describe where the evaluation is in its lifecycle and are useful for monitoring and asynchronous workflows.

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`	`"CLOSED"`
`sub_status`	String	Provides additional detail about the evaluation status. Example values: • `Under Review` • `Pending Verification` • `Accept` • `Reject`	`"Review"`

Identifiers and traceability

Use these fields to correlate requests, logs, webhooks, and support cases.

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`	`"CLOSED"`
`sub_status`	String	Provides additional detail about the evaluation status. Possible values: • `Under Review` • `Pending Verification` • `Accept` • `Reject`	`"Review"`

Execution context

These fields provide timing and environment context for the evaluation.

Field	Type	Description	Example
`eval_source`	String enum	Indicates where the evaluation was initiated from. Possible values: • `API`: Request submitted via the Evaluation API. • `Dashboard`: Case created or evaluated through the RiskOS™ Dashboard.	`"API"`
`eval_start_time`	String `<Date-Time>`	RFC 3339 timestamp for when RiskOS™ started processing the evaluation. Useful for latency and performance monitoring.	`"2025-10-07T23:50:03.60187976Z"`
`eval_end_time`	String `<Date-Time>`	RFC 3339 timestamp for when RiskOS™ finished processing the evaluation. Can be paired with `eval_start_time` to compute total processing time.	`"2025-10-07T23:50:03.738794253Z"`
`environment_name`	String	Indicates which environment the evaluation ran in. Typically `Sandbox` for testing or `Production` for live traffic.	`"Sandbox"`

Enrichment results

Enrichment outputs are returned in the data_enrichments array.

Field	Type	Description	Example
`enrichment_name`	String	Name of the module or service executed (e.g., Digital Intelligence, Verify Plus, Sigma Synthetic).	`"Socure Deceased Check"`
`enrichment_endpoint`	String	API endpoint that processed the enrichment.	`"https://sandbox.socure.com` >`/api/3.0/EmailAuthScore"`
`enrichment_provider`	String	Provider of the enrichment service (`Socure`, `RestAPI`, etc.).	`"Socure"`
`status_code`	Integer	HTTP status returned by the enrichment API call.	`200`
`request`	Object	Request payload sent to the enrichment service.	See `request` schema below.
`response`	Object	Normalized response data from the enrichment service.	See `response` schema below.
`error`	String	Populated only if the enrichment encountered an error.
`is_source_cache`	Boolean	Indicates whether cached data was used instead of a live API call.	`false`
`total_attempts`	Integer	Number of attempts made to retrieve the enrichment data.	`1`

`response` fields

Field	Type	Description	Example
`socureId`	String (UUID)	Socure’s persistent identity ID used for Graph Intelligence correlations.	`"46fd3b11-a130-4915-8cc4-074bbd799669"`
`reasonCodes`	Array Of Strings	Structured codes indicating deceased status.	`[ "R909", "R907" ]`
`firstName`	String	Resolved first name.	`"Jessica"`
`middleName`	String Or Null	Resolved middle name.	`"Marie"`
`surName`	String	Resolved last name.	`"Roberts"`
`nationalId`	String	Submitted SSN (full or last 4).	`"047-66-4618"`
`dob`	String	Date of birth.	`"1943-09-19"`
`dod`	String Or Null	Date of death if reported.	`"2022-11-19"`
`age`	String Or Number	Calculated age if date of death provided.	`"79"`
`sourceAttribution`	String Or Array	Data source confirming deceased status.	`"Probate"`

Apply routing logic

Use decision and reasonCodes to drive workflow outcomes:

Refer if reason code R907 or R909 is returned
Accept if neither is present
Fail if inputs are invalid or cannot be resolved

Best practices for integration and maintenance

Validate API inputs against the expected schema.
Use sandbox mode and known test identities during QA.
Monitor reasonCodes and sourceAttribution for transparency and auditability.
Use decision, tags, and review routing to drive operational workflows.
Log and store evaluation payloads and responses for compliance and dispute resolution.

Validation checklist

Test coverage

Known good identities → APPROVE

Bad/mismatched identities → DECLINE or REVIEW

Edge cases logged + reviewed

Schema and error handling

Fields match schema across environments

Errors are structured and retryable

Use exponential fallback with jitter for resubmissions

Logging and observability

Log full request/response

Include correlation IDs

Redact secrets from logs

Exception routing

Escalation paths defined for REVIEW

Support team has access to logs + scores