Verification 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.

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
      }'
curl -X POST \
  https://<API_ENDPOINT>/v1/entities/create \
  -H 'Content-Type: application/json' \
  -H 'u21-key: <YOUR_API_KEY>' \
  -d '{
    ...
    "options": {
      "identity_verifications": {
        "workflow_id": "sanctions_check_1",
        "run_verifications": true,
        "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:

  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
}

List of supported providers:

  • 'AU10TIX'
  • 'TRULIOO'
  • 'CSI'
  • 'DOW_JONES'
  • 'IDOLOGY'
  • 'EMAILAGE'
  • 'MIDDESK'
  • 'SOCURE'

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

Please see this section for more.


Did this page help you?