Run a Website content check (API)

This developer guide takes you through the steps to run a Website content check in the PassFort API 4.0 to assess the risk of a company's public-facing website.

This check is run on the Assess website content risk (COMPANY_ASSESS_WEBSITE_CONTENT) task.

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 it has the required fields for the Website content check to run successfully (documented below).

Get the profile's ID

This check is 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 to run the check later.

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". The profile has the Assess website content risk task. 

Sample response: 

{
   "applications": [ ... ],
   "category": "APPLICANT",
   "checks": [ ... ],
   "collected_data": {
      "entity_type": "COMPANY",
      "customer_ref": "1234",
      "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"
               }
            }
         ],
         "contact_details": {
             "url": "passfort.com"
         }, 
         "country_of_incorporation": "GBR",
         "name": "AERIAL TRADERS",
         "number": "012345678"
        ]
    },
    "collection_steps": [ ],
    "creation_date": "2020-06-29 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_ASSESS_WEBSITE_CONTENT"
    ],
    "tasks": [
        {
            "check_ids": [ ],
            "creation_date": "2020-06-29 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_ASSESS_WEBSITE_CONTENT",
            "variant": {
                "alias": "website_content",
                "id": "e5afcd76-5cfd-51d2-97d1-2d812e1df411",
                "task_type": "COMPANY_ASSESS_WEBSITE_CONTENT"
            }
        }
    ],
    "unresolved_event_types": [ ]
}

Use the response to: 

1. Confirm the profile has the Assess website content risk task (COMPANY_ASSESS_WEBSITE_CONTENT).
2. Take note of the task ID (tasks.id). 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) won't be used to run the check.
3. Confirm the profile has data for these required keys, which are in the collected_data object:
   1. metadata.name: The company's name.
   2. metadata.addresses.address: The company's address. If the addresses array contains multiple addresses, the first available address will be used.
   3. contact_details.url: The company's website.

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 Update PassFort's profile data.

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

Body parameters: 

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

Sample request body: 

{
   "check_type": "COMPANY_WEBSITE_CONTENT",
    variant: {
       "alias": "default"
    }
}

Sample response: 

{
    "check_type": "COMPANY_WEBSITE_CONTENT",
    "id": "ea565b55-47d9-1858-4588-3a22a3838707",
    "instructed_on": "2020-06-29 14:26:44",
    "performed_on": "2020-06-29 14:26:44",
    "providers": [],
    "state": "PENDING",
    "task_ids": [ ... ],
    "variant": { ... }
}

Take note of the check id in the response because you'll need it to get more information about the check result.

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.

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 in step 2.
3. data.check.check_type: The type of check was run. When the Website content check was run, the value is COMPANY_WEBSITE_CONTENT.
4. 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 in step 2.
5. data.check.result: The results of the check. Possible results for the Website content check are Pass, Refer, or Error. To learn more about these results, see Configuring G2 Automation API.

Sample payload:

{
  "id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
  "event": "CHECK_COMPLETED",
  "secret": "yourSecret",
  "timestamp": 1570807808,
  "data": {
    "check": {
      "check_type": "COMPANY_WEBSITE_CONTENT",
      "id": "ea565b55-47d9-1858-4588-3a22a3838707",
      "result": "Refer",
      "variant": {
        "alias": "website_content",
        "id": "ea565b55-47d9-1858-4588-3a22a3838707",
        "name": "Website content check"
      }
    },
    "customer_ref": null,
    "profile_id": "a2c4393a-e219-67a4-5ab4-2186952e9038"
  }
}

See Getting more information about the check result to learn why the check result was returned and more.

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}

Sample response body:

{
    "check_type": "COMPANY_WEBSITE_CONTENT",
    "completed_on": "2021-01-05 02:39:14",
    "decision": "WARN",
    "errors": [],
    "id": "2d20e97c-bab8-11ea-b0e9-5c33da64241d",
    "input_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"
                 }
              }
           ],
           "contact_details": {
              "url": "www.passfort.com"
           },
           "name": "Aerial Traders"
        }
    },
    "instructed_on": "2020-06-29 14:27:50",
    "output_data": {
        "entity_type": "COMPANY",
        "website_screening": {
            "assessment_messages": [
                {
                    "description": "YellowPages.com requires a business address.",
                    "level": "CRITICAL"
                },
                {
                    "description": "Better Business Bureau module not run. No business address was provided.",
                    "level": "CRITICAL"
                },
                {
                    "description": "OpenCorporates could not run because a jurisdiction could not be determined from the address.",
                    "level": "CRITICAL"
                },
                {
                    "description": "OpenCorporates corporate search not run. No business address was provided.",
                    "level": "CRITICAL"
                },
                {
                    "description": "The following required pages could not be found: Contact About Us Page",
                    "level": "WARNING"
                },
                {
                    "description": "The following required pages could not be found: Delivery Policy",
                    "level": "WARNING"
                },
                {
                    "description": "The following required pages could not be found: Payment Policy",
                    "level": "WARNING"
                },
                {
                    "description": "The following required pages could not be found: Refund Policy",
                    "level": "WARNING"
                },
                {
                    "description": "The following required pages could not be found: Return Policy",
                    "level": "WARNING"
                },
                {
                    "description": "The following required pages could not be found: Privacy Policy",
                    "level": "WARNING"
                },
                {
                    "description": "The following required pages could not be found: Terms of Service",
                    "level": "WARNING"
                },
                {
                    "description": "Corporate or DBA name match not found on Terms and Conditions Page",
                    "level": "WARNING
                },
                {
                    "description": "No personal address was provided.",
                    "level": "WARNING"
                },
                {
                    "description": "No business address was provided.",
                    "level": "WARNING"
                },
                {
                    "description": "No Yelp! results were found.",
                    "level": "WARNING"
                },
                {
                    "description": "Unable to search Pipl; at least one name or phone number required.",
                    "level": "WARNING"
                },
                {
                    "description": "No company name was provided, could not search Complaints Board",
                    "level": "WARNING"
                },
                {
                   "description": "Yelp! search not performed; no business address provided",
                    "level": "WARNING"
                },
                {
                    "description": "No Google Places search performed because no company address was provided.",
                    "level": "WARNING"
                },
                {
                    "description": "This is a high traffic site (Alexa rank 13983)",
                    "level": "INFO"
                },
                {
                    "description": "Prohibited phrases were not found.",
                    "level": "OK"
                },
                {
                    "description": "No Consumer Financial Protection Bureau results Consumer Complaints Database results were found.",
                    "level": "OK"
                },
                {
                    "description": "Google SafeBrowsing reported no malware or phishing.",
                    "level": "OK"
                },
                {
                    "description": "No search results found on the Federal Trade Commission web site.",
                    "level": "OK"
                },
                {
                    "description": "No reasonable OFAC SDN matches were found.",
                    "level": "OK"
                },
                {
                    "description": "No Justia lawsuits found.",
                    "level": "OK"
                },
                {
                    "description": "Alexa reported no adult content.",
                    "level": "OK"
                }
            ],
            "document": {
                "category": "DATA_SUMMARY",
                "document_type": "DATA_SUMMARY",
                "files": null,
                "id": "3300b90c-4eff-11eb-9c9a-5af05ce21265",
                "images": [
                    {
                        "file_id": "32df2306-4eff-11eb-bed1-5af05ce21265",
                        "id": "3300a49a-4eff-11eb-8042-5af05ce21265",
                        "image_type": "FRONT",
                        "upload_date": "2021-01-05 02:39:14"
                    }
                ]
            },
            "g2_compass_score": {
                "reason_codes": [
                    {
                        "name": "105150",
                        "value": "URL previously associated with high-risk MCC"
                    }
                ],
                "request_id": "6ab415a2-79a7-4c2a-213d-c81b58d22a1e",
                "score": 0,
                "threshold": 10
            },
            "provider_id": "refer",
            "valid_url": true
        }
    },
    "performed_on": "2020-06-29 14:27:50",
    "providers": [
        {
            "instructed_on": "2020-06-29 14:27:50",
            "provider_name": "G2 KYC Automation API",
            "variant_name": "G2 KYC Automation API"
        }
    ],
    "result": "Refer",
    "started_on": "2020-06-29 14:27:50",
    "state": "COMPLETE",
    "task_ids": [ … ],
    "variant": { … }
}

The result shows the overall result of the website assessment. It provides a high-level understanding of whether the website content is considered risky. If the result is Pass, the website content risk is below your threshold. If it's Refer, the website content may be risky and should be reviewed by an analyst.

The output_data.website_screening object contains information about the website risk assessment:

• assessment_messages: Shows any messages returned from the data provider. If there are any messages with level that is CRITICAL or WARNING, the overall result is refer.
• document: Includes details for the PDF of the full site scan report. The PDF is stored as a document in the profile's collected_data.
• g2_compass_score: Includes details about the compass score. 
• g2_compass_score.score: The score for the website. This is a number between 0-1000, where 1 indicates low risk, 1000 indicates high risk, and 0 signifies there are not strong indicators of positive or negative risk.
• g2_compass_score.threshold: This is set in the data provider configuration and determines the threshold for when the score indicates risk to your company. If the score is higher than the threshold, the overall result is refer. 
• g2_compass_score.reason_codes: Contains the reason the data provider has assigned the compass score.

The input_data object contains all the profile details that the data provider used for the assessment.