Unit21 can execute entity verifications according to steps defined in system workflows when a new entity is added to the system, an update is made to an existing entity, or by directly triggering an API endpoint.
Workflows can be configured to run against any number of provider services with execution logic based on the results of each service. Workflows can also be configured to run over a re-screening time period on specific entities.
Verification Results can then be received via a webhook or in some cases a synchronous response (synchronous workflows are currently only enabled by the Unit21 team member). Alerts can also be configured to be created when an entity fails a verification workflow. A generated alert can then in turn be tracked for agents' decisions about the entity.
Before running a verification ensure that the necessary Verification Services API Keys
have been added. To modify and view the keys go to https://<DASHBOARD_ENDPOINT>/settings/verifications
in the dashboard or by going to the settings page and clicking the Verifications
tab. All API keys stored in the database are encrypted.
Note: This action requires edit:verifications_config
permission.
Verification Requests
Request fields to run a verification workflow detailed in the table below. Note that the full, raw verification results are not returned by default.
To get the full verification results, use the include_full_response
parameter, or make a separate API call to /verification/result/<verification_result_id>
.
Note that include_full_response
can only be used if synchronous_response
is set to true
.
Field | Type | Description |
---|---|---|
workflow_id | String | A unique identifier defined at workflow creation. |
synchronous_response | Boolean | Whether or not to immediately execute the workflow & receive a verification response as part of the API request response. If synchronous_response is true for a workflow that doesn't allow synchronous responses, this will throw an error. This is an optional field and will default to false. |
include_full_response | Boolean | Include the full, raw, verification results. This option can only be used if synchronous_response is set to true , or a 400 Bad Request will be returned. This is an optional field and will default to false . |
curl -X POST \
https://<API_ENDPOINT>/v1/entities/<ENTITY_ID>/verify \
-H 'Content-Type: application/json' \
-H 'u21-key: <YOUR_API_KEY>' \
-d '{
"workflow_id": "sanctions_check_1",
"synchronous_response": true,
"include_full_response": true
}'
Response fields:
Field | Type | Description |
---|---|---|
end_action | String | The end result of the workflow, one of a set of end results defined by the workflow |
is_success | Boolean | Whether or not the workflow successful completed. Workflows rely on external services, which may at times fail |
results | Object | Object mapping from the executed verification (e.g. IDOLOGY:DOC_VERIFICATION ) to the result |
full_response | Object | The raw response from the verification provider. Contents depend on the verification source and type. |
HTTP/1.1 200 OK
Content-Type: application/json
{
"end_action": "$REJECT",
"is_success": true,
"results": {
"IDOLOGY:DOC_VERIFICATION": {
"parsed_result": "CAPTURE_NOT_APPROVED",
"verification_result_id": 73
},
"IDOLOGY:ID_VERIFICATION": {
"parsed_result": "ID_NON_MATCH",
"verification_result_id": 71
},
"IDOLOGY:WATCHLIST_SCREENING": {
"parsed_result": "NO_RESTRICTION",
"verification_result_id": 72
}
},
"full_response": {...} // Dependent on the verification source/type
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"entity_id": "userA-ef3c5d41-6bc4-4071-b6fd-7dd77c80a5e8",
"unit21_id": "123",
"verification_workflow_result": {
"end_action": "$REJECT",
"is_success": true,
"results": {
"IDOLOGY:DOC_VERIFICATION": {
"parsed_result": "CAPTURE_NOT_APPROVED",
"verification_result_id": 73,
"full_response": {...} // Dependent on the verification source/type
},
"IDOLOGY:ID_VERIFICATION": {
"parsed_result": "ID_NON_MATCH",
"verification_result_id": 71
"full_response": {...} // Dependent on the verification source/type
},
"IDOLOGY:WATCHLIST_SCREENING": {
"parsed_result": "NO_RESTRICTION",
"verification_result_id": 72
"full_response": {...} // Dependent on the verification source/type
}
},
}
}
Linking external Verification Results
Verification results created external to the Unit21 system can be ingested via this endpoint and linked with a pre-existing entity.
An example process involving this endpoint may be as follows:
- Create an entity
- Link entity from step 1 with an externally created verification result using /link-verification-result endpoint.
- (optional) Create/update an alert and link it with verification result using the verification_result_id returned from step 2.
curl -X POST \
https://<API_ENDPOINT>/v1/entities/<unit21_id>/link-verification-result \
-H 'Content-Type: application/json' \
-H 'u21-key: <YOUR_API_KEY>' \
-d '{
"verification_type": "ID_VERIFICATION",
"provider_name": "FAKE_PROVIDER",
"content": {"test": {"nested_field": 123}, "boolean_field": false, "error": "An error occurred"},
"verification_timestamp": 1600277454
}'
If the error parameter is provided as a top level field in the JSON value content, then special formatting may be displayed in the dashboard where applicable.
verification_type
is a string value and can be one of these values:
ID_VERIFICATION
DOC_VERIFICATION
BUSINESS_VERIFICATION
WATCHLIST_SCREENING
ADVERSE_MEDIA_SCREENING
CRYPTO_FORENSICS
If you provide a valid response body in the content field and a supported provider in the provider_name field, special formatting may be applied in our dashboard.
HTTP/1.1 200 OK
Content-Type: application/json
{
"verification_result_id": 42
}
Field | Type | Description | Required |
---|---|---|---|
verification_type | String | String, see above description for supported values. | Yes |
provider_name | String | String value, name of provider. | Yes |
content | Object | JSON value. Put response from verification provider here. | Yes |
verification_timestamp | Numeric | Assumed to be in UTC. Refers to the timestamp at which the verification was run. | No |
Verification Results (Full Response)
{
"created_at": 1591992745,
"entity_id": 856,
"source": "IDOLOGY",
"type": "DOC_VERIFICATION",
"verification_workflow_execution_id": 59,
"full_response": {...} // Dependent on the verification source/type
}
Here are the response fields:
Field | Type | Description |
---|---|---|
created_at | Numeric | The end result of the workflow, one of a set of end results defined by the workflow |
entity_id | Numeric | Unit21 ID of the entity that the verification was run on |
source | String | Provider executing the verification (IDOLOGY , TRULIOO , etc.) |
type | String | Type of verification executed (DOC_VERIFICATION , ID_VERIFICATION , etc.) |
verification_workflow_execution_id | Numeric | ID of the workflow execution |
full_response | Object | Full response from the verification provider running the verification |