Integrate Socure Verify

Learn how to call the RiskOS™ Evaluation API for identity verification with Socure Verify or Verify Plus.

Before you start

Make sure your RiskOS™ environment is provisioned with:

A workflow configured for the Verify or Verify Plus enrichment.

Regional support coverage for the Verify or Verify Plus 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.

Common integration patterns

The table below outlines common integration patterns for Socure Verify and Verify Plus. Fields vary by country based on locally accepted identity documents and regulatory standards. Contact your account executive for country-specific details.

Module	Fields	Response
kycplus	Name, DOB, national ID, address, email, phone	Full profile + audit trail
kyc	Name, DOB, national ID, address, email, phone	Match score + reason codes

Note:

📘
Verify Plus is only available in the United States. For international workflows, use Verify.

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
Date of Birth → date_of_birth
National ID → national_id

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

{
  "id": "APP-987654",
  "timestamp": "2025-08-13T06:10:54.298Z",
  "workflow": "consumer_onboarding",
  "data": {
    "individual": {
      "given_name": "Jonathan",
      "family_name": "Reyes",
      "national_id": "1234",
      "phone_number": "+639171234567",
      "email": "[email protected]",
      "date_of_birth": "1979-07-30",
      "ip_address": "203.87.128.100",
      "address": {
        "line_1": "123 Rizal Avenue",
        "locality": "Portland",
        "major_admin_division": "OR",
        "postal_code": "85142",
        "country": "US"
      }
    }
  }
}

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": "APP-987654",
  "timestamp": "2025-08-13T06:10:54.298Z",
  "workflow": "consumer_onboarding",
  "data": {
    "individual": {
      "given_name": "Jonathan",
      "family_name": "Reyes",
      "national_id": "1234",
      "phone_number": "+639171234567",
      "email": "[email protected]",
      "date_of_birth": "1979-07-30",
      "ip_address": "203.87.128.100",
      "address": {
        "street_address": "123 Rizal Avenue",
        "locality": "Portland",
        "major_admin_division": "OR",
        "postal_code": "85142",
        "country": "US"
      }
    }
  }
}'

Request schema

Top-level fields

Field	Type	Required	Description	Example
`id`	String	Required	Required, customer-defined unique identifier for the request. This value must be unique for each evaluation. Reusing an ID causes RiskOS™ to treat the request as a re-run and can impact processing behavior, results, and downstream workflows.	`"APP-987654"`
`timestamp`	String	Required	Timestamp when evaluation was initiated.	`"2025-05-18T02:09:25Z"`
`workflow`	String	Required	RiskOS™ workflow name configured in your environment. Note: The workflow name must be unique within your RiskOS™ environment. It is not scoped by use case and must identify a single active workflow for each Evaluation API request.	`"business_onboarding"`
`data`	Object	Required	Main payload containing business and individual information.
→`individual`	Object	Required	Primary identity object containing individual's information.	See `individual` schema below.

`individual` fields

Validation rules & accuracy guidance

These rules ensure RiskOS™ has enough information to perform a reliable identity match.

Identity Verification Requirements

At least ONE of the following combinations must be provided:

Name + Date of Birth
- given_name + family_name + date_of_birth
Name + Phone
- given_name + family_name + phone_number
Name + Address
- given_name + family_name + address
National ID (Standalone)
- national_id (can be provided alone or with other fields)
- U.S.: Full SSN/TIN or last 4 digits of SSN
- Other countries: Full government-issued ID

Accuracy Guidance

More PII fields = higher matching accuracy and coverage. Recommended combinations:

Best Accuracy
- national_id (full SSN/TIN) + given_name / family_name + date_of_birth + phone_number + address
Better Accuracy
- given_name / family_name + date_of_birth + phone_number + address
Good Accuracy
- given_name / family_name + any two additional fields
Minimum Viable
- given_name / family_name + one additional field
- OR national_id alone (last 4 SSN requires additional fields for verification)
- OR phone_number + date_of_birth

Field	Type	Required	Description	Example
`given_name`	String	Conditionally Required	First name of the individual.	`"Jonathan"`
`family_name`	String	Conditionally Required	Last name of the individual.	`"Reyes"`
`national_id`	String	Conditionally Required	Government-issued ID (last 4 SSN for U.S., full ID for others).	`"1234"`
`date_of_birth`	String	Conditionally Required	Date of birth in `YYYY-MM-DD` format.	`"1979-07-30"`
`email`	String	Optional	Individual’s email address.	`"[email protected]"`
`phone_number`	String	Conditionally Required	Phone number in E.164 format. The API expects the standard E.164 format but tolerates hyphens and spaces for user convenience.	`"+639171234567"`
`ip_address`	String	Optional	IP address in IPv4 or IPv6 format.	`"203.87.128.100"`
`address`	Object	Conditionally Required	Residential address of the individual.	See `address` schema below.

`address`

Field	Type	Required	Description	Example
`line_1`	String	Required	Street name and number.	`"123 Rizal Avenue"`
`locality`	String	Required	City or locality.	`"Portland"`
`major_admin_division`	String	Required	State, province, or region.	`"OR"`
`postal_code`	String	Required	Postal or ZIP code.	`"85142"`
`country`	String	Required	Two-letter ISO 3166-1 alpha-2 country code.	`"US"`

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": "APP-987654",
  "workflow": "api_individual_onboarding",
  "workflow_id": "fae769dc-832f-4619-a386-54873b8861e5",
  "workflow_version": "65.1.0",
  "eval_source": "API",
  "eval_id": "c9e53a0f-35f4-4d18-bf26-ec1788c9f47a",
  "eval_start_time": "2025-11-17T20:03:49.123613925Z",
  "eval_end_time": "2025-11-17T20:03:49.686548734Z",
  "decision": "ACCEPT",
  "decision_at": "2025-11-17T20:03:49.686428264Z",
  "status": "CLOSED",
  "sub_status": "Accept",
  "tags": [
    "low_id_coverage",
    "manual_review_required"
  ],
  "notes": "",
  "review_queues": [
    "kyc-apac-philippines"
  ],
  "data_enrichments": [
    {
      "enrichment_name": "Socure KYC PROD SBX",
      "enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {
        "city": "Danbury",
        "consentTimestamp": "2025-11-17T20:03:48.252000Z",
        "country": "US",
        "countryOfOrigin": "US",
        "customerUserId": "custom-customer_user_id",
        "date_of_birth": "1958-01-31",
        "firstName": "Ananda",
        "gender": "Male",
        "homeNumber": "+1-203-798-6508",
        "mobileNumber": "+12037986508",
        "modules": [
          "kyc"
        ],
        "nationalId": "700-01-3784",
        "parentTxnId": "bcbb1fef-c125-42ea-a059-aee00381835f",
        "physicalAddress": "2 Moran Ave",
        "physicalAddress2": "Address line 2",
        "riskOSId": "Effectiv-Test-kyc-1763409828252",
        "state": "CT",
        "surName": "test",
        "userConsent": true,
        "userId": "data-individual-id",
        "workflow": "api_individual_onboarding",
        "zip": "06810"
      },
      "response": {
        "kyc": {
          "socureId": "0318d3c3-541c-4090-8250-dec3e41efa89",
          "nationalId": "786-00-1234",
          "reasonCodes": [
            "I919"
          ],
          "fieldValidations": {
            "city": 0.99,
            "dob": 0.99,
            "driverLicense": 0.99,
            "email": 0.99,
            "firstName": 0.99,
            "mobileNumber": 0.99,
            "ssn": 0.99,
            "state": 0.99,
            "streetAddress": 0.99,
            "surName": 0.99,
            "zip": 0.99
          },
          "sourceAttribution": [
            "Credit",
            "Government",
            "Education"
          ],
          "transactionScope": "international",
          "callType": "2X2",
          "matchCounts": {
            "tradelines": 3
          },
          "fieldSourceAttribution": {
            "firstName": ["Government"],
            "surName": ["Government"],
            "ssn": ["Government"]
          }
        },
        "referenceId": "8d92942e-af40-47b3-9b19-3f13456f401b",
        "customerProfile": {
          "userId": "data-individual-id",
          "customerUserId": "custom-customer_user_id"
        }
      },
      "is_source_cache": false,
      "total_attempts": 1
    }
  ],
  "computed": {
    "CONDITION": true,
    "socure_kyc_response": {
      "__third_party_name__": "Socure KYC PROD SBX",
      "kyc": {
        "socureId": "0318d3c3-541c-4090-8250-dec3e41efa89",
        "nationalId": "786-00-1234",
        "reasonCodes": [
          "I919"
        ],
        "fieldValidations": {
          "city": 0.99,
          "dob": 0.99,
          "driverLicense": 0.99,
          "email": 0.99,
          "firstName": 0.99,
          "mobileNumber": 0.99,
          "ssn": 0.99,
          "state": 0.99,
          "streetAddress": 0.99,
          "surName": 0.99,
          "zip": 0.99
        },
        "sourceAttribution": [
          "Credit",
          "Government",
          "Education"
        ],
        "transactionScope": "international",
        "callType": "2X2",
        "matchCounts": {
          "tradelines": 3
        },
        "fieldSourceAttribution": {
          "firstName": ["Government"],
          "surName": ["Government"],
          "ssn": ["Government"]
        }
      },
      "referenceId": "8d92942e-af40-47b3-9b19-3f13456f401b",
      "customerProfile": {
        "userId": "data-individual-id",
        "customerUserId": "custom-customer_user_id"
      }
    }
  },
  "aggregations": { },
  "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)

These fields describe the outcome of an evaluation and any routing applied by the workflow.

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.	`"ACCEPT"`
`decision_at`	String <Date-Time>	RFC 3339 timestamp when the decision was finalized.	`"2025-11-17T20:03:49.686428264Z"`
`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.	Not returned
`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.	`["low_id_coverage", "manual_review_required"]`
`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.	`["kyc-apac-philippines"]`
`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	Internal RiskOS™ evaluation lifecycle state. Possible values: • `evaluation_completed` • `evaluation_paused` • `evaluation_in_progress`	`"evaluation_completed"`
`status`	String enum	Case-level status of the evaluation. Possible values: • `OPEN` • `CLOSED`	`"CLOSED"`
`sub_status`	String	Provides additional detail about the evaluation status. Example values: • `Under Review` • `Pending Verification` • `Accept` • `Reject`	`"Accept"`

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.	`"APP-987654"`
`eval_id`	String (UUID)	RiskOS™-generated unique identifier for the evaluation.	`"c9e53a0f-35f4-4d18-bf26-ec1788c9f47a"`
`workflow`	String	Name of the workflow executed.	`"api_individual_onboarding"`
`workflow_id`	String (UUID)	Unique identifier for the workflow run.	`"fae769dc-832f-4619-a386-54873b8861e5"`
`workflow_version`	String	Version of the executed workflow.	`"65.1.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.	`"2025-11-17T20:03:49.123613925Z"`
`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.	`"2025-11-17T20:03:49.686548734Z"`
`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. Each object corresponds to a module executed as part of the Consumer Onboarding workflow.

Field	Type	Description	Example
`enrichment_name`	String	Name of the enrichment executed.	`"Socure KYC PROD SBX"`
`enrichment_provider`	String	Provider of the enrichment.	`"Socure"`
`status_code`	Integer	HTTP status returned by the enrichment call.	`200`
`request`	Object	Provider request payload (for observability and debugging).	See `request` schema below.
`response`	Object	Normalized enrichment response.	See `response` schema below.
`is_source_cache`	Boolean	Indicates whether cached data was used.	`false`
`total_attempts`	Integer	Number of attempts made to retrieve the data.	`1`

`request` fields

Field	Type	Description	Example
`country`	String	ISO 3166-1 alpha-2 country code.	`"US"`
`firstName`	String	Consumer’s given name.	`"Jonathan"`
`surName`	String	Consumer’s family name.	`"Reyes"`
`nationalId`	String	Government-issued identifier (SSN, national ID, etc.).	`"786-00-1234"`
`dob`	String (YYYY-MM-DD)	Consumer’s date of birth.	`"1979-07-30"`
`streetAddress`	String	Street address of residence.	`"123 Rizal Avenue"`
`city`	String	City of residence.	`"Portland"`
`state`	String	State, province, or region.	`"OR"`
`zip`	String	Postal or ZIP code.	`"85142"`
`ipAddress`	String	IP address observed during the session.	`"203.87.128.100"`
`phone`	String	Phone number in E.164 format.	`"+639171234567"`
`email`	String	Consumer’s email address.	`"[email protected]"`

`response` fields

The response root contains only the enrichment results object (kyc for standard Verify, or kycPlus for Verify Plus), the referenceId, and customerProfile. Identity signals such as socureId, sourceAttribution, callType, and transactionScope are nested inside the kyc or kycPlus object.

Field	Type	Description	Example
`kyc`	Object	Results from the standard Verify evaluation.	See the `kyc` schema in the following section.
`kycPlus`	Object	Results from the Verify Plus evaluation.	See the `kycPlus` schema in the following section.
`referenceId`	String (UUID)	Unique identifier assigned to each enrichment after a RiskOS™ workflow is finalized.	`"f3863a33-69ca-43c2-90e0-8b4344a41a09"`
`customerProfile`	Object	The user identifiers you provided in the request, echoed back.	See the `customerProfile` schema in the following section.

`customerProfile` fields

Field	Type	Description	Example
`userId`	String	The `data.individual` identifier echoed back from your request.	`"data-individual-id"`
`customerUserId`	String	The customer-defined user identifier echoed back from your request.	`"custom-customer_user_id"`

`kyc` fields (standard Verify)

Field	Type	Description	Example
`socureId`	String (UUID)	Socure's persistent identity identifier used for cross-module correlations.	`"0318d3c3-541c-4090-8250-dec3e41efa89"`
`nationalId`	String or Null	National identification number associated with the best-matched entity.	`"786-00-1234"`
`creditFileNumber`	String or Null	The credit file number returned for the consumer when a credit bureau in Canada validates the transaction. Requires special provisioning and is applicable to Canada only.	`"00512123456"`
`reasonCodes`	Array of Strings	Decision reasons (for example, `"I919"`).	`["I919"]`
`fieldValidations`	Object	Confidence scores (0–1) for each submitted field. See the `fieldValidations` schema in the following section.	`{"firstName": 0.99, "ssn": 0.99}`
`sourceAttribution`	Array of Strings	High-level data source categories used in the verification.	`["Credit", "Government", "Education"]`
`transactionScope`	String	Indicates the scope of the transaction (domestic or international).	`"international"`
`callType`	String	Indicates the verification call type used. Returns `"2X2"` when 2X2 is enabled for the transaction.	`"2X2"`
`matchCounts`	Object	Contains match counts by category. International transactions only (United Kingdom, when 2X2 is enabled).	`{"tradelines": 3}`
`fieldSourceAttribution`	Object	Mapping of specific PII fields to the authoritative sources that verified them. International transactions only.	`{"ssn": ["Social Security Administration"], "address": ["USPS"]}`

`fieldValidations` fields

Field	Type	Description	Example
`firstName`	Number	Match score for first name. `0.99` indicates a match; `0.01` indicates no match.	`0.99`
`surName`	Number	Match score for surname. `0.99` indicates a match; `0.01` indicates no match.	`0.99`
`streetAddress`	Number	Match score for street address. `0.99` indicates a match; `0.01` indicates no match.	`0.99`
`city`	Number	Match score for city. `0.99` indicates a match; `0.01` indicates no match.	`0.99`
`state`	Number	Match score for state. `0.99` indicates a match; `0.01` indicates no match.	`0.99`
`zip`	Number	Match score for ZIP code. `0.99` indicates a match; `0.01` indicates no match.	`0.99`
`mobileNumber`	Number	Match score for phone number. `0.99` indicates a match; `0.01` indicates no match.	`0.99`
`dob`	Number	Match score for date of birth. `0.99` indicates a match; `0.01` indicates no match.	`0.99`
`ssn`	Number	Match score for Social Security Number or Individual Tax Identification Number. `0.99` indicates a match; `0.01` indicates no match.	`0.99`
`email`	Number	Match score for email address. `0.99` indicates a match; `0.01` indicates no match.	`0.99`
`driverLicense`	Number	Match score for driver license number. `0.99` indicates a match; `0.01` indicates no match.	`0.99`

`kycPlus` fields

Field	Type	Description	Example
`socureId`	String (UUID)	Socure's persistent identity identifier used for cross-module correlations.	`"819509ab-5ab8-475c-a084-5f209dcff940"`
`nationalId`	String or null	National identification number (SSN or ITIN) associated with the best-matched entity.	`"786-00-1234"`
`reasonCodes`	Array of Strings	Decision reasons (for example, `"I919"`, `"R948"`).	`["I919", "R948"]`
`fieldValidations`	Object	Confidence scores (0–1) for each submitted field. See the `fieldValidations` schema above.	`{"nationalId": 0.01}`
`sourceAttribution`	Array of Strings	Data sources used in the verification process.	`["Credit", "Property Tax"]`
`transactionScope`	String	Indicates the scope of the transaction (domestic or international).	`"international"`
`bestMatchedEntity`	Object	The best identity match returned.	See `bestMatchedEntity` schema below.
`sportLeague`	Array of strings or null	The sports league associated with the entity.	`["NFL"]`
`connections`	Array of objects or null	Identities connected to the best-matched entity in the Socure Identity Graph. See `connections` schema below.	See `connections` schema below.

`bestMatchedEntity` fields

Field	Type	Description	Example
`firstName`	String	Resolved first name.	`"Jonathan"`
`middleName`	String or Null	Resolved middle name.	`null`
`surName`	String	Resolved last name.	`"Reyes"`
`suffix`	String or Null	Suffix (e.g., `"Jr."`).	`null`
`ssn`	String	Resolved SSN or national ID.	`"786-00-1234"`
`ssnIssued`	String	Year or range when SSN was issued.	`"1999-2000"`
`dob`	String (YYYY-MM-DD)	Resolved date of birth.	`"1999-07-05"`
`mobileNumber`	String	Resolved phone number.	`"+13475550100"`
`emailAddress`	String	Resolved email address.	`"[email protected]"`
`deceasedDate`	String or Null	Date of death, if applicable.	`null`
`driverLicense`	String or Null	Driver license number.	`null`
`normalizedAddress`	Object	Standardized address.	See schema below.
`associatedPhoneNumbers`	Array of Objects	Phones linked to the identity.	See schema below.
`associatedAddresses`	Array of Objects	Addresses linked to the identity.	See schema below.
`associatedEmails`	Array of Objects	Emails linked to the identity.	See schema below.

`normalizedAddress` fields

Field	Type	Description	Example
`streetAddress`	String	The street address of the normalized input address.	`"123 Rizal Avenue"`
`city`	String	The city in which the normalized input address is located.	`"Portland"`
`state`	String	The state in which the normalized input address is located.	`"OR"`
`zip`	String	The ZIP code in which the normalized input address is located.	`"97223"`
`firstSeenDate`	String (YYYY-MM-DD)	The date the address was first observed.	`"2010-03-01"`
`lastSeenDate`	String (YYYY-MM-DD)	The date of the most recent presentation of the data.	`"2024-11-18"`
`lastSeenDateTrx`	String (YYYY-MM-DD)	The date of the most recent transaction in which the data was presented.	`"2024-11-18"`
`county`	String	The county in which the normalized input address is located.	`"Washington"`
`isMatched`	Boolean	Indicates whether this address matched the input address.	`true`
`isLatest`	Boolean	Indicates whether this is the most recent (current) address for the best-matched entity.	`true`

`associatedPhoneNumbers` fields

Field	Type	Description	Example
`phoneNumber`	String	The phone number in E.164 format, including country code.	`"+12063588927"`
`firstSeenDate`	String (YYYY-MM-DD)	The date the phone number was first observed.	`"2010-03-01"`
`lastSeenDate`	String (YYYY-MM-DD)	The timestamp of the most recent presentation of the data.	`"2023-05-08"`
`isMatched`	Boolean	Indicates whether the phone number was matched to the best-matched entity.	`true`
`isLatest`	Boolean	Indicates whether this phone number is the most recent (current) number associated with the best-matched entity.	`true`

`associatedAddresses` fields

Field	Type	Description	Example
`streetAddress`	String	The street address, including house number and street name.	`"108 Smokerise Blvd"`
`city`	String	The city where the address is located.	`"Longwood"`
`state`	String	The two-letter U.S. state abbreviation.	`"FL"`
`zip`	String	The ZIP code or postal code for the address.	`"32779-3315"`
`firstSeenDate`	String (YYYY-MM-DD)	The date the address was first observed.	`"2022-03-01"`
`lastSeenDate`	String (YYYY-MM-DD)	The date of the most recent presentation of the data.	`"2024-11-18"`
`lastSeenDateTrx`	String (YYYY-MM-DD)	The date of the most recent transaction in which the data was presented.	`"2024-11-18"`
`county`	String	The county associated with the best-matched entity’s address.	`"Seminole"`
`isMatched`	Boolean	Indicates whether the address was matched to the best-matched entity.	`true`
`isLatest`	Boolean	Indicates whether this address is the most recent (current) address associated with the best-matched entity.	`false`

`associatedEmails` fields

Field	Type	Description	Example
`emailAddress`	String	The email address associated with the best-matched entity.	`"[email protected]"`
`firstSeenDate`	String (YYYY-MM-DD)	The date the email address was first observed.	`"1999-09-12"`
`lastSeenDate`	String (YYYY-MM-DD)	The date of the most recent presentation of the data.	`"2010-09-13"`
`isMatched`	Boolean	Indicates whether the email was matched to the best-matched entity.	`true`
`isLatest`	Boolean	Indicates whether this is the most recent (current) associated email.	`false`

`connections` fields

Field	Type	Description	Example
`socureId`	String or null	The Socure ID of the connected entity.	`"ff6bc013-5cd9-44d5-9da4-bdb04b4003ee"`
`fullName`	String	The full name of the connected entity.	`"Melissa Smith"`

Apply routing logic

Apply the decision parameter to your application:

if response.get("decision") == "ACCEPT":
    proceed_with_onboarding()
elif response.get("decision") == "REVIEW":
    trigger_manual_review(queue=response.get("review_queues", ["Default"])[0])
elif response.get("decision") == "REJECT":
    reject_application(reason="Identity verification failed")
else:
    log_warning("Unknown decision value", response.get("decision"))

Use RiskOS™ logs to trace enrichment execution and reason code evaluation logic. For auditability, log the full response payload and decision scores per field.

Best practices for integration and maintenance

Always validate API inputs against the expected schema.
Use sandbox mode and known test identities during QA.
Enable and monitor reasonCodes and sourceAttribution for transparency and auditability.
Use decision, tags, and review_queues to drive routing logic in your RiskOS™ workflow.
Log and store evaluation payloads and responses for compliance, dispute resolution, and improvement.

Other relevant API endpoints exposed via RiskOS™

RiskOS™ supports a range of identity verification use cases through modular API endpoints. These modules can be configured independently or combined within workflows to meet regional compliance requirements, fraud detection strategies, and onboarding needs.

Validation checklist

Test coverage

Known good identities → ACCEPT

Bad/mismatched identities → REJECT or REVIEW

Edge cases logged + reviewed

Schema & error handling

Fields match schema across environments

Errors are structured and retryable

Use exponential fallback with jitter for resubmissions

Logging & observability

Log full request/response

Include correlation IDs

Redact secrets from logs

Exception routing

Escalation paths defined for REVIEW

Support team has access to logs + scores

Updated 3 days ago

Did this page help you?

Before you start

Choose your environment

Get an API key

How it works

Common integration patterns

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

Start a new Risk Evaluation

Endpoint

Authentication and headers

Example request

Request schema

Top-level fields

individual fields

address

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

customerProfile fields

kyc fields (standard Verify)

fieldValidations fields

kycPlus fields

bestMatchedEntity fields

normalizedAddress fields

associatedPhoneNumbers fields

associatedAddresses fields

associatedEmails fields

connections fields

Apply routing logic

Best practices for integration and maintenance

Other relevant API endpoints exposed via RiskOS™

Validation checklist

Test coverage

Schema & error handling

Logging & observability

Exception routing

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

`individual` fields

`address`

`request` fields

`response` fields

`customerProfile` fields

`kyc` fields (standard Verify)

`fieldValidations` fields

`kycPlus` fields

`bestMatchedEntity` fields

`normalizedAddress` fields

`associatedPhoneNumbers` fields

`associatedAddresses` fields

`associatedEmails` fields

`connections` fields