User Guides
Home
Start typing to search…

Integration Guide

Learn how to integrate Socure’s Business Onboarding API to automate KYB verification for businesses.

Socure Business Onboarding API integration guide

This guide walks you through how to integrate with Socure’s /api/evaluation endpoint using the Business Onboarding workflow. You’ll learn how to send minimal input data, parse the enriched response, and apply decision logic to support onboarding, fraud prevention, and conversion optimization workflows.


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

Get an API key

  1. In the Sandbox RiskOS™ Dashboard, go to Developer Workbench > 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 (APPROVE, REVIEW, or DECLINE).
  4. If required, complete partner verification asynchronously before receiving the final decision.
📘

Note: The decision values shown in this guide (ACCEPT, REVIEW, DECLINE) 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

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": "[email protected]",
      "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": "[email protected]",
        "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": "[email protected]",
        "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",
      "primary_phone": "+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": "[email protected]",
      "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": "[email protected]",
        "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": "[email protected]",
        "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",
      "primary_phone": "+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

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.Required, customer-defined unique identifier for the request.

"Sample-KYB-Case-123"

timestamp

String

Required

RFC 3339 timestamp indicating when the evaluation request was initiated.

"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

See data schema below.


data fields

FieldTypeRequiredDescriptionExample
individualObjectRequiredPrimary individual (business owner/signatory) information. Must include core KYC fields.See individual schema below.
businessObjectRequiredBusiness entity information. Must include EIN and address.See business schema below.
additional_individualsArrayOptionalList of UBOs and other associated individuals. Each uses the same format as individual object.
ip_addressStringOptionalClient IP address in IPv4/IPv6 format. Used for device intelligence."203.0.113.42"

individual fields

FieldTypeRequiredDescriptionExample
given_nameStringRequiredIndividual's first/given name (max 240 characters)"Alistair"
family_nameStringRequiredIndividual's last/family name (max 240 characters)"Blackwood"
national_idStringRequiredSSN or ITIN — 9 digits, hyphens optional"293001642"
date_of_birthStringRequiredDate of birth in ISO format (YYYY-MM-DD)"1976-08-09"
emailStringRequiredIndividual's email address (must be a valid email format)"theo.matthews92
@mailbox.org"
phone_numberStringRequiredPhone number in E.164 format (with country code)"+1-212-555-4540"
addressObjectRequiredIndividual's physical addressSee address schema below.
di_session_tokenStringRequiredDigital Intelligence SDK session token (UUID format)"eyJraWQiOiJmMzRiN2Yi..."
idStringOptionalMaps to the userId in enrichments or a customer’s internal identifier. Can be enabled as a searchable field in RiskOS™ Dashboard."Sample-IND-106"
additional_contextObjectOptionalAdditional verification settings

business fields

FieldTypeRequiredDescriptionExample
nameStringRequiredLegal business name."MICROEM"
einStringRequiredFederal Employer Identification Number (9 digits)."111222330"
addressObjectRequiredBusiness addressSee address schema below.
primary_phoneStringOptionalPrimary business phone number in E.164 format (with country code)."+1-555-183-3389"
website_urlStringOptionalCompany website URL (must be a valid URL)."https://microem.com/"
formationObjectOptionalBusiness formation details.See formation schema below.
last_fiscal_revenueObjectOptionalLast fiscal year revenue (amount object with amount and currency fields).{"amount": 3499144, "currency": "USD"}

address fields (used in individual.address and business.address)

FieldTypeRequiredDescriptionExample
line_1StringRequiredStreet address (max 255 characters)."12620 PADDINGTON AVE"
line_2StringOptionalAdditional address info (apartment, suite, unit, etc.)."Apt 12B"
localityStringRequiredCity or town name."New York"
major_admin_divisionStringRequiredState or province code (2–3 characters)."NY"
countryStringRequiredISO 3166-1 alpha-2 country code."US"
postal_codeStringRequiredZIP or postal code (5–10 alphanumeric characters)."10001"

formation fields

FieldTypeRequiredDescriptionExample
entity_typeStringRequiredLegal entity type (e.g., CORPORATION, LLC, SOLE_PROPRIETOR)."CORPORATION"
registration_dateStringRequiredDate of business registration in ISO format (YYYY-MM-DD)."2024-10-12"
registration_stateStringRequiredState, province, or region of registration (2–3 character code)."DE"

Example response

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

{
  "id": "Sample-KYB-Case-123",
  "workflow": "business_onboarding",
  "workflow_id": "81f5383f-1fbb-46d0-8c26-6964bd9dc3a9",
  "workflow_version": "9.8.0",
  "eval_source": "API",
  "eval_id": "266e54e8-66bc-4f6d-be9a-6da239204822",
  "eval_start_time": "2025-10-09T16:12:09.306980648Z",
  "eval_end_time": "2025-10-09T16:12:09.558731441Z",
  "decision": "REVIEW",
  "decision_at": "2025-10-09T16:12:09.558745621Z",
  "status": "ON_HOLD",
  "sub_status": "BaseLayer Business Search Initiated",
  "tags": [],
  "notes": "",
  "review_queues": [
    "Default Queue"
  ],
  "data_enrichments": [
    {
      "enrichment_name": "Baselayer Business Verification",
      "enrichment_endpoint": "https://api.baselayer.com/searches",
      "enrichment_provider": "BaselayerCreateBusinessSearch",
      "status_code": 201,
      "request": {
        "address": "100 Broadway, New York, NY, 10005",
        "name": "MICROEM",
        "options": [
          "Order.NaicsPrediction"
        ],
        "tin": "111222330",
        "website": "https://microem.com/"
      },
      "response": {
        "address": "100 Broadway, New York, NY, 10005",
        "id": "720b52f0-9641-4384-9032-c8ea68a682d0",
        "name": "MICROEM",
        "reference_id": "",
        "state": "PENDING",
        "status_url": "https://api.baselayer.com/searches/720b52f0-9641-4384-9032-c8ea68a682d0/status",
        "tin": "111222330",
        "url": "https://api.baselayer.com/searches/720b52f0-9641-4384-9032-c8ea68a682d0"
      },
      "is_source_cache": false,
      "total_attempts": 1
    }
  ],
  "computed": {
    "baselayer_business_search_response": {
      "__third_party_name__": "Baselayer Business Verification",
      "address": "100 Broadway, New York, NY, 10005",
      "id": "720b52f0-9641-4384-9032-c8ea68a682d0",
      "name": "MICROEM",
      "reference_id": "",
      "state": "PENDING",
      "status_url": "https://api.baselayer.com/searches/720b52f0-9641-4384-9032-c8ea68a682d0/status",
      "tin": "111222330",
      "url": "https://api.baselayer.com/searches/720b52f0-9641-4384-9032-c8ea68a682d0"
    }
  },
  "eval_status": "evaluation_paused",
  "environment_name": "Sandbox",
  "redirect_uri": "https://riskos.sandbox.socure.com/hosted/9b0d4ff7-7111-4413-b909-18642d0f62df"
}

Key response fields

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


Where to find specific results

AreaFieldsHow to use it
Decision and routingdecision, decision_at, tags, review_queues, notes, scorePrimary control signals. Branch application logic using decision. Use tags, queues, notes, and score for secondary routing, review, and explanation.
Module resultsModule-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 traceabilityid, eval_idPersist these identifiers to correlate API calls, logs, webhooks, GET requests, and support cases.
Enrichment executiondata_enrichments[] (response, status_code, total_attempts, is_source_cache)Inspect enrichment outputs and detect provisioning issues, partial failures, retries, or cached responses.
Workflow contextworkflow, workflow_id, workflow_versionUnderstand which workflow ran and which version produced the result. Useful for debugging and historical analysis.
Evaluation lifecycleeval_status, status, sub_statusExecution and case state only. Useful for monitoring and asynchronous workflows. Do not use for business decisions.
Execution contexteval_source, eval_start_time, eval_end_time, environment_nameObservability 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.

FieldTypeDescriptionExample
decisionString (enum)Final evaluation result returned by the Business Onboarding workflow.

Possible values:
• APPROVE
• REVIEW
• DECLINE

Note: The fields returned can be customized to fit your integration or business needs.		"REVIEW"
decision_atString <Date-Time>RFC 3339 timestamp when the decision was finalized."2025-10-09T16:12:09.558745621Z"
scoreNumberIf 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.-76
tagsArray of stringsArray 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_queuesArray of stringsLists any manual review queues the evaluation was sent to. Empty when the case is fully auto-resolved without human review.["Default Queue"]
notesStringFreeform 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.

FieldTypeDescriptionExample
eval_statusString (enum)Indicates the current state of an evaluation in RiskOS™.

Possible values:
• evaluation_completed
• evaluation_paused
• evaluation_in_progress		"evaluation_paused"
statusString (enum)Indicates the current state of an evaluation or case.

Possible values:
• OPEN
• ON_HOLD
• CLOSED		"ON_HOLD"
sub_statusStringProvides additional detail about the evaluation status."BaseLayer Business Search Initiated"

Identifiers and traceability

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

FieldTypeDescriptionExample
idString (UUID or custom string)Your evaluation identifier within RiskOS™.

Note: This is customer-generated.		"Sample-KYB-Case-123"
eval_idString (UUID)RiskOS™-generated unique identifier for the evaluation."266e54e8-66bc-4f6d-be9a-6da239204822"
workflowStringName of the workflow executed."business_onboarding"
workflow_idString (UUID)Unique identifier for the workflow run."81f5383f-1fbb-46d0-8c26-6964bd9dc3a9"
workflow_versionStringVersion of the executed workflow."9.8.0"

Execution context

These fields provide timing and environment context for monitoring and debugging.

FieldTypeDescriptionExample
eval_sourceString (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_timeString <Date-Time>RFC 3339 timestamp for when RiskOS™ started processing the evaluation. Useful for latency and performance monitoring."2025-10-09T16:12:09.306980648Z"
eval_end_timeString <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-09T16:12:09.558731441Z"
environment_nameStringIndicates which environment the evaluation ran in. Typically Sandbox for testing or Production for live traffic."Sandbox"

Enrichment results

Partner and module outputs are returned in the data_enrichments array.

FieldTypeDescriptionExample
enrichment_nameStringName of the module or service executed."Baselayer Business Verification"
enrichment_endpointStringEndpoint that processed the enrichment."https://api.baselayer.com/searches"
enrichment_providerStringProvider of the enrichment service (Socure, third-party vendor, etc.)."BaselayerCreateBusinessSearch"
status_codeIntegerHTTP status returned by the enrichment API call.201
requestObjectRequest payload sent to the enrichment service.See request schema below.
responseObjectNormalized response data from the enrichment service.See response schema below.
errorStringPopulated only if the enrichment encountered an error.""
is_source_cacheBooleanIndicates whether cached data was used instead of a live API call.false
total_attemptsIntegerNumber of attempts to retrieve the enrichment data.1

Example request fields (varies by enrichment)

FieldTypeDescriptionExample
addressStringFull business address submitted for verification or lookup."100 Broadway, New York, NY, 10005"
nameStringLegal or registered business name to be verified."MICROEM"
optionsArray of stringsSpecific enrichment options or modules requested.["Order.NaicsPrediction"]
tinStringTax Identification Number or equivalent business identifier."111222330"
websiteString (URL)Company website URL provided for enrichment or verification."https://microem.com/"

Example response fields (varies by enrichment)

FieldTypeDescriptionExample
addressStringFull business address returned by the enrichment provider."100 Broadway, New York, NY, 10005"
idStringUnique enrichment record identifier assigned by the provider."720b52f0-9641-4384-9032-c8ea68a682d0"
nameStringLegal or registered business name."MICROEM"
reference_idStringUnique identifier assigned to each enrichment after a RiskOS™ workflow is finalized.
stateStringCurrent enrichment request state or processing status."PENDING"
status_urlStringEndpoint for checking the latest status of the enrichment request.
tinStringTax Identification Number associated with the business."111222330"
urlStringDirect URL to the enrichment record or search result.

Apply routing logic

if response.get("decision") == "APPROVE":
    onboard_user()
elif response.get("decision") == "REVIEW":
    send_to_manual_review()
elif response.get("decision") == "DECLINE":
    reject_user()
else:
    log_warning("Unexpected decision value")

API explorer

To make Sandbox calls in the API explorer:

  1. Complete RiskOS™ environment Setup guide.
  2. Go to the RiskOS™ Dashboard > Developer Workbench > API Keys page and collect your Sandbox API key.
  3. Paste your key into the API Key field.
    • The explorer automatically adds the Authorization: Bearer header.
  4. Click Send Request to execute the call.
📘

Note:

The Sandbox environment requires specific field values to return a properly formatted response. Modifying the input data may result in HTTP errors.

POST

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

Request | Response

Request Body

API Response

Response will appear here.

Best practices for integration

  • Always include ein, dob, and di_session_token.
  • Include optional fields (phone, website_url) when available to improve Business Onboarding accuracy.
  • Use reasonCodes and routingOutcomes to refine your risk policy.
  • Configure UBO/Individual verification flow using recommended products.
  • Log and store evaluation payloads and responses for compliance and debugging.

Validation checklist

Inputs

Minimal inputs accepted and validated
Optional fields handled gracefully

Routing

Reason codes logged and surfaced in workflows
UBO/Individual connected workflow tested

Testing

Sandbox personas used to validate all outcomes (APPROVE, REVIEW, DECLINE)

Updated about 1 month ago