Run an Identity check using the API

This topic takes you through the steps to run an Electronic identity check in the Passfort API 4.0 to verify an individual's address by establishing a digital paper trail.

This check can be run on the following tasks:

Verify address (INDIVIDUAL_VERIFY_ADDRESS)
Verify identity (INDIVIDUAL_VERIFY_IDENTITY)

Choose a profile and get the profile ID

Identity checks are always run on profiles with the INDIVIDUAL entity type.

Choose an individual profile to run the check on, and take note of the profile's ID number, for example, a2c4393a-e219-67a4-5ab4-2186952e9038). You'll need it to confirm it has the required fields and also to run the check later.

If you haven't created the profile yet, follow the steps to create a profile using the API. If you have access to the full Passfort product, you can also create a profile via the portal. To get the profile ID, view the profile in the portal and copy the string of letters and numbers after /profiles/ in the URL.

Confirm the profile has the required fields for the check

To see all data on the profile, make a request to the following endpoint.

Request endpoint:

GET https://api.passfort.com/4.0/profiles/{profile_id}

In this example, data is returned for an individual profile named "Alex Wheeler." The profile has the Verify identity and Verify address tasks.

Sample response:

{
    "applications": [ ... ],
    "category": "APPLICANT",
    "checks": [ ],
    "collected_data": {
        "entity_type": "INDIVIDUAL",
        "address_history": [
            {
                "address": {
                    "type": "STRUCTURED",
                    "country": "USA",
                    "county": "",
                    "locality": "San Diego",
                    "original_freeform_address": ", , 596, Balboa Road, San Diego, , , CA, 92123",
                    "original_structured_address": { ... },
                    "postal_code": "92123",
                    "postal_town": "",
                    "premise": "",
                    "route": "Balboa Road",
                    "state_province": "CA",
                    "street_number": "596",
                    "subpremise": ""
                }
            }
        ],
        "contact_details": { },
        "personal_details": {
            "dob": "1999-01-23",
            "name": {
                "family_name": "Floren",
                "given_names": [
                    "Sam"
                ]
            },
            "national_identity_number": {
                "USA": "000-49-697"
            }
        }
    },
    "collection_steps": [ ],
    "creation_date": "2020-01-21 12:50:07",
    "display_name": "Sam Floren",
    "document_images": [ ],
    "events": [ ],
    "has_associates": false,
    "has_collection_steps": false,
    "id": "a2c4393a-e219-67a4-5ab4-2186952e9038",
    "linked_to": [ ],
    "role": "INDIVIDUAL_CUSTOMER",
    "root_id": "6bba3592-d9de-1ee5-8e97-ba8d8d13c558",
    "status": "NORMAL",
    "tags": [ ],
    "task_progress": {...},
    "task_types": [
        "INDIVIDUAL_VERIFY_IDENTITY",
        "INDIVIDUAL_VERIFY_ADDRESS"
    ],
    "tasks": [
        {
            "check_ids": [ ],
            "creation_date": "2020-01-17 12:50:07",
            "form_instance_ids": [ ],
            "id": "3d7a333c-418d-72a1-007b-06854dbb28eb",
            "is_complete": false,
            "is_expired": false,
            "is_skipped": false,
            "state": "INCOMPLETE",
            "type": "INDIVIDUAL_VERIFY_IDENTITY",
            "variant": {
                "id": "133608c0-3c7b-11ea-aa81-3e1b2992e5d6",
                "alias": "verify_identity_individuals",
                "task_type": "INDIVIDUAL_VERIFY_IDENTITY"
            }
        },
        {
            "check_ids": [ ],
            "creation_date": "2020-01-17 12:50:07",
            "form_instance_ids": [ ],
            "id": "72aadb55-8b02-8495-d6b0-e1627ec23612",
            "is_complete": false,
            "is_expired": false,
            "is_skipped": false,
            "state": "INCOMPLETE",
            "type": "INDIVIDUAL_VERIFY_ADDRESS",
            "variant": {
                "id": "5562c4e4-4d12-b16a-a151-7c9eed6816e9",
                "alias": "verify_address_individuals",
                "task_type": "INDIVIDUAL_VERIFY_ADDRESS"
            }
        }
    ]
}

Use the response to:

Confirm the profile has the type of task you want to run the check on. To run this check on the Verify address task, the profile must have a task with the INDIVIDUAL_VERIFY_ADDRESS type. To run this check on the Verify identity task, the profile must have a task with the INDIVIDUAL_VERIFY_IDENTITY type.
Take note of the task ID, or tasks.id. Use the corresponding task alias (tasks.variant.alias) to confirm you're looking at the right task. If there is more than one task with the same alias, which happens when a task has more than one version, use the task with "is_expired": "false". Note that the task variant ID (tasks.variant.id) won't be used to run this check, so you don't need to take note of it.
Confirm the profile has data for these required keys, which are in the collected_data object:
- personal_details.name.given_names: The individual's first and, if applicable, middle names.
- personal_details.name.family_name: The individual's surname.
- address_history: An array of objects containing the individual's addresses. Note that the country of address must be covered by your data provider. See the article for your data provider for more details.
- personal_details.dob: The individual's phone number. Note that this is not a required field for Equifax UK IC SaaS. If you're using LexisNexis InstantID as the data provider, you only have to provide the date of birth or the national identity number, so this field is optional when you've provided the individual's social security number, and you're not using the DOB is one of the required fields configuration option.
- personal_details.national_identity_number: The individual's national identity number. This is only a required field if:
  - You're using the Identity number is one of the required fields configuration option, available for GBG ID3global and LexisNexis InstantID.
  - You're using LexisNexis InstantID as the data provider and you haven't provided a date of birth. Note that if you're using LexisNexis InstantID, the national identity number must be an American social security number.

If the required fields don't exist on the profile or don't contain valid data, the check returns an error when you try to run it.

To learn how to add/update the fields in the profile's collected_data, see Update Passfort's profile data.

To learn which optional profile fields and configuration options can be used for this check, see the article for your data provider: Equifax Australia IDMatrix, Equifax Canada AML Assist, Equifax UK IC SaaS, GBG ID3global, Global Data Consortium Worldview, LexisNexis, Onfido v3.Configuring Equifax Canada AML Assist

Run the check

To run the check, send a request to the following endpoint. By default, the Identity check runs synchronously.

Request endpoint:

POST https://api.passfort.com/4.0/profiles/{profile_id}/checks

By default, the Identity check runs synchronously.

You can also send mode as a query parameter to run the check asynchronously.

Body parameters:

When you make the POST request, include the following parameters in the body.

Key	Value	Description
`check_type` Required String*	`IDENTITY_CHECK`	The type of check that's being run.
`task_ids` Optional, but we recommend including it whenever possible. string	Sample value: `3d7a333c-418d-72a1-007b-06854dbb28eb`	The unique identifier for the task(s) the check will run on, in other words `INDIVIDUAL_VERIFY_IDENTITY` task or the `INDIVIDUAL_VERIFY_ADDRESS` task. If you don't provide a `task_ids`, the check will run on whichever task the profile has. If the profile has both tasks, the check will run on both.
`variant` *Required object	For a sample value, see the following sample request body.	Object to indicate which variant of the check is run.
`variant.alias` *Required string This key is optional if `variant.id` is provided, but we recommend sending the alias whenever possible.	Sample value: `default`	The check alias.
`variant.id` *Required string This key is optional if `variant.alias` is provided.	Sample value: `ea70ade9-3de3-1785-203b-68044cd3ecbb`	The unique identifier for the check.

In the following example, we'll run the check on the Verify identity task, using GBG ID3global as the data provider.

The sample response shows:

The check has passed; the decision is PASS.
An overall result of 2+2 was achieved; the result is 2+2.
This 2+2 result was achieved because the rule for Matches name and address, plus name and DOB was met; for this rule, active is true.
This rule was met because the individual's forename, surname, and address were matched in the UK Landline (Append) database and the individual's forename, surname, and date of birth were matched in the UK Credit Header (AML) database. The individual's address was also matched in the UK Credit Header (AML), though it wasn't required for the rule. We can see all this by looking at the satisfied_by array of objects for the rule.
The individual was matched in the Electoral Register in addition to the UK Landline (Append) and UK Credit Header (AML). No matches were found in the UK National Identity Register. We can see this in the matches array of objects.

A detailed explanation of these fields is described after the sample response.

Sample request body:

{
   "check_type": "IDENTITY_CHECK",
   "task_ids": [
      "3d7a333c-418d-72a1-007b-06854dbb28eb"
   ],
    "variant": {
        "alias": "default"
    }
}

Sample response:

{
   "check_type": "IDENTITY_CHECK",
   "completed_on": "2020-01-21 14:33:23",
   "decision": "PASS",
   "errors": [ ],
   "id": "ea565b55-47d9-1858-4588-3a22a3838707",
   "input_data": {
      "address_history": [ ... ],
      "contact_details": { },
      "entity_type": "INDIVIDUAL",
      "personal_details": { ... }
   },
   "instructed_on": "2020-01-21 14:33:23",
   "output_data": {
      "address_history": [ … ],
      "electronic_id_check": {
         "matches": [
            {
               "count": 1,
               "database_name": "UK Landline (Append)",
               "database_type": "CIVIL",
               "matched_fields": [
                  "ADDRESS",
                  "FORENAME",
                  "SURNAME"
               ]
            },
            {
               "count": 0,
               "database_name": "UK National Identity Register",
               "database_type": "CIVIL",
               "matched_fields": [ ]
            },
            {
               "count": 1,
               "database_name": "Electoral Register",
               "database_type": "CIVIL",
               "matched_fields": [
                  "ADDRESS",
                  "FORENAME",
                  "SURNAME"
               ]
            },
            {
               "count": 1,
               "database_name": "UK Credit Header (AML)",
               "database_type": "CREDIT",
               "matched_fields": [
                  "ADDRESS",
                  "DOB",
                  "FORENAME",
                  "SURNAME"
               ]
            }
         ],
         "rules": [
            {
               "active": true,
               "database_types": [ ... ],
               "distinct_sources": true,
               "name": "Matches name and address, plus name and DOB",
               "requires": [ ... ],
               "result": "2+2",
               "satisfied_by": [
                  {
                     "count": 1,
                     "database_name": "UK Landline (Append)",
                     "matched_fields": [
                        "ADDRESS",
                        "FORENAME",
                        "SURNAME"
                     ],
                     "required_fields": [
                        "ADDRESS",
                        "FORENAME",
                        "SURNAME"
                     ]
                  },
                  {
                     "count": 1,
                     "database_name": "UK Credit Header (AML)",
                     "matched_fields": [
                        "ADDRESS",
                        "DOB",
                        "FORENAME",
                        "SURNAME"
                     ],
                     "required_fields": [
                        "DOB",
                        "FORENAME",
                        "SURNAME"
                     ]
                  }
               ]
            },
            {
               "active": false,
               "database_types": [ ... ],
               "distinct_sources": true,
               "name": "Matches name and address from two sources",
               "requires": [ ... ],
               "result": "2+2",
               "satisfied_by": [ ... ]
            },
            {
               "active": false,
               "database_types": [ ... ],
               "distinct_sources": true,
               "name": "Matches name and address",
               "requires": [ ... ],
               "result": "1+1",
               "satisfied_by": [ … ]
            },
            {
               "active": false,
               "database_types": [ … ],
               "distinct_sources": true,
               "name": "Matches name and address",
               "requires": [ ... ],
               "result": "1+1",
               "satisfied_by": [ ... ]
            }
         ]
      },
      "entity_type": "INDIVIDUAL"
   },
   "performed_on": "2020-01-21 14:33:23",
   "providers": [
      {
         "instructed_on": "2020-01-21 14:33:23",
         "provider_name": "GBG ID3global",
         "variant_name": "gbg_id3global"
       }
   ],
   "result": "2+2",
   "started_on": "2020-01-20 14:33:23",
   "state": "COMPLETE",
   "task_ids": [
      "3d7a333c-418d-72a1-007b-06854dbb28eb"
   ],
   "variant": { ... }
}

Use the response to:

Confirm whether the check has passed:

If the check has passed, the decision is PASS.
If the check has returned a partial match, meaning that some matches were found but not enough for the check to pass, the decision is PARTIAL.
If the check hasn't passed or returned a partial match, the decision is FAIL.
If an error occurred, the decision is ERROR.

The check passes, returns a partial match, or fails depending on the data provider and configuration options you're using. To learn more, see the article for your data provider: Equifax Australia IDMatrix, Equifax Canada AML Assist, Equifax UK IC SaaS, GBG ID3global, Global Data Consortium Worldview, LexisNexis, Onfido v3.Configuring Equifax Canada AML Assist

If the overall result is 2+2, the result is 2+2.
If the overall result is 1+1, the result is 1+1.
If the check failed, the result is Fail.
If the check returned an error, the result is Error.

In most cases, a 2+2 overall result means the individual was matched in 2 of the data provider's sources, and a 1+1 overall result means the individual was matched in 1 of the data provider's sources. LexisNexis is the exception to this, where the number of sources is not considered when determining 1+1 or 2+2 results. For more information, see Configuring LexisNexis InstantID. Note that 1+1 and 2+2 results are not used for Equifax UK IC SaaS.

The output_data object shows which rules were used to determine the overall result and lists all the matches for the individual that the data provider was able to find:

electronic_id_check.rules: This array of objects has one object for every possible rule that could be used to determine the overall result.
These rules depend on the data provider you're using and the configuration options you're using. For example, GBG ID3global has a configuration option to confirm whether the individual is located on any mortality lists, then fail the check if they are. When this configuration option is used, a rule called Matches name and DOB on mortality list is present as an object in the rules array. If the configuration option is deselected, this rule is not present as an object in the rules array.
Each object in the rules array has a few key fields:
- name: This is the human-readable name of the rule.
- active: This is true when the rule was used for the overall result. It's false when the rule was not. Only one rule is used for the overall result. If the requirements for multiple rules are met, the first matching rule is used as the active rule.
- result: This is what the check's overall result will be if this is the active rule.
- requires: This is what needs to be matched for the rule to be met.
- satisfied_by: If the rule is met, this lists the database and matching profile information used to meet the rule. If the rule is not met, this field is not returned. Note that even if a rule is met, it may not be the active rule since only one active rule is returned.
electronic_id_check.matches: This array of objects has one object for every data provider source that had a match for the individual. Each object in the matches array has a few key fields:
- database_name: The name of the source.
- database_type: The type of source. Can be: CIVIL, CREDIT, MORTALITY, or IGNORED.
- matched_fields: The profile fields that were matched in the source.
If the check was unable to return matches for any database, the array is empty.

Note that some data providers do not return details about database sources. With LexisNexis InstantID, for example, electronic_id_check.matches only has one object named LexisNexis DB when the individual has matches, and the array is empty if there are no matches.

You can use the configuration options for your data provider to specify which of the individual's details, for example, date of birth or nationality, need to be found in one of the data provider's sources for it to contribute to the match. For more information, see the configuration article for your data provider.

To get a list of every field that may be included in the response, see run a check in the developer resources.

Additional information

In this section:

Run an Identity check using the API

Choose a profile and get the profile ID

Confirm the profile has the required fields for the check

Run the check

Additional information

Search results