Integration Guide

Socure Account Intelligence API integration guide

This guide walks you through how to integrate with Socure’s /api/evaluation endpoint using the Account Intelligence or Account Intelligence Premier enrichments. You’ll learn how to send identity data, parse the response, and apply decision logic to support onboarding, trust and safety, fraud prevention, or compliance workflows.

Before you start

Make sure your RiskOS™ environment is provisioned with:

A workflow configured for the Account Intelligence enrichment.

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 configured RiskOS™ workflow with tailored enrichments.
Receive a decision (ACCEPT, REVIEW, or REJECT) and supporting metadata.
Apply your routing logic based on the result.

Example frontend input form (mapped to `/api/evaluation` payload)

This example screen shows how a mobile app might capture user information during onboarding before triggering a RiskOS™ /api/evaluation request.

Each field maps to required parameters in the data.individual object:

First Name → given_name
Last Name → family_name
Account Number → account.account_number
Routing Number → account.routing_number
Account Inquiries → account.account_inquiries (e.g., AVAILABILITY, OWNERSHIP)

You can configure which fields are required per workflow by adjusting module-level match logic in RiskOS™.

Start a new Risk 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: Account `AVAILABILITY`

Use these fields when you need to confirm whether a bank account is currently open and available for transactions. The account_number and routing_number together uniquely identify the account, and the account_inquiries field must be set to AVAILABILITY.

{
  "id": "123456",
  "timestamp": "2022-07-28T06:10:54.298Z",
  "workflow": "bank_account_validation",
  "data": {
    "individual": {
      "account": {
        "account_number": "92301962561",
        "routing_number": "122199983",
        "account_inquiries": ["AVAILABILITY"]
      }
    }
  }
}

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": "123456",
  "timestamp": "2022-07-28T06:10:54.298Z",
  "workflow": "bank_account_validation",
  "data": {
    "individual": {
      "account": {
        "account_number": "92301962561",
        "routing_number": "122199983",
        "account_inquiries": ["AVAILABILITY"]
      }
    }
  }
}'

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.	`"123456"`
`timestamp`	String `<Date-Time>`	Required	Timestamp when evaluation was initiated	`"2025-05-18T02:09:25Z"`
`workflow`	String	Required	RiskOS™ workflow name configured in your environment	`"bank_account` `_validation"`
`data`	Object	Required	Main payload containing business and individual information
→`individual.account`	Object	Required	Primary identity object containing account information.	See `individual.account` below.

`individual.account` fields

Field	Type	Required	Description	Example
`account_number`	String	Required	Bank account number to be validated.	`"92301962561"`
`routing_number`	String	Required	Bank routing number associated with the account.	`"122199983"`
`account_inquiries`	String	Required	Inquiry type specifying the check to perform. Must be set to `AVAILABILITY`.	`"AVAILABILITY"`

Example request: Account `OWNERSHIP`

Use these fields when you need to validate the identity of the account holder associated with a bank account. This schema includes personal details (such as name, date of birth, and contact information) or business details, along with the account information. The account_inquiries field must be set to OWNERSHIP.

{
  "id": "123456",
  "timestamp": "2022-07-28T06:10:54.298Z",
  "workflow": "bank_account_validation",
  "data": {
    "individual": {
      "given_name": "John",
      "family_name": "Smith",
      "date_of_birth": "1958-01-31",
      "account": {
        "account_number": "92301962561",
        "routing_number": "122199983",
        "account_inquiries": ["OWNERSHIP"]
      }
    }
  }
}

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": "123456",
  "timestamp": "2022-07-28T06:10:54.298Z",
  "workflow": "bank_account_validation",
  "data": {
    "individual": {
      "given_name": "John",
      "family_name": "Smith",
      "date_of_birth": "1958-01-31",
      "account": {
        "account_number": "92301962561",
        "routing_number": "122199983",
        "account_inquiries": ["OWNERSHIP"]
      }
    }
  }
}'

Request schema

Top-level fields

Field	Type	Required	Description	Example
`id`	String	Required	Mandatory identifier set by the customer when initiating a request in RiskOS™.	`"123456"`
`timestamp`	String	Required	Timestamp when evaluation was initiated	`"2025-05-18T02:09:25Z"`
`workflow`	String	Required	RiskOS™ workflow name configured in your environment	`"bank_account_validation"`
`data`	Object	Required	Main payload containing business and individual information	See `data` schema below.
→`individual`	Object	Required	Primary identity object containing account information.	See `individual` schema below.

`individual` fields

Field	Type	Required	Description	Example
`given_name`	String	Required	Individual’s first name.	`"John"`
`family_name`	String	Required	Individual’s last name.	`"Smith"`
`name`	String	Conditional	Business entity name. Required if `given_name` and `family_name` are not provided.	`"Online Gaming Inc"`
`national_id`	String	Optional	Government-issued identifier (e.g., SSN).	`"123456789"`
`date_of_birth`	String	Optional	Date of birth in `YYYY-MM-DD` format.	`"1958-01-31"`
`email`	String	Optional	Email address associated with the individual.	`"[email protected]"`
`phone_number`	String	Optional	Phone number in E.164 format.	`"+13475551234"`
`address`	Object	Optional	Mailing address of the individual.	See `address` schema below.
`line_1`	String	Optional	Street address line 1.	`"234 Main Street"`
`line_2`	String	Optional	Street address line 2 (apartment, suite, etc.).	`"Apt. 3C"`
`locality`	String	Optional	City or locality.	`"Jersey City"`
`major_admin_division`	String	Optional	State, province, or region.	`"NJ"`
`country`	String	Optional	Two-letter ISO country code.	`"US"`
`postal_code`	String	Optional	Postal or ZIP code.	`"07307"`
`account`	Object	Required	Bank account details for validation.	See `account` schema below.

`account` fields

Field	Type	Required	Description	Example
`account_number`	String	Required	Bank account number to be validated.	`"92301962561"`
`routing_number`	String	Required	Bank routing number associated with the account.	`"122199983"`
`account_inquiries`	Array of Strings	Required	Types of checks to perform. Must include `OWNERSHIP`.	`["OWNERSHIP"]`

Example request: Account `AVAILABILITY` and `OWNERSHIP`

The AVAILABILITY and OWNERSHIP parameters can be combined in any situation where you need to validate both an account's availability and ownership.

{
  "id": "123456",
  "timestamp": "2022-07-28T06:10:54.298Z",
  "workflow": "bank_account_validation",
  "data": {
    "individual": {
      "given_name": "John",
      "family_name": "Smith",
      "national_id": "123456789",
      "date_of_birth": "1958-01-31",
      "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"
      },
      "account": {
        "account_number": "92301962561",
        "routing_number": "122199983",
        "account_inquiries": ["AVAILABILITY", "OWNERSHIP"]
      }
    }
  }
}

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": "123456",
  "timestamp": "2022-07-28T06:10:54.298Z",
  "workflow": "bank_account_validation",
  "data": {
    "individual": {
      "given_name": "John",
      "family_name": "Smith",
      "national_id": "123456789",
      "date_of_birth": "1958-01-31",
      "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"
      },
      "account": {
        "account_number": "92301962561",
        "routing_number": "122199983",
        "account_inquiries": ["AVAILABILITY", "OWNERSHIP"]
      }
    }
  }
}'

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": "Ananda_AccountIntelligence-1761645455142",
  "workflow": "api_individual_onboarding",
  "workflow_id": "36031914-1edb-4b81-8d80-5d50aa07cead",
  "workflow_version": "179.1.0",
  "eval_source": "API",
  "eval_id": "2b3fb168-2a70-418d-80b7-0c0a9bdff17f",
  "eval_start_time": "2025-10-28T09:57:38.019002347Z",
  "eval_end_time": "2025-10-28T09:57:38.068070735Z",
  "decision": "REJECT",
  "decision_at": "2025-10-28T09:57:38.067908786Z",
  "status": "CLOSED",
  "sub_status": "Decline",
  "tags": [],
  "notes": "",
  "review_queues": [],
  "data_enrichments": [
    {
      "enrichment_name": "Socure Account Intelligence",
      "enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {
        "businessPhone": "+11232313213",
        "city": "Danbury",
        "country": "US",
        "countryOfOrigin": "US",
        "customerUserId": "custom-customer_user_id",
        "dob": "1958-01-31",
        "ein": "912355201",
        "firstName": "Ananda",
        "mobileNumber": "+1-2037986508",
        "modules": [
          "accountintelligence"
        ],
        "nationalId": "700-01-3784",
        "parentTxnId": "2b3fb168-2a70-418d-80b7-0c0a9bdff17f",
        "payments": {
          "account": {
            "accountNumber": "92301962141",
            "inquiries": [
              "STATUS",
              "OWNERSHIP"
            ],
            "routingNumber": "122199983"
          }
        },
        "physicalAddress": "2 Moran Ave",
        "physicalAddress2": "Address Line 2",
        "riskOSId": "Ananda_AccountIntelligence-1761645455142",
        "state": "CT",
        "surName": "test",
        "userId": "data-individual-id",
        "workflow": "api_individual_onboarding",
        "zip": "068100000"
      },
      "response": {
        "accountIntelligence": {
          "account": {
            "availabilityScore": 0.49,
            "ownershipScore": 0.49
          },
          "reasonCodes": []
        },
        "customerProfile": {
          "customerUserId": "custom-customer_user_id",
          "userId": "data-individual-id"
        },
        "referenceId": "9acd0778-5ee5-48c2-b2e9-9a7a141d887f"
      },
      "is_source_cache": false,
      "total_attempts": 1
    }
  ],
  "computed": {
    "CONDITION": false,
    "socure_accountintelligence_response": {
      "__third_party_name__": "Socure Account Intelligence PROD SBX",
      "accountIntelligence": {
        "account": {
          "availabilityScore": 0.49,
          "ownershipScore": 0.49
        },
        "reasonCodes": []
      },
      "customerProfile": {
        "customerUserId": "custom-customer_user_id",
        "userId": "data-individual-id"
      },
      "referenceId": "9acd0778-5ee5-48c2-b2e9-9a7a141d887f"
    }
  },
  "eval_status": "evaluation_completed",
  "environment_name": "Sandbox"
}

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.	`"REJECT"`
`decision_at`	String `<Date-Time>`	RFC 3339 timestamp when the decision was finalized.	`"2024-12-02T10:29:10.999Z"`
`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.	`-76`
`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.	`["account ta", "high risk"]`
`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`	`"Reject"`

Identifiers and traceability

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

Field	Type	Description	Example
`id`	String (UUID or custom string)	Your evaluation identifier within RiskOS™. Note: This is customer-generated.	`"ato-78901"`
`eval_id`	String (UUID)	RiskOS-generated unique identifier for the evaluation.	`"6dc8f39c-ecc3-4fe0-9283-fc8e5f99e816"`
`workflow`	String	Name of the workflow executed.	`"account_takeover"`
`workflow_id`	String (UUID)	Unique identifier for the workflow run.	`"472288ff-b3a8-4e69-89dd-069d5e2bcb41"`
`workflow_version`	String	Version of the executed workflow.	`"3.7.0"`

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.	`"2024-12-02T10:28:24.456771162Z"`
`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.	`"2024-12-02T10:29:10.999Z"`
`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 Account Intelligence"`
`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`

`request` fields

Field	Type	Description	Example
`modules`	Array of Strings	Product modules to run. For Account Intelligence, include `"accountintelligence"`.	`["accountintelligence"]`
`country`	String	Country code in ISO 3166-1 alpha-2 format.	`"US"`
`countryOfOrigin`	String	Country of origin code in ISO 3166-1 alpha-2 format.	`"US"`
`firstName`	String	First name of the individual account holder.	`"Ananda"`
`surName`	String	Last name (surname) of the individual account holder.	`"test"`
`dob`	String (YYYY-MM-DD)	Date of birth of the individual account holder.	`"1958-01-31"`
`nationalId`	String	Government-issued identifier (e.g., SSN or national ID).	`"700-01-3784"`
`ein`	String	Employer Identification Number (EIN), if applicable.	`"912355201"`
`physicalAddress`	String	Address line 1 (street address).	`"2 Moran Ave"`
`physicalAddress2`	String	Address line 2 (apt/suite/unit).	`"Address Line 2"`
`city`	String	City of the account holder.	`"Danbury"`
`state`	String	State, province, or region.	`"CT"`
`zip`	String	Postal code (ZIP code).	`"068100000"`
`mobileNumber`	String	Mobile phone number (typically E.164).	`"+1-2037986508"`
`businessPhone`	String	Business phone number (typically E.164).	`"+11232313213"`
`customerUserId`	String	Customer-provided identifier for the end user.	`"custom-customer_user_id"`
`userId`	String	Customer-provided identifier for the individual (often internal user key).	`"data-individual-id"`
`workflow`	String	Workflow name that initiated the enrichment.	`"api_individual_onboarding"`
`riskOSId`	String	RiskOS workflow execution identifier.	`"Ananda_AccountIntelligence-1761645455142"`
`parentTxnId`	String (UUID)	Parent transaction/evaluation ID for correlation.	`"2b3fb168-2a70-418d-80b7-0c0a9bdff17f"`
`payments.account.accountNumber`	String	Bank account number to be evaluated.	`"92301962141"`
`payments.account.routingNumber`	String	Bank routing number associated with the account.	`"122199983"`
`payments.account.inquiries`	Array of Strings	Inquiry types to be performed for the bank account.	`["STATUS","OWNERSHIP"]`

`response` fields

Field	Type	Description	Example
`referenceId`	String (UUID)	Unique identifier assigned to the enrichment call result.	`"9acd0778-5ee5-48c2-b2e9-9a7a141d887f"`
`accountIntelligence`	Object	Results from Account Intelligence evaluation. See Account Intelligence Scoring for more information.
`customerProfile`	Object	Echoed customer identifiers associated with the request.

Sandbox test cases

You can simulate almost any identity scenario using our Test Personas JSON file. Each entry includes a realistic, sandbox-only identity and a ready-to-use API request payload. Many entries also include the expected response to help you validate your /api/evaluation integration before going live.

Test cases - Happy path

Test case 1: Verify the availability and ownership of a consumer account

curl --location 'https://riskos.sandbox.socure.com/api/evaluation' \
--header 'accept: application/json' \
--header 'X-API-Version: 2025-01-01.orion' \
--header 'Content-Type: application/json' \
--header 'authorization: Bearer YOUR_API_KEY' \
--data '{
    "id": "Ananda_AccountIntelligence-1761645455142",
    "timestamp": "2025-10-28T09:57:38.019002347Z",
    "workflow": "api_individual_onboarding",
    "data": {
        "line_of_business": "test1",
        "channel": "mobile",
        "individual": {
            "additional_context": {
            },
             "account": {
                "account_number": "92301962141",
                "routing_number": "122199983",
                "account_inquiries": [
                    "AVAILABILITY",
                    "OWNERSHIP"
                ]
            },
            "id": "data-individual-id",
            "given_name": "Ananda",
            "family_name": "test",
            "date_of_birth": "1958-01-31",
            "national_id": "700-01-3784",
            "phone_number": "+1-2037986508",
            "address": {
                "type": "HOME",
                "line_1": "2 Moran Ave",
                "line_2": "Address Line 2",
                "locality": "Danbury",
                "major_admin_division": "CT",
                "country": "US",
                "postal_code": "068100000"
            }
        },
        "custom": {
            "customer_user_id":"custom-customer_user_id",
            "country_of_origin": "US"
        },
        "business": {
            "ein":"912355201",
            "phone_number":"+11232313213"
        }
    }
}'

{
    "id": "Ananda_AccountIntelligence-1761645455142",
    "workflow": "api_individual_onboarding",
    "workflow_id": "36031914-1edb-4b81-8d80-5d50aa07cead",
    "workflow_version": "179.1.0",
    "eval_source": "API",
    "eval_id": "2b3fb168-2a70-418d-80b7-0c0a9bdff17f",
    "eval_start_time": "2025-10-28T09:57:38.019002347Z",
    "eval_end_time": "2025-10-28T09:57:38.068070735Z",
    "decision": "REJECT",
    "decision_at": "2025-10-28T09:57:38.067908786Z",
    "status": "CLOSED",
    "sub_status": "Decline",
    "tags": [],
    "notes": "",
    "review_queues": [],
    "data_enrichments": [
        {
            "enrichment_name": "Socure Account Intelligence PROD SBX",
            "enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
            "enrichment_provider": "Socure",
            "status_code": 200,
            "request": {
                "businessPhone": "+11232313213",
                "city": "Danbury",
                "country": "US",
                "countryOfOrigin": "US",
                "customerUserId": "custom-customer_user_id",
                "dob": "1958-01-31",
                "ein": "912355201",
                "firstName": "Ananda",
                "mobileNumber": "+1-2037986508",
                "modules": [
                    "accountintelligence"
                ],
                "nationalId": "700-01-3784",
                "parentTxnId": "2b3fb168-2a70-418d-80b7-0c0a9bdff17f",
                "payments": {
                    "account": {
                        "accountNumber": "92301962141",
                        "inquiries": [
                            "STATUS",
                            "OWNERSHIP"
                        ],
                        "routingNumber": "122199983"
                    }
                },
                "physicalAddress": "2 Moran Ave",
                "physicalAddress2": "Address Line 2",
                "riskOSId": "Ananda_AccountIntelligence-1761645455142",
                "state": "CT",
                "surName": "test",
                "userId": "data-individual-id",
                "workflow": "api_individual_onboarding",
                "zip": "068100000"
            },
            "response": {
                "accountIntelligence": {
                    "account": {
                        "availabilityScore": 0.49,
                        "ownershipScore": 0.49
                    },
                    "reasonCodes": []
                },
                "customerProfile": {
                    "customerUserId": "custom-customer_user_id",
                    "userId": "data-individual-id"
                },
                "referenceId": "9acd0778-5ee5-48c2-b2e9-9a7a141d887f"
            },
            "is_source_cache": false,
            "total_attempts": 1
        }
    ],
    "computed": {
        "CONDITION": false,
        "socure_accountintelligence_response": {
            "__third_party_name__": "Socure Account Intelligence PROD SBX",
            "accountIntelligence": {
                "account": {
                    "availabilityScore": 0.49,
                    "ownershipScore": 0.49
                },
                "reasonCodes": []
            },
            "customerProfile": {
                "customerUserId": "custom-customer_user_id",
                "userId": "data-individual-id"
            },
            "referenceId": "9acd0778-5ee5-48c2-b2e9-9a7a141d887f"
        }
    },
    "eval_status": "evaluation_completed",
    "environment_name": "Sandbox"
}

Test case 2: Verify the availability and ownership of a business account

curl --location 'https://riskos.sandbox.socure.com/api/evaluation' \
--header 'accept: application/json' \
--header 'X-API-Version: 2025-01-01.orion' \
--header 'Content-Type: application/json' \
--header 'authorization: Bearer YOUR_API_KEY' \
--data '{
    "id": "Ananda_AccountIntelligence-1761645406795",
    "timestamp": "2025-10-28T09:56:48.268221402Z",
    "workflow": "api_individual_onboarding",
    "data": {
        "line_of_business": "test1",
        "channel": "mobile",
        "individual": {
            "additional_context": {
                "entity_name": "sdfd"
            },
             "account": {
                "account_number": "92301962141",
                "routing_number": "122199983",
                "account_inquiries": [
                  	"AVAILABILITY",
                    "OWNERSHIP"
                ]
            },
            "id": "data-individual-id",
            "date_of_birth": "1958-01-31",
            "national_id": "700-01-3784",
            "phone_number": "2037986508",
            "address": {
                "type": "HOME",
                "line_1": "2 Moran Ave",
                "line_2": "Address Line 2",
                "locality": "Danbury",
                "major_admin_division": "CT",
                "country": "US",
                "postal_code": "068100000"
            }
        },
        "custom": {
            "customer_user_id":"custom-customer_user_id",
            "country_of_origin": "US"
        },
        "business": {
            "ein":"912355201",
            "phone_number":"+11232313213"
        }
    }
}'

{
    "id": "Ananda_AccountIntelligence-1761645406795",
    "workflow": "api_individual_onboarding",
    "workflow_id": "36031914-1edb-4b81-8d80-5d50aa07cead",
    "workflow_version": "179.1.0",
    "eval_source": "API",
    "eval_id": "bee41fc8-347a-423d-aaff-58e385358090",
    "eval_start_time": "2025-10-28T09:56:48.268221402Z",
    "eval_end_time": "2025-10-28T09:56:48.503153007Z",
    "decision": "REJECT",
    "decision_at": "2025-10-28T09:56:48.503043807Z",
    "status": "CLOSED",
    "sub_status": "Decline",
    "tags": [],
    "notes": "",
    "review_queues": [],
    "data_enrichments": [
        {
            "enrichment_name": "Socure Account Intelligence PROD SBX",
            "enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
            "enrichment_provider": "Socure",
            "status_code": 200,
            "request": {
                "businessPhone": "+11232313213",
                "city": "Danbury",
                "country": "US",
                "countryOfOrigin": "US",
                "customerUserId": "custom-customer_user_id",
                "dob": "1958-01-31",
                "ein": "912355201",
                "entityName": "sdfd",
                "mobileNumber": "2037986508",
                "modules": [
                    "accountintelligence"
                ],
                "nationalId": "700-01-3784",
                "parentTxnId": "bee41fc8-347a-423d-aaff-58e385358090",
                "payments": {
                    "account": {
                        "accountNumber": "92301962141",
                        "inquiries": [
                            "STATUS",
                            "OWNERSHIP"
                        ],
                        "routingNumber": "122199983"
                    }
                },
                "physicalAddress": "2 Moran Ave",
                "physicalAddress2": "Address Line 2",
                "riskOSId": "Ananda_AccountIntelligence-1761645406795",
                "state": "CT",
                "userId": "data-individual-id",
                "workflow": "api_individual_onboarding",
                "zip": "068100000"
            },
            "response": {
                "accountIntelligence": {
                    "account": {
                        "availabilityScore": 0.49,
                        "ownershipScore": 0.49
                    },
                    "reasonCodes": []
                },
                "customerProfile": {
                    "customerUserId": "custom-customer_user_id",
                    "userId": "data-individual-id"
                },
                "referenceId": "fb0395e6-30b9-4c38-9db0-24d3ddb062e4"
            },
            "is_source_cache": false,
            "total_attempts": 1
        }
    ],
    "computed": {
        "CONDITION": false,
        "socure_accountintelligence_response": {
            "__third_party_name__": "Socure Account Intelligence PROD SBX",
            "accountIntelligence": {
                "account": {
                    "availabilityScore": 0.49,
                    "ownershipScore": 0.49
                },
                "reasonCodes": []
            },
            "customerProfile": {
                "customerUserId": "custom-customer_user_id",
                "userId": "data-individual-id"
            },
            "referenceId": "fb0395e6-30b9-4c38-9db0-24d3ddb062e4"
        }
    },
    "eval_status": "evaluation_completed",
    "environment_name": "Sandbox"
}

Test cases - Unhappy path

Test case 3: Invalid account number

curl --location 'https://riskos.sandbox.socure.com/api/evaluation' \
--header 'accept: application/json' \
--header 'X-API-Version: 2025-01-01.orion' \
--header 'Content-Type: application/json' \
--header 'authorization: Bearer YOUR_API_KEY' \
--data '{
    "id": "Ananda_AccountIntelligence-1761645502459",
    "timestamp": "2025-10-28T09:58:25.594488111Z",
    "workflow": "api_individual_onboarding",
    "data": {
        "line_of_business": "test1",
        "channel": "mobile",
        "individual": {
            "additional_context": {
                
            },
             "account": {
                "account_number": "923019621s41",
                "routing_number": "122199983",
                "account_inquiries": [
                    "AVAILABILITY",
                    "OWNERSHIP"
                ]
            },
            "id": "data-individual-id",
            "given_name": "Ananda",
            "family_name": "test",
            "date_of_birth": "1958-01-31",
            "national_id": "700-01-3784",
            "phone_number": "+1-2037986508",
            "address": {
                "type": "HOME",
                "line_1": "2 Moran Ave",
                "line_2": "Address Line 2",
                "locality": "Danbury",
                "major_admin_division": "CT",
                "country": "US",
                "postal_code": "068100000"
            }
        },
        "custom": {
            "customer_user_id":"custom-customer_user_id",
            "country_of_origin": "US"
        },
        "business": {
            "ein":"912355201",
            "phone_number":"+11232313213"
        }
    }
}'

{
    "id": "Ananda_AccountIntelligence-1761645502459",
    "workflow": "api_individual_onboarding",
    "workflow_id": "36031914-1edb-4b81-8d80-5d50aa07cead",
    "workflow_version": "179.1.0",
    "eval_source": "API",
    "eval_id": "3e4545bf-9914-4fb3-9076-45399e84df7a",
    "eval_start_time": "2025-10-28T09:58:25.594488111Z",
    "eval_end_time": "2025-10-28T09:58:25.675160519Z",
    "decision": "REJECT",
    "decision_at": "2025-10-28T09:58:25.675015459Z",
    "status": "CLOSED",
    "sub_status": "Decline",
    "tags": [],
    "notes": "",
    "review_queues": [],
    "data_enrichments": [
        {
            "enrichment_name": "Socure Account Intelligence PROD SBX",
            "enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
            "enrichment_provider": "Socure",
            "status_code": 400,
            "request": {
                "businessPhone": "+11232313213",
                "city": "Danbury",
                "country": "US",
                "countryOfOrigin": "US",
                "customerUserId": "custom-customer_user_id",
                "dob": "1958-01-31",
                "ein": "912355201",
                "firstName": "Ananda",
                "mobileNumber": "+1-2037986508",
                "modules": [
                    "accountintelligence"
                ],
                "nationalId": "700-01-3784",
                "parentTxnId": "3e4545bf-9914-4fb3-9076-45399e84df7a",
                "payments": {
                    "account": {
                        "accountNumber": "923019621s41",
                        "inquiries": [
                            "STATUS",
                            "OWNERSHIP"
                        ],
                        "routingNumber": "122199983"
                    }
                },
                "physicalAddress": "2 Moran Ave",
                "physicalAddress2": "Address Line 2",
                "riskOSId": "Ananda_AccountIntelligence-1761645502459",
                "state": "CT",
                "surName": "test",
                "userId": "data-individual-id",
                "workflow": "api_individual_onboarding",
                "zip": "068100000"
            },
            "response": {
                "response": "{\"status\":\"Error\",\"referenceId\":\"69bd01bf-1048-4d7e-b9a1-5833fc7caa53\",\"data\":{\"parameters\":[\"Invalid account number. Please resubmit the transaction using proper account number\"]},\"customerProfile\":{\"customerUserId\":\"custom-customer_user_id\",\"userId\":\"data-individual-id\"},\"msg\":\"Invalid account number. Please resubmit the transaction using proper account number\"}"
            },
            "is_source_cache": false,
            "total_attempts": 1
        }
    ],
    "computed": {
        "CONDITION": false,
        "socure_accountintelligence_error": {
            "error_code": "EXTERNAL_ERROR",
            "error_msg": "{\"status\":\"Error\",\"referenceId\":\"69bd01bf-1048-4d7e-b9a1-5833fc7caa53\",\"data\":{\"parameters\":[\"Invalid account number. Please resubmit the transaction using proper account number\"]},\"customerProfile\":{\"customerUserId\":\"custom-customer_user_id\",\"userId\":\"data-individual-id\"},\"msg\":\"Invalid account number. Please resubmit the transaction using proper account number\"}",
            "http_status": 400,
            "is_retryable": false
        }
    },
    "eval_status": "evaluation_completed",
    "environment_name": "Sandbox"
}

Test case 4: Invalid routing number

curl --location 'https://riskos.sandbox.socure.com/api/evaluation' \
--header 'accept: application/json' \
--header 'X-API-Version: 2025-01-01.orion' \
--header 'Content-Type: application/json' \
--header 'authorization: Bearer YOUR_API_KEY' \
--data '{
    "id": "Ananda_AccountIntelligence-1761645548228",
    "timestamp": "2025-10-28T09:59:11.141214973Z",
    "workflow": "api_individual_onboarding",
    "data": {
        "line_of_business": "test1",
        "channel": "mobile",
        "individual": {
            "additional_context": {
                
            },
             "account": {
                "account_number": "92301962141",
                "routing_number": "12219t9983",
                "account_inquiries": [
                    "AVAILABILITY",
                    "OWNERSHIP"
                ]
            },
            "id": "data-individual-id",
            "given_name": "Ananda",
            "family_name": "test",
            "date_of_birth": "1958-01-31",
            "national_id": "700-01-3784",
            "phone_number": "+1-2037986508",
            "address": {
                "type": "HOME",
                "line_1": "2 Moran Ave",
                "line_2": "Address Line 2",
                "locality": "Danbury",
                "major_admin_division": "CT",
                "country": "US",
                "postal_code": "068100000"
            }
        },
        "custom": {
            "customer_user_id":"custom-customer_user_id",
            "country_of_origin": "US"
        },
        "business": {
            "ein":"912355201",
            "phone_number":"+11232313213"
        }
    }
}'

{
    "id": "Ananda_AccountIntelligence-1761645548228",
    "workflow": "api_individual_onboarding",
    "workflow_id": "36031914-1edb-4b81-8d80-5d50aa07cead",
    "workflow_version": "179.1.0",
    "eval_source": "API",
    "eval_id": "3f3cb465-574d-4341-8d20-89f96bfe01ed",
    "eval_start_time": "2025-10-28T09:59:11.141214973Z",
    "eval_end_time": "2025-10-28T09:59:11.170252912Z",
    "decision": "REJECT",
    "decision_at": "2025-10-28T09:59:11.170122862Z",
    "status": "CLOSED",
    "sub_status": "Decline",
    "tags": [],
    "notes": "",
    "review_queues": [],
    "data_enrichments": [
        {
            "enrichment_name": "Socure Account Intelligence PROD SBX",
            "enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
            "enrichment_provider": "Socure",
            "status_code": 400,
            "request": {
                "businessPhone": "+11232313213",
                "city": "Danbury",
                "country": "US",
                "countryOfOrigin": "US",
                "customerUserId": "custom-customer_user_id",
                "dob": "1958-01-31",
                "ein": "912355201",
                "firstName": "Ananda",
                "mobileNumber": "+1-2037986508",
                "modules": [
                    "accountintelligence"
                ],
                "nationalId": "700-01-3784",
                "parentTxnId": "3f3cb465-574d-4341-8d20-89f96bfe01ed",
                "payments": {
                    "account": {
                        "accountNumber": "92301962141",
                        "inquiries": [
                            "STATUS",
                            "OWNERSHIP"
                        ],
                        "routingNumber": "12219t9983"
                    }
                },
                "physicalAddress": "2 Moran Ave",
                "physicalAddress2": "Address Line 2",
                "riskOSId": "Ananda_AccountIntelligence-1761645548228",
                "state": "CT",
                "surName": "test",
                "userId": "data-individual-id",
                "workflow": "api_individual_onboarding",
                "zip": "068100000"
            },
            "response": {
                "response": "{\"status\":\"Error\",\"referenceId\":\"5d6f845e-9ee4-4779-a67c-f7c535fd6a25\",\"data\":{\"parameters\":[\"Invalid routing number. Please resubmit the transaction using proper routing number\"]},\"customerProfile\":{\"customerUserId\":\"custom-customer_user_id\",\"userId\":\"data-individual-id\"},\"msg\":\"Invalid routing number. Please resubmit the transaction using proper routing number\"}"
            },
            "is_source_cache": false,
            "total_attempts": 1
        }
    ],
    "computed": {
        "CONDITION": false,
        "socure_accountintelligence_error": {
            "error_code": "EXTERNAL_ERROR",
            "error_msg": "{\"status\":\"Error\",\"referenceId\":\"5d6f845e-9ee4-4779-a67c-f7c535fd6a25\",\"data\":{\"parameters\":[\"Invalid routing number. Please resubmit the transaction using proper routing number\"]},\"customerProfile\":{\"customerUserId\":\"custom-customer_user_id\",\"userId\":\"data-individual-id\"},\"msg\":\"Invalid routing number. Please resubmit the transaction using proper routing number\"}",
            "http_status": 400,
            "is_retryable": false
        }
    },
    "eval_status": "evaluation_completed",
    "environment_name": "Sandbox"
}

Test case 5: IInvalid phone number

curl --location 'https://riskos.sandbox.socure.com/api/evaluation' \
--header 'accept: application/json' \
--header 'X-API-Version: 2025-01-01.orion' \
--header 'Content-Type: application/json' \
--header 'authorization: Bearer YOUR_API_KEY' \
--data '{
    "id": "Ananda_AccountIntelligence-1761645592583",
    "timestamp": "2025-10-28T09:59:56.077836199Z",
    "workflow": "api_individual_onboarding",
    "data": {
        "line_of_business": "test1",
        "channel": "mobile",
        "individual": {
            "additional_context": {
                
            },
             "account": {
                "account_number": "92301962141",
                "routing_number": "122199983",
                "account_inquiries": [
                    "AVAILABILITY",
                    "OWNERSHIP"
                ]
            },
            "id": "data-individual-id",
            "given_name": "Ananda",
            "family_name": "test",
            "date_of_birth": "1958-01-31",
            "national_id": "700-01-3784",
            "phone_number": "+1-203127986508",
            "address": {
                "type": "HOME",
                "line_1": "2 Moran Ave",
                "line_2": "Address Line 2",
                "locality": "Danbury",
                "major_admin_division": "CT",
                "country": "US",
                "postal_code": "068100000"
            }
        },
        "custom": {
            "customer_user_id":"custom-customer_user_id",
            "country_of_origin": "US"
        },
        "business": {
            "ein":"912355201",
            "phone_number":"+11232313213"
        }
    }
}'

{
    "id": "Ananda_AccountIntelligence-1761645592583",
    "workflow": "api_individual_onboarding",
    "workflow_id": "36031914-1edb-4b81-8d80-5d50aa07cead",
    "workflow_version": "179.1.0",
    "eval_source": "API",
    "eval_id": "bd472d6f-b4c1-46ff-95ca-0ab44d65351b",
    "eval_start_time": "2025-10-28T09:59:56.077836199Z",
    "eval_end_time": "2025-10-28T09:59:56.138004338Z",
    "decision": "REJECT",
    "decision_at": "2025-10-28T09:59:56.137846578Z",
    "status": "CLOSED",
    "sub_status": "Decline",
    "tags": [],
    "notes": "",
    "review_queues": [],
    "data_enrichments": [
        {
            "enrichment_name": "Socure Account Intelligence PROD SBX",
            "enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
            "enrichment_provider": "Socure",
            "status_code": 400,
            "request": {
                "businessPhone": "+11232313213",
                "city": "Danbury",
                "country": "US",
                "countryOfOrigin": "US",
                "customerUserId": "custom-customer_user_id",
                "dob": "1958-01-31",
                "ein": "912355201",
                "firstName": "Ananda",
                "mobileNumber": "+1-203127986508",
                "modules": [
                    "accountintelligence"
                ],
                "nationalId": "700-01-3784",
                "parentTxnId": "bd472d6f-b4c1-46ff-95ca-0ab44d65351b",
                "payments": {
                    "account": {
                        "accountNumber": "92301962141",
                        "inquiries": [
                            "STATUS",
                            "OWNERSHIP"
                        ],
                        "routingNumber": "122199983"
                    }
                },
                "physicalAddress": "2 Moran Ave",
                "physicalAddress2": "Address Line 2",
                "riskOSId": "Ananda_AccountIntelligence-1761645592583",
                "state": "CT",
                "surName": "test",
                "userId": "data-individual-id",
                "workflow": "api_individual_onboarding",
                "zip": "068100000"
            },
            "response": {
                "response": "{\"status\":\"Error\",\"referenceId\":\"b8e2c3fb-934c-4a39-bc23-6221da6d5229\",\"data\":{\"parameters\":[\"Invalid phone number. Please resubmit the transaction using a phone number conforming to E.164 format.\"]},\"customerProfile\":{\"customerUserId\":\"custom-customer_user_id\",\"userId\":\"data-individual-id\"},\"msg\":\"Invalid phone number. Please resubmit the transaction using a phone number conforming to E.164 format.\"}"
            },
            "is_source_cache": false,
            "total_attempts": 1
        }
    ],
    "computed": {
        "CONDITION": false,
        "socure_accountintelligence_error": {
            "error_code": "EXTERNAL_ERROR",
            "error_msg": "{\"status\":\"Error\",\"referenceId\":\"b8e2c3fb-934c-4a39-bc23-6221da6d5229\",\"data\":{\"parameters\":[\"Invalid phone number. Please resubmit the transaction using a phone number conforming to E.164 format.\"]},\"customerProfile\":{\"customerUserId\":\"custom-customer_user_id\",\"userId\":\"data-individual-id\"},\"msg\":\"Invalid phone number. Please resubmit the transaction using a phone number conforming to E.164 format.\"}",
            "http_status": 400,
            "is_retryable": false
        }
    },
    "eval_status": "evaluation_completed",
    "environment_name": "Sandbox"
}

Best practices for integration and maintenance

Validate inputs → Always validate API request payloads against the published schema before sending.
Test thoroughly → Use sandbox mode and the provided test personas to simulate availability and ownership scenarios before moving to production.
Monitor transparency signals → Enable and track reasonCodes and sourceAttribution in responses. These provide explainability for decisions and are critical for audits.
Automate routing logic → Leverage decision, tags, and review_queues to automatically route cases in your RiskOS™ workflow (e.g., auto-approve PASS, escalate REVIEW).
Maintain audit logs → Store both request payloads and Socure responses securely for compliance, dispute resolution, and continuous improvement.

Validation checklist

Test coverage

Known good identities → APPROVE

Bad or mismatched identities → REJECT or REVIEW

Edge cases logged and 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 and response

Include correlation IDs

Redact secrets from logs

Exception routing

Escalation paths defined for REVIEW

Support team has access to logs and scores

Socure Account Intelligence API integration guide

Before you start

Choose your environment

Get an API key

How it works

Example frontend input form (mapped to /api/evaluation payload)

Start a new Risk Evaluation

Endpoint

Authentication and headers

Example request: Account AVAILABILITY

Request schema

Top-level fields

individual.account fields

Example request: Account OWNERSHIP

Request schema

Top-level fields

individual fields

account fields

Example request: Account AVAILABILITY and OWNERSHIP

Example response

Key response fields

Where to find specific results

Decision and routing (primary control signals)

Evaluation lifecycle and status

Identifiers and traceability

Execution context

Enrichment results

request fields

response fields

Sandbox test cases

Test cases - Happy path

Test case 1: Verify the availability and ownership of a consumer account

Test case 2: Verify the availability and ownership of a business account

Test cases - Unhappy path

Test case 3: Invalid account number

Test case 4: Invalid routing number

Test case 5: IInvalid phone number

Best practices for integration and maintenance

Validation checklist

Test coverage

Schema and error handling

Logging and observability

Exception routing

Example frontend input form (mapped to `/api/evaluation` payload)

Example request: Account `AVAILABILITY`

`individual.account` fields

Example request: Account `OWNERSHIP`

`individual` fields

`account` fields

Example request: Account `AVAILABILITY` and `OWNERSHIP`

`request` fields

`response` fields