Run a Document fetch check

Introduction

This developer guide takes you through the steps to run a Document fetch check in the Passfort API 4.0 to confirm whether an individual's proof of identity document is valid.

This check can be run on the Verify identity task (INDIVIDUAL_VERIFY_IDENTITY) or the Verify address task (INDIVIDUAL_VERIFY_ADDRESS).

If you'd like to use this check on the Verify address task, you should ensure that:

The documents provided contain proof of address as well as proof of identity, for example, a driver's license.
Your data provider extracts addresses from documents.

Warning

It's not possible to run a variant of this check with Onfido on the Verify address task because Onfido does not extract the individual’s address from the document. For more information about how Onfido handles this check, see Onfido's documentation. To learn which document types are supported, see the configuration article for your data provider.

With this check, you collect the document from the customer via the data provider's SDK or embedded webpage. If you'd like to upload the document directly to the profile, use the Document verification check instead.

Where possible, we recommend using the Document fetch check instead of Document verification because it also enables you to use any services the data provider is offering to check the quality of users' photos of documents. Contact your data provider to find out what services they offer.

In the portal, the name of the Document fetch check is ID verification (service collects documents).

What the process looks like

Most of the action you take for the Document fetch process happens in Passfort.

In Passfort, get the profile ID and run the check. The results are displayed in Passfort.

The only action you need to take with the data provider is to create the applicant.

This guide shows you how to perform these steps.

Implement your data provider's SDK or embedded webpage

For more information about implementing your data providers' services, see their guides:

For help getting TRUSTDOCK Identity Verification API guides, speak to your TRUSTDOCK account manager.

Get the profile's ID and confirm it has the required keys and values

You should choose a profile for the check and get the profile ID.

Once you have the profile ID, you can make sure it has the required fields for the check to run successfully.

Get the profile's ID

These 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 run the check later.

If you haven't created the profile yet, follow the steps to create a profile via the API. 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": "GBR",
                    "locality": "London",
                    "original_freeform_address": "Crown, 38, Street, London, W1 2ZT",
                    "original_structured_address": { … },
                    "postal_code": "W1 2ZT",
                    "route": "Street",
                    "street_number": "38",
                    "subpremise": "Crown"
                }
            }
        ],
        "contact_details": { },
        "personal_details": {
            "dob": "1975-04-19",
            "name": {
                "family_name": "Wheeler",
                "given_names": [
                    "Alex"
                ]
            },
            "national_identity_number": { },
            "nationality": "GBR"
        }
    },
    "collection_steps": [ ],
    "creation_date": "2019-10-03 13:48:16",
    "display_name": "Alex Wheeler",
    "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": "2019-10-03 13:48:16",
            "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": {
                "alias": "verify_identity",
                "id": "ddc72ea7-6e45-cc3b-dc52-30a94b9ec8c2",
                "name": "Verify identity",
                "task_type": "INDIVIDUAL_VERIFY_IDENTITY"
            }
        },
        {
            "check_ids": [ ],
            "creation_date": "2019-10-03 13:48:16",
            "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": {
                "alias": "verify_address",
                "id": "5562c4e4-4d12-b16a-a151-7c9eed6816e9",
                "name": "Verify address",
                "task_type": "INDIVIDUAL_VERIFY_ADDRESS"
            }
        }
    ],
    "unresolved_event_types": [ ]
}

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 corresponding task ID (tasks.id). Use the corresponding task alias (tasks.variant.alias) to confirm that 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 stored 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.
- personal_details.dob: The individual's date of birth. Note that this field is only required by Onfido and Jumio Netverify.
- address_history: An array of objects containing the individual's addresses. Note that this field is only required by TRUSTDOCK when you're running the check on the Verify address task and by Jumio Netverify (all tasks).

If the required fields don't exist or contain invalid data, running the check returns an error.

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

The reference is also a required field. We'll get it in the next section. To learn which optional profile fields can be used for this check and to learn about configuration options like the Check nationality option, see the article for your data provider: Onfido, Jumio Netverify, TRUSTDOCKAPI.

Get the data provider's reference ID for the document

When the data provider collects the customer's documents, they create a reference ID.

Jumio Netverify calls this a scanReference
Onfido calls this an applicant ID
TRUSTDOCK calls this an Identity Verification ID

You should get this ID so you can send it in the request to run the check later.

If you have a direct agreement with your data provider, you can improve the efficiency of the process by getting the data provider's reference ID at the same time as you create the profile in Passfort.

Jumio Netverify

For more information about getting the scanReference, see Jumio's documentation.

Onfido (direct agreement)

For more information about getting the applicant ID, see Onfido's documentation:

TRUSTDOCK Identity Verification API

For more information about getting the Identity Verification ID, speak to your TRUSTDOCK account manager.

Passfort only supports the following TRUSTDOCK plans.

Act on Prevention of Transfer of Criminal Proceeds (e) Plan
Personal Identity Verification Plan

Verifying two documents with a single TRUSTDOCK reference ID

It is possible to verify two documents with a single Identity Verification ID. This can be done when the reference to one document is in the records.document.id_document TRUSTDOCK field and the other is in records.document.individual_number_document TRUSTDOCK field.

When you get the check result from Passfort, it will contain:

All the images and text data present in the record.
The plan_id, plan_name, review_date, reviewer_id_1, and reviewer_id_2 associated with the submitted record, but not each document.
The document_type and extracted data for the TRUSTDOCK id_document. This information is not returned for the individual_number_document.

An integration error will be returned if there is not an id_document present in the record or if more than one record is returned.

Run the check and get the results

Now that you have the profile ID and the reference ID, you can run the check and get the results.

Run the check

Request endpoint:

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

By default, the check will run asynchronously. You can also send mode as a query parameter to run the check synchronously.

Note that if a response is not received from the data provider within 120 seconds, the mode will switch to asynchronous automatically, so you should always support asynchronous checks. Speak to your data provider to see if they guarantee a check response within 120 seconds.

Key	Value	Description
`check_type` *Required string	`DOCUMENT_FETCH`	The type of check that's being run.
`source` *Required string	`JUMIO`, `ONFIDO` , or `GENERIC` (used for TRUSTDOCK)	The data provider.
`reference` *Required string	Sample value: `6bba3592-d9de-1ee5-8e97-ba8d8d13c558`	The reference ID the data provider is using for the document.
`category` Optional, but we recommend including it whenever possible. string	`PROOF_OF_ADDRESS` or `PROOF_OF_IDENTITY` In the case of Onfido, you should always send the `category` as `PROOF_OF_IDENTITY` because they Onfido only supports identity documents.	The category of the document. You should send `PROOF_OF_ADDRESS` when the check is run on the Verify address task and `PROOF_OF_IDENTITY` when the check is run on the Verify identity task. When the category is `PROOF_OF_ADDRESS`, part of the pass criteria of the check is that the address extracted from the document must match the address in the profile. If you do not send this key, Passfort uses the `PROOF_OF_IDENTITY` category.
`task_ids` Optional string	Sample value: `72aadb55-8b02-8495-d6b0-e1627ec23612`	Array of strings where each string is a unique identifier for a task the check will run on. If you're using Onfido, you can run the check on the Verify identity task. If you're using Jumio Netverify, you can run the check on the Verify identity and/or the Verify address task. While this key is optional, we strongly recommend including it in your request. If you do not send this key, Passfort runs the check on the Verify identity task.
`variant` *Required object	For a sample value, see the following sample request body.	Object to indicate which variant of the check will 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 with Jumio Netverify as the data provider.

Sample request body:

{
    "check_type": "DOCUMENT_FETCH",
    "source": "JUMIO",
    "reference": "3d7b7010-d5ca-dab1-d7c0-01e4ada9b534",
    "category": "PROOF_OF_IDENTITY",
    "task_ids": [
        "72aadb55-8b02-8495-d6b0-e1627ec23612"
    ],
    "variant": {
        "alias": "default"
    }
}

Sample response:

{
    "check_type": "DOCUMENT_FETCH",
    "source": "JUMIO",
    "id": "a2c4393a-e219-67a4-5ab4-2186952e9038",
    "reference": "3d7b7010-d5ca-dab1-d7c0-01e4ada9b534",
    "category": "PROOF_OF_IDENTITY",
    "input_data": {
        "address_history": [ … ],
        "entity_type": "INDIVIDUAL",
        "personal_details": { ... },
        "nationality": "GBR"
    },
    "instructed_on": "2019-11-05 17:01:13",
    "performed_on": "2019-11-05 17:01:13",
    "started_on": "2019-11-05 17:01:13",
    "deadline": "2019-11-08",
    "providers": [ … ],
    "state": "RUNNING",
    "task_ids": [
        "3d7a333c-418d-72a1-007b-06854dbb28eb"
    ],
    "variant": { … }
}

Get the check result

Listen to the Check completed webhook to get a notification when the check is finished running and to learn what the result is.

This webhook sends a payload whenever results are returned from any check.

Payloads from this webhook have these important keys:

secret: Authenticate the request by ensuring this secret matches your secret.
id: The check ID. Use it to confirm the payload is for your check by matching it to the check ID you captured earlier.
check_type: The type of check that was run.
variant.alias: The alias for the check variant. You can use it for additional confirmation that the payload is for your check by matching it to the check variant alias you captured earlier.
result: The value for this key indicates the result of the check. To learn more about the results, see the configuration article for your data provider.

When the check results are returned from the data provider, Passfort cross-references the information from the individual’s collected_data with the information returned from the data provider to ensure it matches. This means it's possible for the data provider to pass the check and for Passfort to fail the check.

In this example, a Document fetch check run with Jumio Netverify passed.

Sample payload:

{
    "id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
    "event": "CHECK_COMPLETED",
    "secret": "yourSecret",
    "timestamp": 1573048450,
    "data": {
        "check": {
            "check_type": "DOCUMENT_FETCH",
            "id": "ea565b55-47d9-1858-4588-3a22a3838707",
            "result": "Pass",
            "variant": {
                "alias": "jumio_service_collects",
                "id": "ea70ade9-3de3-1785-203b-68044cd3ecbb",
                "name": "Jumio"
            }
        },
        "customer_ref": null,
        "profile_id": "a2c4393a-e219-67a4-5ab4-2186952e9038"
    }
}

Get more information about the check result

If you want to get more information about the results from the webhook, make a call to the following endpoint.

In the request body, include the check ID (check.id) and the profile ID (data.profile_id) from the webhook payload.

We recommend listening to the Check completed webhook to find out when the check is finished because it's more efficient than continuously polling the following endpoint.

Request endpoint:

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

In this example, the Document fetch check passed.

Sample response:

{
    "check_type": "DOCUMENT_FETCH",
    "completed_on": "2019-11-05 17:01:14",
    "decision": "PASS",
    "errors": [ ],
    "id": "edc23993-eb6a-9d89-bb79-5b8925b33224",
    "input_data": {
        "address_history": [
            {
                "address": {
                    "type": "STRUCTURED",
                    "country": "GBR",
                    "locality": "London",
                    "original_freeform_address": "Crown, 38, Street, London, W1 2ZT",
                    "original_structured_address": { ... },
                    "postal_code": "W1 2ZT",
                    "route": "Street",
                    "street_number": "38",
                    "subpremise": "Crown"
                }
            }
        ],
        "entity_type": "INDIVIDUAL",
        "personal_details": {
            "dob": "1975-04-19",
            "name": {
                "family_name": "Wheeler",
                "given_names": [
                    "Alex"
                ]
            },
            "nationality": "GBR"
        }
    },
    "instructed_on": "2019-11-05 17:01:13",
    "output_data": {
        "documents": [
            {
                "category": "PROOF_OF_IDENTITY",
                "document_type": "PASSPORT",
                "id": "bdb87a86-bd8d-6d83-b976-e114959a38d9",
                "extracted_data": {
                    "expiry": "2024-01-01",
                    "issuer": "Manual check",
                    "issuing_country": "GBR",
                    "mrz1": "P<GBRWHEELER<<ALEX<DARCY<<<<<<<<<<<<<<<<",
                    "mrz2": "0847623927GBR7504194M2401014<<<<<<<<<<<<<<08",
                    "number": "16CK123456",
                    "personal_details": { … }
                },
                "images": [
                    {
                        "id": "913c68e8-c246-463d-b59b-78c4444647b9",
                        "image_type": "FRONT",
                        "upload_date": "2019-11-06 13:54:05"
                    }
                ],
                "verification_result": {
                    "all_passed": true,
                    "document_type_passed": true,
                    "field_checks": [ … ],
                    "field_checks_passed": true,
                    "forgery_checks": [ … ],
                    "forgery_checks_passed": true,
                    "image_checks": [ … ],
                    "image_checks_passed": true,
                    "provider_name": "Jumio"
                }
            }
        ],
        "entity_type": "INDIVIDUAL"
    },
    "performed_on": "2019-11-05 17:01:13",
    "providers": [
        {
            "instructed_on": "2019-11-06 13:54:05",
            "provider_name": "Jumio Netverify",
            "variant_name": ""
        }
    ],
    "reference": "3d7b7010-d5ca-dab1-d7c0-01e4ada9b534",
    "result": "Pass",
    "source": "JUMIO",
    "started_on": "2019-11-05 17:01:13",
    "state": "COMPLETE",
    "task_ids": [ ],
    "variant": {
        "alias": "jumio_service_collects",
        "id": "5562c4e4-4d12-b16a-a151-7c9eed6816e9",
        "name": "Jumio"
    }
}

The output_data.documents.verification_result object that's returned in the response contains some key information about the check result:

all_passed: When all the data provider's checks have passed, the value of this field is true. When one or more checks have failed, the value of this field is false.
document_type_passed: When the correct document_type was used, the value of this field is true. If an incorrect document_type was used, the value of this field is false.
error_reason: This field contains a description about why the check returned an error.
field_checks: This array of objects contains one object for every profile field that was cross-referenced with the information extracted from the data provider.
forgery_checks: This array of objects contains one object for every forgery check performed by the data provider, along with a detailed result for each one.
forgery_checks_passed: When all forgery checks performed by the data provider passed, the value of this is true. When one or more forgery checks failed, the value of this field is false.
image_checks: This array of objects contains one object for every image check performed by the data provider, along with a detailed result for each one.
image_checks_passed: When all image checks performed by the data provider passed, the value of this field is true. When one or more image checks failed, the value of this field is false.
provider_name: The name of the data provider.

For a description of every field that might be returned in the response, see the API Resources for Get results of a specific check.

Onfido mapping

If you're using Onfido, the documents.document_type field maps as follows:

Onfido document type	Passfort `document_type`
`driving_licence`, `regular_driving_licence`, `learning_driving_licence`	`DRIVING_LICENSE`
`passport`	`PASSPORT`
`passport_card`	`PASSPORT_CARD`
`national_identity_card`	`STATE_ID`
`voter_id`	`VOTER_ID`
`national_health_insurance_card`	`HEALTHCARE_ID`
`tax_id`	`TAX_ID`
`residence_permit`	`BIOMETRIC_STATE_ID`
`visa`	`VISARD`

If you're using version 1 or 2 of the Onfido API and the document type is unknown, the check fails. If you're using version 3 of the Onfido API, the document type will be classified as miscellaneous if Passfort cannot recognize the document and unknown if Onfido cannot recognize the document.

TRUSTDOCK Identity Verification API mapping

If you have a login, you can learn more about the TRUSTDOCK fields in their API documentation.

If you're using the TRUSTDOCK Identity Verification API, the documents.document_type field maps as follows:

TRUSTDOCK document type	Passfort `document_type`
`passport`	`PASSPORT`
`health_insurance_card`	`HEALTHCARE_ID`
`drivers_license`	`DRIVING_LICENSE`
`driving_history_certificate`	`MISCELLANEOUS`
`individual_number_card`	`STATE_ID`
`residence_card`	`RESIDENCE_ID`
`basic_resident_registration_card`	`RESIDENCE_OTHER`
`special_permanent_resident_certificate`	`RESIDENCE_OTHER`

If you're using the TRUSTDOCK Identity Verification API, the documents.verification_result.provider_information array maps as follows:

TRUSTDOCK name	Passfort `provider_information`
`verified_by`	`reviewer_id_1`
`verified_by`	`reviewer_id_2`
`plan.id`	`plan_id`
`plan.name`	`plan_name`
`individual_number`	`mynumber_redacted` (shows only the last 2 digits and is displayed in the portal) `mynumber` (shows the full, unredacted number and is not displayed in the portal)

If you're using the TRUSTDOCK Identity Verification API the documents.verification_result.review_date field maps to the verified_at field in TRUSTDOCK.

If you're using the TRUSTDOCK Identity Verification API, the documents.verification_result.forgery_checks object maps as follows:

TRUSTDOCK `reason code`	Passfort `forgery_checks.category`	Passfort `forgery_checks.type`
`address_is_not_specified`	Security checks	Address specified
`contains_individual_number`	Document validation	Does not contain MyNumber
`expired`	Document validation	Document has not expired
`mismatched_data`	Document validation	Input data matching
`missing_address`	Document validation	Address present
`missing_issuer`	Document validation	Document issuer present
`other`	Security checks	Other
`wrong_document`	Document validation	Document is supported

If you're using the TRUSTDOCK Identity Verification API, the documents.verification_result.image_checks object maps as follows:

TRUSTDOCK `reason code`	Passfort `image_checks.category`	Passfort `image_checks.type`
`blurred`	Image quality	Image integrity: blurred
`copy_or_scanned_data`	Security checks	Visual authenticity: original document present
`failed_randomness_check`	Security checks	Liveness overall result
`mismatched_face`	Security checks	Face matching
`missing_thickness`	Image quality	Image integrity: thickness
`no_face`	Security checks	Visual authenticity: face detection
`not_human`	Security checks	Liveness: actions performed by a human
`out_of_frame`	Image quality	Image integrity: document capture
`partly_hidden`	Image quality	Image integrity: document fully visible

Now that you have the results of the check, you may want to mark the task as complete.

In this section:

Using Passfort