Run a Website content check using the 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.
Choose a profile and get the profile 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, for example, 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 profile yet, follow the steps to create a profile using 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:
Confirm the profile has the Assess website content risk task (
COMPANY_ASSESS_WEBSITE_CONTENT
).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.Confirm the profile has data for these required keys, which are in the
collected_data
object:metadata.name
: The company's name.metadata.addresses.address
: The company's address. If theaddresses
array contains multiple addresses, the first available address will be used.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 when your system data changes.
If the profile has a customer reference number (customer_ref
), it will also be sent to the data provider.
Run the check
To run the check, send a request to the following endpoint.
Request endpoint:
POST https://api.passfort.com/4.0/profiles/{profile_id}/checks
By default, the Website content check runs asynchronously. You can also 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 |
*Required string |
| The type of check that's being run. |
Optional, but we recommend including it whenever possible. array of string | Sample value: | The unique identifier for the task variant the check will run on, such as the |
*Required object | For a sample value, see the following sample request body. | Object to indicate which variant of the check will run. |
*Required string This key is optional if | Sample value: | The check alias. |
*Required string This key is optional if | Sample value: | 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 to learn what the result is.
Note
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:
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 earlier.data.check.check_type
: The type of check was run. When the Website content check was run, the value isCOMPANY_WEBSITE_CONTENT
.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.data.check.result
: The results of the check. Possible results for the Website content check arePass
,Refer
, orError
. 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 Get more information about the check result to learn why the check result was returned and more.
Get more information about the check result
If you want to get more information about the check result, make a call to the following endpoint.
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 withlevel
that isCRITICAL
orWARNING
, 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'scollected_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 one 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 thescore
is higher than thethreshold
, the overall result isrefer
.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.
Note
The messages may not contribute to the compass score. Speak to your G2 account manager to learn more.