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.

If you haven't created the company's 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 /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". 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.

If the profile has a customer reference number (customer_ref), it will also be sent to the data provider.

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 Website content check runs asynchronously, but 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_WEBSITE_CONTENT

The type of check that's being run.

task_ids

Optional (we recommend including it whenever possible)

Array of string

Sample value: 3d7a333c-418d-72a1-007b-06854dbb28eb

The unique identifier for the task variant the check will run on (i.e. the COMPANY_ASSESS_WEBSITE_CONTENT task).

variant

Optional (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, 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.

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.

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 learn what the result is.

This webhook sends a payload whenever results are returned from any check (including checks other than the Website content 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 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.

The messages may not contribute to the compass score. Speak to your G2 account manager to learn more.

How did we do?


Powered by HelpDocs (opens in a new tab)