## Before you start
Make sure your RiskOS™ environment is provisioned with:
- [A workflow configured](https://help.socure.com/riskos/docs/deceased-check-riskos-setup#/) 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.
```undefined
https://riskos.sandbox.socure.com/api/evaluation
```
- **No real customer data**
- **Free testing environment**
- **Unlimited API calls**
```undefined
https://riskos.socure.com/api/evaluation
```
- **Real customer data**
- **API usage charges apply**
- **Connects to live data services**
### Get an API key
1. In the Sandbox RiskOS™ Dashboard, go to [**Developer Workbench > API Keys**](https://riskos.sandbox.socure.com/developers/api-keys).
2. Copy your API key securely.
1. In the Production RiskOS™ Dashboard, go to [**Developer Workbench > API Keys**](https://riskos.sandb...k.com/developers/api-keys).
2. 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
```http
POST https://riskos.sandbox.socure.com/api/evaluation
```
```http
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:
```http
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
```json
{
"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
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 `` | 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.
```json
{
"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` | `