Run a Document fetch check (API)

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:

  1. The documents provided contain proof of address as well as proof of identity (e.g. a driver's license).
  2. Your data provider extracts addresses from documents.
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.
PassFort supports these document types when Onfido is the data provider: Passports, driving licenses, state IDs, voter IDs, and biometric residence permits. There are no document type restrictions in PassFort when Jumio Netverify is the 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.

Before you begin

Implement your data provider's SDK or embedded webpage

This guide assumes you've already implemented your data provider's SDK or embedded webpage so your customer can send their identity documents.

You can use Jumio Netverify or Onfido as your data provider. For more information about implementing their services, see their guides:

If you're using PassFort as a reseller for Onfido checks, confirm your configuration is correct

When you're using PassFort as a reseller, use the Policy Builder to confirm the check variant and task variant have the right configuration options.

To change your configuration options, contact us.

To see the Policy Builder, you need to have Read only access for the Smart policies permission.
If you have a direct agreement with your data provider, you don't need to perform these steps.

Confirm the check variant is a default check:

  1. Go to the Policy Builder > Check configuration.
  2. Click ID verification (service collects documents) check.
  3. Confirm Is default check is selected.

Confirm the task variant is a default task that has the check as an acceptance check:

  1. Go to the Policy Builder > Tasks.
  2. Click the Verify address or Verify identity task.
  3. Confirm Is default task is selected.
  4. Confirm the ID verification (service collects documents) check is listed as an Acceptance check.

1. 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 (more information below).

Once you have the profile ID, you can make sure it has the required fields (documented below) for the Document fetch check to run successfully.

Get the profile's ID

Document fetch 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 (e.g. 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 an individual 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 /onboarding/ 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:

  1. 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.
  2. 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. 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.
  3. Confirm the profile has data for these required keys, which are stored in the collected_data object:
    1. personal_details.name.given_names: The individual's first and (if applicable) middle names.
    2. personal_details.name.family_name: The individual's surname.
    3. personal_details.dob: The individual's date of birth.
    4. address_history: An array of objects containing the individual's addresses. Note that this field is only required by Jumio Netverify.

If the required fields do not exist on the profile or do not contain valid data, the check will return an error when you try to run it in step 3.

To learn how to add/update the fields in 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 step.
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.

2. 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 and Onfido calls this an applicant ID.

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

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:

Onfido (checks resold by PassFort)

If you're using PassFort as a reseller, make a single call to the endpoint below to create an applicant and generate an Onfido SDK token.

The Onfido token expires after 90 minutes, so you must run the Document fetch check within that time. If your token has expired, make another request to the endpoint below and run the Document fetch check again.
The Onfido SDK token is a JWT token.

Request endpoint:

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

Body parameters:

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

Key

Value

Description

token_type

Required

String

DOCFETCH

The type of token request.

referrer

Required for web SDK

String

Sample: http://localhost:3000/*

The URL of the webpage where the Onfido web SDK will be used.

application_id

Required for the iOS or Android SDK

String

Sample: ABCDE12345.com.your-company.example

Your Android or iOS application ID.

You should not send a referrer and application_id in the same request.

In this example, we'll send the request for the web SDK.

Sample request body:

{
"token_type": "DOCFETCH",
"referrer": "http://localhost:3000/*"
}

Sample response:

{
"onfido_applicant_id": "3d7b7010-d5ca-dab1-d7c0-01e4ada9b534",
"sdk_jwt": "0TUmKi8NZVCLFqXpRDCF.yPN04BFBA2mbSeKhAl8dUzF10FjPsu1Cn9ESJrkMSjubjIz7nOeGV2JG8LycDowsEMPkE5",
"token_type": "DOCFETCH"
}

Use the response to:

  • Take note of the applicant id (onfido_applicant_id). You'll need to send it as the reference when you run the check.

3. Run the check

Now that you have the profile ID and 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

Body parameters:

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

Key

Value

Description

check_type

Required

String

DOCUMENT_FETCH

The type of check that's being run.

source

Required

String

JUMIO or ONFIDO

The name of the data provider.

reference

Required

String

Sample value: 6bba3592-d9de-1ee5-8e97-ba8d8d13c558

The reference ID the data provider is using for the document.

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.

In the example below, 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",
"task_ids": [
"72aadb55-8b02-8495-d6b0-e1627ec23612"
]
}

Sample response:

{
"check_type": "DOCUMENT_FETCH",
"source": "JUMIO",
"id": "a2c4393a-e219-67a4-5ab4-2186952e9038",
"reference": "3d7b7010-d5ca-dab1-d7c0-01e4ada9b534",
"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": { … }
}

This check often takes a bit of time to run, so the check state will likely be RUNNING in the response because the response is returned immediately. See the next step to learn how to get the check result as soon as it comes back from the data provider.

Get the check result

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

To enable this webhook, turn on the Check completed event.

This webhook sends a callback whenever results are returned from any check (including checks other than the Document fetch check).

Callbacks 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 callback is for your check by matching it to the check ID you captured in step 1.
  • check_type: The type of check that was run. When the Document fetch check was run, the value is DOCUMENT_CHECK.
  • variant.alias: The alias for the check variant. You can use it for additional confirmation that the callback is for your check by matching it to the check variant alias you captured in step 1.
  • result: The value for this key indicates the result of the check. Possible results for the Document fetch check are Pass, Fail, or Error. To learn what triggers each result, see the configuration article for your data provider: Jumio Netverify, Onfido.
When the check results are returned from the data provider, PassFort cross-references the information from 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 callback:

{
"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"
}
}

Use the response to:

Confirm the check has passed:

  • If the check has passed, data.check.result is Pass.
  • If the check hasn't passed, data.check.result is Fail.
  • If an error occurred, data.check.result is Error.

See Getting more information about the check result to learn what forgery or image checks the data provider performed, what information the data provider extracted from the document, any error or failure details, and more.

Getting more information about the check result

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

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

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 endpoint below.

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 image, forgery, and field 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.

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


How did we do?


Powered by HelpDocs