Run a Company data check (API)

This developer guide takes you through the steps to run a Company data check in the PassFort API 4.0 to provide basic information about a company (e.g. name, date of incorporation, officers, shareholders, and financial information).

The type of company information returned depends on your data provider. To learn more, see the data provider articles linked at the bottom of the description of the Company data check.
If you're using the full PassFort product, you can run this check on the following tasks: Assess financials (COMPANY_ASSESS_FINANCIALS), Identify officers (COMPANY_IDENTIFY_OFFICERS), Identify shareholders (COMPANY_IDENTIFY_BENEFICIAL_OWNERS), and Verify company details (COMPANY_VERIFY_IDENTITY). The tasks depend on which data provider you're using. To learn more, see the data provider articles linked at the bottom of the description of the Company data check.

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

First, choose a profile for the check and get the profile ID (more information below).

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

Get the profile's ID

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

Choose a company 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 confirm it has the required fields and also to run the check later.

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

Sample response: 

{
   "applications": [ ... ],
   "category": "APPLICANT",
   "checks": [ ],
   "collected_data": {
      "entity_type": "COMPANY",
      "metadata": {
         "country_of_incorporation": "GBR",
         "name": "AERIAL TRADERS",
         "number": "012345678"
        ]
      }
    },
    "collection_steps": [ ],
    "creation_date": "2021-05-06 10:51:40",
    "display_name": "AERIAL TRADERS",
    "document_images": [ ],
    "events": [ ],
    "has_associates": false,
    "id": "a2c4393a-e219-67a4-5ab4-2186952e9038",
    "last_modified_date": "2021-05-06 10:51:44",
    "linked_to": [ ],
    "role": "COMPANY_CUSTOMER",
    "root_id": "6bba3592-d9de-1ee5-8e97-ba8d8d13c558",
    "status": "NORMAL",
    "tags": [ ],
    "unresolved_event_types": [ ]
}

Use the response to:

Confirm the profile has data for these required keys, which are in the collected_data object:

  1. metadata.country_of_incorporation: The country in which the company is incorporated.
  2. metadata.name: The legal name of the company.
  3. metadata.number: The company's registration number. Note that if you're using Bureau van Dijk Orbis, you can provide the Bureau van Dijk Orbis ID number (metadata.bvd_id) instead.

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.

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

To learn which optional profile fields can be used for this check, see the article for your data provider: BREX the kompany API, Bureau van Dijk Orbis, Companies House, CreditorWatch, Creditsafe Company Data API.

If you're using the full PassFort product, you should also take this opportunity to confirm the profile has the tasks you want to run the check on and note the task ID (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".

2. Run the check

Sending the request

To run the check, make a request to the endpoint below.

Request endpoint: 

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

By default, the Company data check runs asynchronously. You can send mode as a query parameter to run the check synchronously.

Body parameters:

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

Key

Value

Description

check_type

Required

String

COMPANY_DATA

The type of check that's being run.

variant

Optional (but we recommend including it whenever possible)

Object

For a sample value, see the sample request body below.

Object to indicate which variant of the check will run.

variant.alias

Required

String

This key is optional if variant.id is provided. We recommend sending the alias whenever possible.

Sample value:

company_data

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 example below, we'll run the check on the Identify officers task.

Sample request body:

{
    "check_type": "COMPANY_DATA",
    "variant": {
        "alias": "company_data"
    }
}

Sample response: 

{
    "check_type": "COMPANY_DATA",
    "id": "ea565b55-47d9-1858-4588-3a22a3838707",
    "instructed_on": "2021-05-06 11:05:05",
    "performed_on": "2021-05-06 11:05:05",
    "providers": [],
    "state": "PENDING",
    "variant": {
        "alias": "company_data",
        "id": "ea70ade9-3de3-1785-203b-68044cd3ecbb",
        "name": "Company data check"
    }
}

Take note of the check id in the response because you'll need it for the next steps to get the check result.

If you're using the full PassFort product, you should also include the task_ids in the request to indicate which task the check should run on. If you don't provide a task_ids, the check will run on whichever applicable task(s) the profile has.
Because this check runs asynchronously, the check state is expected to be PENDING in the response.
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 (including checks other than the Company data check).

Payloads from this webhook have several important keys:

  1. secret: Authenticate the request by ensuring this secret matches your secret.
  2. id: The check ID. Use it to confirm the payload is for your check by matching it to the check ID you captured when you ran the check.
  3. data.check.check_type: The type of check that was run. When the Company data check was run, the value will be COMPANY_DATA_CHECK.
  4. data.check.result: The result of the check. Possible results for the Company data check are Pass, Partial, Fail, or Error. To learn what causes these check results, see the article for your data provider.

In this example, the Company data check returned information for the company.

Sample payload:

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

See Getting more information about the check result to learn which data was discovered.

Getting more information about the check result

If you want to get more information about the check result, make a call to the endpoint below.

In the request body, include the profile ID and the check ID.

Request endpoint:

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

In this example, the check passes and two directors are returned from Companies House.

Sample response:

{
    "check_type": "COMPANY_DATA",
    "completed_on": "2021-05-06 11:05:09",
    "decision": "PASS",
    "errors": [],
    "id": "ea565b55-47d9-1858-4588-3a22a3838707",
    "input_data": {
        "entity_type": "COMPANY",
        "metadata": {
            "country_of_incorporation": "GBR",
            "name": "AERIAL TRADERS",
            "number": "012345678"
        }
    },
    "instructed_on": "2021-05-06 11:05:05",
    "output_data": {
        "entity_type": "COMPANY",
        "metadata": {
            "addresses": [
                {
                    "address": {
                        "country": "GBR",
                        "county": "Greater London",
                        "latitude": 51.5132105,
                        "longitude": -0.0870753,
                        "original_freeform_address": "38, Crown Street, London, W1 2ZT",
                        "postal_code": "W1 2ZT",
                        "postal_town": "London",
                        "route": "Crown Street",
                        "state_province": "England",
                        "street_number": "38",
                        "type": "STRUCTURED"
                    },
                    "type": "registered_address"
                }
            ],
            "company_type": "ltd",
            "country_of_incorporation": "GBR",
            "incorporation_date": "1995-08-04",
            "is_active": true,
            "jurisdiction": "england-wales",
            "name": "AERIAL TRADERS",
            "number": "012345678",
            "registry": "Companies House (UK)",
            "sic_codes": [ … ],
            "structured_company_type": {
                "is_limited": true,
                "is_public": false,
                "ownership_type": "COMPANY"
            }
        },
        "mismatched_fields": [],
        "officers": {
            "directors": [
                {
                    "appointed_on": "1995-04-01",
                    "entity_type": "INDIVIDUAL",
                    "immediate_data": {
                        "address_history": [ … ],
                        "entity_type": "INDIVIDUAL",
                        "personal_details": {
                            "dob": "1966-09",
                            "name": {
                                "family_name": "FITZWILLIAM",
                                "given_names": [
                                    "Ashley",
                                    "Remington"
                                ]
                            },
                            "nationality": "GBR"
                        }
                    },
                    "original_role": "Director",
                    "provider_name": "Companies House",
                    "resolver_id": "d669473a-8e9d-a923-0a580a000732"
                },
                {
                    "appointed_on": "2007-12-01",
                    "entity_type": "INDIVIDUAL",
                    "immediate_data": {
                        "address_history": [ … ],
                        "entity_type": "INDIVIDUAL",
                        "personal_details": {
                            "dob": "1980-10",
                            "name": {
                                "family_name": "ALI KHAN",
                                "given_names": [
                                    "Nayab"
                                ]
                            },
                            "nationality": "CDN"
                        }
                    },
                    "original_role": "Director",
                    "provider_name": "Companies House",
                    "resolver_id": "1c8a8070-8e8d-11e9-a96d-0a580a00182e"
                }
            ],
            "other": [],
            "partners": [],
            "resigned": [],
            "secretaries": []
        },
        "ownership_structure": {
            "beneficial_owners": [ ... ]
        }
    },
    "performed_on": "2021-05-06 11:05:09",
    "providers": [
        {
            "instructed_on": "2021-05-06 11:05:05",
            "provider_name": "Companies House",
            "variant_name": "Company data check"
        }
    ],
    "result": "Pass",
    "started_on": "2021-05-06 11:05:05",
    "state": "COMPLETE",
    "variant": {
        "alias": "company_data",
        "id": "ea70ade9-3de3-1785-203b-68044cd3ecbb",
        "name": "Companies data check"
    }
}

Use the output_data in the response to see the company information:

  • metadata: Shows general information about the company. This data is used for the Verify company details task.
  • officers: Shows information about the company officers. This data is used for the Identify officers task.
  • ownership_structure: Shows information about the company shareholders. This data is used for the Identify shareholders task.
  • immediate_data: Shows information about a specific company officer or shareholder. Its structure is identical to the collected_data on a profile. If you want to perform due diligence on the company officer or shareholder, you should create a profile for the associate, using the immediate_data as the collected_data
  • financials: Shows information about the company's financial data. This data is used for the Assess financials task.

Ongoing monitoring

Some data providers offer ongoing monitoring for the Company data check. This means that after the check has been run the first time, the profile is monitored for any new information that could be imported to the check results.

To find out if your data provider offers ongoing monitoring and, if so, which data is monitored and how to configure this in the Policy Builder, see the article for your data provider.

To update the profile with any new results that your data provider discovers, first ensure you're listening to the Events created webhook by logging into the Portal following these steps

After this:

  1. If the data provider discovers new results for the profile, the Events created webhook will be fired with CHECK_EXPIRY as the event_type. You can see a sample payload in the API Resources.
  2. When you receive the payload, take note of the profile_id to learn which profile is impacted, then follow the steps above to re-run the Company data check on the profile. This will import the updated information to the profile.
It's important to look at the event_type in the payload because the Events created webhook fires for any check type with ongoing monitoring (including checks other than the Company data check). 


How did we do?


Powered by HelpDocs (opens in a new tab)