Run a Company document verification check

This developer guide takes you through the steps to run a Company document verification check in the Passfort API 4.0 to confirm whether a company's document is valid.

This check can be run on these tasks:

Verify bank account COMPANY_VERIFY_BANK_ACCOUNT
Verify company address COMPANY_VERIFY_ADDRESS
Verify company details COMPANY_VERIFY_IDENTITY
Verify tax status COMPANY_VERIFY_TAX_STATUS

Select a profile for the check

Company document verification checks are always run on profiles with the COMPANY entity type.

Choose a company profile to run the check on, and get the profile's ID number, for example, a2c4393a-e219-67a4-5ab4-2186952e9038. You'll need it to make the request in the next step.

If you haven't created the company's profile yet, follow the steps to create a profile via the API. 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

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 a company profile named "Aerial Traders." The profile has the Verify bank account, Verify company address, Verify company details, and Verify tax status tasks.

Sample response:

{
   "applications": [ ... ],
   "category": "APPLICANT",
   "checks": [ ... ],
   "collected_data": {
      "entity_type": "COMPANY",
      "metadata": {
         "addresses": [
            {
               "address": {
                  "type": "STRUCTURED",
                  "country": "GBR",
                  "locality": "London",
                  "original_freeform_address": "38, Crown Street, London, W1 2ZT",
                  "original_structured_address": { ... },
                  "postal_code": "W1 2ZT",
                  "route": "Crown Street",
                  "street_number": "38"
               }
            }
         ],
         "country_of_incorporation": "GBR",
         "name": "AERIAL TRADERS",
         "number": "012345678",
         "tax_ids": [
            {
                "tax_id_type": "EUROVAT",
                "value": "GB462793578"
            }
        ]
      }
    },
    "collection_steps": [ ],
    "creation_date": "2019-10-03 13:48:16",
    "display_name": "AERIAL TRADERS",
    "document_images": [ ],
    "events": [ ],
    "has_associates": false,
    "has_collection_steps": false,
    "id": "a2c4393a-e219-67a4-5ab4-2186952e9038",
    "linked_to": [ ],
    "role": "COMPANY_CUSTOMER",
    "root_id": "6bba3592-d9de-1ee5-8e97-ba8d8d13c558",
    "status": "NORMAL",
    "tags": [ ],
    "task_progress": { ... },
    "task_types": [
        "COMPANY_VERIFY_IDENTITY",
        "COMPANY_VERIFY_TAX_STATUS",
        "COMPANY_VERIFY_BANK_ACCOUNT"
    ],
    "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": "COMPANY_VERIFY_IDENTITY",
            "variant": {
                "alias": "verify_identity",
                "id": "dc72ea7-6e45-cc3b-dc52-30a94b9ec8c2",
                "task_type": "COMPANY_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": "COMPANY_VERIFY_TAX_STATUS",
            "variant": {
                "alias": "verify_tax_status",
                "id": "5562c4e4-4d12-b16a-a151-7c9eed6816e9",
                "task_type": "COMPANY_VERIFY_TAX_STATUS"
            }
        },
        {
            "check_ids": [ ],
            "creation_date": "2019-10-03 13:48:16",
            "form_instance_ids": [ ],
            "id": "a2380e94-47ee-3337-fe2d-9fad0692106f",
            "is_complete": false,
            "is_expired": false,
            "is_skipped": false,
            "state": "INCOMPLETE",
            "type": "COMPANY_VERIFY_BANK_ACCOUNT",
            "variant": {
                "alias": "verify_bank_account",
                "id": "e5afcd76-5cfd-51d2-97d1-2d812e1df411",
                "task_type": "COMPANY_VERIFY_BANK_ACCOUNT"
            }
        },
        {
            "check_ids": [ ],
            "creation_date": "2019-10-03 13:48:16",
            "form_instance_ids": [ ],
            "id": "a51e03c2-c750-92d3-d6ce-bcb880bcaab0",
            "is_complete": false,
            "is_expired": false,
            "is_skipped": false,
            "state": "INCOMPLETE",
            "type": "COMPANY_VERIFY_ADDRESS",
            "variant": {
                "alias": "verify_bank_account",
                "id": "a481458c-cba5-44a2-e779-a5e5cbd6c6c7",
                "task_type": "COMPANY_VERIFY_BANK_ACCOUNT"
            }
        }
    ],
    "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 bank account task, the profile must have a task with the COMPANY_VERIFY_BANK_ACCOUNT type. To run this check on the Verify company address task, the profile must have a task with the COMPANY_VERIFY_ADDRESS type. To run this check on the Verify company details task, the profile must have a task with the COMPANY_VERIFY_IDENTITY type. To run this check on the Verify tax status task, the profile must have a task with the COMPANY_VERIFY_TAX_STATUS 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:
- metadata.name: The legal name of the company.
- metadata.country_of_incorporation: The country in which the company is incorporated.
- metadata.addresses: An array of objects where each object corresponds to one of the company's addresses.
- metadata.tax_ids: An array of objects where each object corresponds to one of the company's tax IDs. Note that this is only required if you're using the check to verify the company's tax status.

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

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

The document_id is also a required field. We'll create it in the next section. To learn which optional profile fields can be used for this check, see the article for Configuring idvcheck.

Create the document object

Follow these steps to add a document to the profile, using these specifications:

When you make the request to add the document_images, ensure the image_type is FRONT. This is because documents for the Company document check only have a front.
When you make the request to create the document object, send the category and document_type in the request body as follows.

Key

Value

category

*Required

string

On the Verify company address task: PROOF_OF_ADDRESS

On the Verify company details task: PROOF_OF_IDENTITY

On the Verify bank account task: PROOF_OF_BANK_ACCOUNT

On the Verify tax status task: PROOF_OF_TAX_STATUS

document_type

*Required

string

When the category is PROOF_OF_ADDRESS: UTILITY_BILL or TAX

When the category is PROOF_OF_IDENTITY: INCORPORATION

When the category is PROOF_OF_BANK_ACCOUNT: BANK_STATEMENT

When the category is PROOF_OF_TAX_STATUS: TAX

Run the check

Now that you have the document object, you can run the check and get the results.

Run the check

To run the check, send a request to the following endpoint.

In the request body, include the document ID, returned when you created the document object, and the task ID, returned when you got all data from the profile.

Tip

Forgot to take note of the document ID or the task ID?

Send a request to get all data from the profile. The document ID is returned in collected_data.documents.id and the task ID is returned in tasks.id.

Request endpoint:

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

By default, the Company document verification 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.

Body parameters:

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

Key	Value	Description
`check_type` *Required string	`COMPANY_DOCUMENT_VERIFICATION`	The type of check that's being run.
`document_id` *Required string	Sample value: `9a92b3c5-e804-06bc-cccc-6b3b43ea2a7a`	The unique identifier for the document in the profile's documents.
`task_ids` Optional, but we recommend including it whenever possible Array of strings	For the Verify company details task: `COMPANY_VERIFY_IDENTITY` For the Verify bank account task:`COMPANY_VERIFY_BANK_ACCOUNT` For the Verify tax status task: `COMPANY_VERIFY_TAX_STATUS` If you do not send a value for this key, the check is run on the Verify company details task when the document `category` is `COMPANY_VERIFY_IDENTITY`, run on the Verify bank account task when the `category` is `COMPANY_VERIFY_BANK_ACCOUNT`, and run on the Verify tax status task when the document `category` is `COMPANY_VERIFY_TAX_STATUS`.	The unique identifier for the tasks the check will run on.
`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 this example, we'll run the check on the Verify bank account task, sending the document we created earlier.

Sample request body:

{
    "check_type": "COMPANY_DOCUMENT_VERIFICATION",
    "document_id": "9a92b3c5-e804-06bc-cccc-6b3b43ea2a7a",
    "task_ids": [
        "3d7a333c-418d-72a1-007b-06854dbb28eb"
    ],
    "variant": {
        "alias": "default"
    }
}

Sample response:

{
    "check_type": "COMPANY_DOCUMENT_VERIFICATION",
    "deadline": "2019-10-14 14:37:46",
    "document_id": "9a92b3c5-e804-06bc-cccc-6b3b43ea2a7a",
    "id": "ea565b55-47d9-1858-4588-3a22a3838707",
    "input_data": {
        "documents": [
            {
                "category": "PROOF_OF_BANK_STATEMENT",
                "document_type": "BANK_STATEMENT",
                "id": "9a92b3c5-e804-06bc-cccc-6b3b43ea2a7a",
                "images": [
                    {
                        "id": "ec1565b6-82c7-0577-8b3a-94462b67c97a",
                        "image_type": "FRONT",
                        "upload_date": "2019-10-03 14:05:19"
                    }
                ]
            }
        ],
        "entity_type": "COMPANY",
        "metadata": { … },
    },
    "instructed_on": "2019-10-03 14:26:44",
    "performed_on": "2019-10-03 14:26:48",
    "providers": [ … ],
    "started_on": "2019-10-03 14:26:44",
    "state": "RUNNING",
    "task_ids": [ … ],
    "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 results as soon as they come in 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.

This webhook sends a payload whenever results are returned from any check, including checks other than the Company document verification check.

Payloads from this webhook have several 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 previously.
data.check.check_type: The type of check was run. When the Company document verification check was run, the value is COMPANY_DOCUMENT_VERIFICATION.
data.check.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 previously.
data.check.result: The results of the check. Possible results for the Company document verification check are Pass, Fail, or Error.

When the check results are returned from the data provider, Passfort cross-references the information from the company'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 it.

In this example, a Company document verification check passed.

Sample payload:

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

Use the response to:

Confirm the check passed:

If the check has passed, the data.check.result is Pass.
If the check hasn't passed, the data.check.result is Fail.
If an error occurred, the 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 this 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 endpoint.

Request endpoint:

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

In this example, the Company document verification check passed.

Sample response:

{
    "check_type": "COMPANY_DOCUMENT_VERIFICATION",
    "completed_on": "2019-10-03 14:28:02",
    "decision": "PASS",
    "document_id": "9a92b3c5-e804-06bc-cccc-6b3b43ea2a7a",
    "errors": [ ],
    "id": "ea70ade9-3de3-1785-203b-68044cd3ecbb",
    "input_data": {
        "documents": [
            {
                "category": "PROOF_OF_BANK_ACCOUNT",
                "document_type": "BANK_STATEMENT",
                "id": "9a92b3c5-e804-06bc-cccc-6b3b43ea2a7a",
                "images": [
                    {
                        "id": "ec1565b6-82c7-0577-8b3a-94462b67c97a",
                        "image_type": "FRONT",
                        "upload_date": "2019-10-03 14:05:19"
                    }
                ]
            }
        ],
        "entity_type": "COMPANY",
        "metadata": {
            "addresses": [
                {
                    "country": "GBR",
                    "locality": "London",
                    "original_freeform_address": "38, Crown Street, London, W1 2ZT",
                    "original_structured_address": { ... },
                    "postal_code": "W1 2ZT",
                    "route": "Crown Street",
                    "street_number": "38",
                    "type": "STRUCTURED"
                }
            ],
            "country_of_incorporation": "GBR",
            "name": "AERIAL TRADERS"
        }
    },
    "instructed_on": "2019-10-03 14:26:44",
    "output_data": {
        "documents": [
            {
                "category": "PROOF_OF_BANK_ACCOUNT",
                "document_type": "BANK_STATEMENT",
                "id": "ce712852-ef66-11e9-9774-3607af249582",
                "images": [
                    {
                        "id": "9e3ca2d4-ef66-11e9-bbe4-a6cea75352cd",
                        "image_type": "FRONT",
                        "upload_date": "2019-10-15 16:12:43"
                    }
                ],
                "verification_result": {
                    "all_passed": true,
                    "field_checks": [
                        {
                            "field": "FIELD_EXPIRY",
                            "result": "CHECK_VALID"
                        }
                    ],
                    "forgery_checks_passed": true,
                    "provider_name": "IDVCheck"
                }
            }
        ],
        "entity_type": "COMPANY"
    },
    "performed_on": "2019-10-03 14:26:48",
    "providers": [
        {
            "instructed_on": "2019-10-03 14:26:44",
            "provider_name": "idvcheck",
            "variant_name": "idvcheck for Forexo Pro"
        }
    ],
    "result": "Pass",
    "started_on": "2019-10-15 16:16:36",
    "state": "COMPLETE",
    "task_ids": [
        "3d7a333c-418d-72a1-007b-06854dbb28eb"
    ],
    "variant": {
        "id": "5562c4e4-4d12-b16a-a151-7c9eed6816e9",
        "name": "Verify bank account - Forexo"
    }
}

The input_data.documents array of objects that is returned in the response contains important information about the documents:

extracted_data: An object containing all the information the data provider extracted from the document.
verification_result.field_checks: A set of comparisons between the information extracted from the data provider and the information in the profile.
verification_result.forgery_checks: The results of any forgery checks conducted by the data provider.

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

all_passed: When all the image, forgery, and field checks have passed, the value of this key is true. When one or more checks have failed, the value of this key is false.
document_type_passed: When the correct document_type was used, the value of this key is true. If an incorrect document_type was used, the value of this key is false.
error_reason: A description about why the check returned an error.
field_checks: An array of objects that contains one object for every profile field that was cross-referenced with the information extracted from the data provider.
forgery_checks: An array of objects that 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 key is true. When one or more forgery checks failed, the value of this key 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 key is true. When one or more image checks failed, the value of this key 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 the results of a specific check.

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

In this section:

Using Passfort