Technical Reference

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.

FieldTypeDescription
workflow_idStringA unique identifier defined at workflow creation.
synchronous_responseBooleanWhether 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_responseBooleanInclude 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:

FieldTypeDescription
end_actionStringThe end result of the workflow, one of a set of end results defined by the workflow
is_successBooleanWhether or not the workflow successful completed. Workflows rely on external services, which may at times fail
resultsObjectObject mapping from the executed verification (e.g. IDOLOGY:DOC_VERIFICATION) to the result
full_responseObjectThe 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:

  1. Create an entity
  2. Link entity from step 1 with an externally created verification result using /link-verification-result endpoint.
  3. (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
}
FieldTypeDescriptionRequired
verification_typeStringString, see above description for supported values.Yes
provider_nameStringString value, name of provider.Yes
contentObjectJSON value. Put response from verification provider here.Yes
verification_timestampNumericAssumed 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:

FieldTypeDescription
created_atNumericThe end result of the workflow, one of a set of end results defined by the workflow
entity_idNumericUnit21 ID of the entity that the verification was run on
sourceStringProvider executing the verification (IDOLOGY, TRULIOO, etc.)
typeStringType of verification executed (DOC_VERIFICATION, ID_VERIFICATION, etc.)
verification_workflow_execution_idNumericID of the workflow execution
full_responseObjectFull response from the verification provider running the verification