## Before you start Make sure your RiskOS™ environment is provisioned with: - [A workflow configured](https://help.socure.com/riskos/docs/business-onboarding-riskos-setup) for the **Business Onboarding** solution. - **Business Onboarding** APIs and supporting services. - **UBO/Individual Verification** APIs and supporting services. ### Postman Collection The following Postman collection can be used to test the Business Onboarding solution with the Evaluation endpoint. ### 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.sandbox.socure.com/developers/api-keys). 2. Copy your API key securely. ## How it works 1. Send a `POST /api/evaluation` request with business, individual/UBO, and device data. 2. RiskOS™ evaluates the request using your Business Onboarding workflow. 3. You receive a decision (`ACCEPT`, `REVIEW`, or `REJECT`). 4. If required, complete partner verification asynchronously before receiving the final decision. > 📘 > > **Note**: The `decision` values shown in this guide (`ACCEPT`, `REVIEW`, `REJECT`) reflect a customized Business Onboarding workflow. > > Your environment may use different default decision values depending on how your workflow is configured. ## 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": "Sample-KYB-Case-123", "timestamp": "2025-05-18T02:09:25Z", "workflow": "business_onboarding", "data": { "ip_address": "24.21.33.212", "individual": { "id": "Sample-IND-106", "given_name": "Alistair", "family_name": "Blackwood", "national_id": "293001642", "date_of_birth": "1976-08-09", "email": "alistair.blackwood@example.com", "phone_number": "+1-212-555-4540", "address": { "line_1": "12620 PADDINGTON AVE", "line_2": "", "locality": "New York", "major_admin_division": "NY", "country": "US", "postal_code": "10001" }, "di_session_token": "234ac3ff-3ed1-42de-8f33-8f332febfa54" }, "additional_individuals": [ { "id": "Sample-IND-107", "given_name": "Theo", "family_name": "Matthews", "national_id": "598003280", "date_of_birth": "1980-07-06", "email": "theo.matthews92@mailbox.org", "phone_number": "+1-212-555-6698", "address": { "line_1": "130 Ironside St.", "line_2": "", "locality": "New York", "major_admin_division": "NY", "country": "US", "postal_code": "10001" }, "additional_context": { "disclosure_purpose": "GLBA_502(e)" } }, { "id": "Sample-IND-108", "given_name": "Jasper", "family_name": "Donovan", "national_id": "732004625", "date_of_birth": "1987-11-11", "email": "jdonovan@example.com", "phone_number": "+1-503-555-7811", "address": { "line_1": "2922 Huntington Drive", "line_2": "", "locality": "Forest Grove", "major_admin_division": "OR", "country": "US", "postal_code": "97123" }, "additional_context": { "disclosure_purpose": "GLBA_502(e)" } } ], "business": { "name": "MICROEM", "ein": "111222330", "phone_number": "+1-555-183-3389", "address": { "line_1": "100 Broadway", "line_2": "", "locality": "New York", "major_admin_division": "NY", "country": "US", "postal_code": "10005" }, "formation": { "entity_type": "CORPORATION", "registration_date": "2024-10-12", "registration_state": "DE", "registration_country": "US" }, "website_url": "https://microem.com/", "last_fiscal_revenue": { "amount": 3499144, "currency": "USD" } } } } ``` ```curl curl --location '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": "Sample-KYB-Case-123", "timestamp": "2025-05-18T02:09:25Z", "workflow": "business_onboarding", "data": { "ip_address": "24.21.33.212", "individual": { "id": "Sample-IND-106", "given_name": "Alistair", "family_name": "Blackwood", "national_id": "293001642", "date_of_birth": "1976-08-09", "email": "alistair.blackwood@example.com", "phone_number": "+1-212-555-4540", "address": { "line_1": "12620 PADDINGTON AVE", "line_2": "", "locality": "New York", "major_admin_division": "NY", "country": "US", "postal_code": "10001" }, "di_session_token": "234ac3ff-3ed1-42de-8f33-8f332febfa54" }, "additional_individuals": [ { "id": "Sample-IND-107", "given_name": "Theo", "family_name": "Matthews", "national_id": "598003280", "date_of_birth": "1980-07-06", "email": "theo.matthews92@mailbox.org", "phone_number": "+1-212-555-6698", "address": { "line_1": "130 Ironside St.", "line_2": "", "locality": "New York", "major_admin_division": "NY", "country": "US", "postal_code": "10001" }, "additional_context": { "disclosure_purpose": "GLBA_502(e)" } }, { "id": "Sample-IND-108", "given_name": "Jasper", "family_name": "Donovan", "national_id": "732004625", "date_of_birth": "1987-11-11", "email": "jdonovan@example.com", "phone_number": "+1-503-555-7811", "address": { "line_1": "2922 Huntington Drive", "line_2": "", "locality": "Forest Grove", "major_admin_division": "OR", "country": "US", "postal_code": "97123" }, "additional_context": { "disclosure_purpose": "GLBA_502(e)" } } ], "business": { "name": "MICROEM", "ein": "111222330", "phone_number": "+1-555-183-3389", "address": { "line_1": "100 Broadway", "line_2": "", "locality": "New York", "major_admin_division": "NY", "country": "US", "postal_code": "10005" }, "formation": { "entity_type": "CORPORATION", "registration_date": "2024-10-12", "registration_state": "DE", "registration_country": "US" }, "website_url": "https://microem.com/", "last_fiscal_revenue": { "amount": 3499144, "currency": "USD" } } } }' ``` ### Request schema #### Top-level fields | Field | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `id` | String | Required | Unique identifier for the request. | `"Sample-KYB-Case-123"` | | `timestamp` | String | Required | Time of the evaluation request. | `"2025-05-18T02:09:25Z"` | | `workflow` | String | Required | Workflow name configured in the RiskOS™ Dashboard. | `"business_onboarding"` | | `data` | Object | Required | Main payload containing business and individual information. | | #### `data` fields | Field | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `individual` | Object | Required | Primary individual information. | | | `business` | Object | Required | Business entity information. | | | `additional_individuals` | Array | Optional | List of individuals. | | | `ip_address` | String | Optional | Client IP address. | `"203.0.113.42"` | #### `individual` fields | Field | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `given_name` | String | Required | Individual's first name. | `"Alistair"` | | `family_name` | String | Required | Individual's last name. | `"Blackwood"` | | `national_id` | String | Required | SSN or ITIN. | `"293001642"` | | `date_of_birth` | String | Required | Date of birth in ISO format. | `"1976-08-09"` | | `email` | String | Required | Individual's email address. | `"theo.matthews92@mailbox.org"` | | `phone_number` | String | Required | Phone number in E.164 format. | `"+1-212-555-4540"` | | `address` | Object | Required | Individual's physical address. | | | `di_session_token` | String | Required | Digital Intelligence SDK session token. | `"eyJraWQiOiJmMzRiN2Yi..."` | | `id` | String | Optional | Customer's internal identifier. | `"Sample-IND-106"` | | `additional_context` | Object | Optional | Additional verification settings. | | #### `business` fields | Field | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `name` | String | Required | Legal business name. | `"MICROEM"` | | `ein` | String | Required | Federal Employer Identification Number. | `"111222330"` | | `address` | Object | Required | Business address. | | | `phone_number` | String | Optional | Primary business phone number. | `"+1-555-183-3389"` | | `website_url` | String | Optional | Company website URL. | `"https://microem.com/"` | | `formation` | Object | Optional | Business formation details. | | | `last_fiscal_revenue` | Object | Optional | Last fiscal year revenue. | `{"amount": 3499144, "currency": "USD"}` | #### `address` fields | Field | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `line_1` | String | Required | Street address. | `"12620 PADDINGTON AVE"` | | `line_2` | String | Optional | Additional address info. | `"Apt 12B"` | | `locality` | String | Required | City or town name. | `"New York"` | | `major_admin_division` | String | Required | State code. | `"NY"` | | `country` | String | Required | Country code. | `"US"` | | `postal_code` | String | Required | ZIP or postal code. | `"10001"` | #### `formation` fields | Field | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `entity_type` | String | Required | Legal entity type. | `"CORPORATION"` | | `registration_date` | String | Required | Date of business registration. | `"2024-10-12"` | | `registration_state` | String | Required | State of registration. | `"DE"` |