Integrate Business Onboarding

Before you start

Make sure your RiskOS™ environment is provisioned with:

A workflow configured 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.

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

No real customer data
Free testing environment
Unlimited API calls

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

Real customer data
API usage charges apply
Connects to live data services

Get an API key

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

How it works

Send a POST /api/evaluation request with business, individual/UBO, and device data.
RiskOS™ evaluates the request using your Business Onboarding workflow.
You receive a decision (ACCEPT, REVIEW, or REJECT).
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

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": "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 --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"`