Run a Fraud check
This developer guide takes you through the steps to run a Fraud check for individuals or companies in the Passfort API 4.0 to confirm whether a profile has any potential matches in the Cifas National Fraud Database.
This check can be run on the following tasks:
Assess individual fraud risk (
INDIVIDUAL_FRAUD_SCREENING
)Assess company fraud risk (
COMPANY_FRAUD_SCREENING
)
Choose a profile and get the profile ID
Fraud checks can be run on profiles with the INDIVIDUAL
entity type or COMPANY
entity type.
Choose a 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 also to run the check later.
If you haven't created the profile yet, follow the steps to create a profile using the API. If you have access to 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 /profiles/
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 an individual profile named "Alex Wheeler." The profile has the Assess individual fraud risk task.
{ "applications": [ ... ], "category": "APPLICANT", "checks": [ ], "collected_data": { "entity_type": "INDIVIDUAL", "address_history": [ { "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" } } ], "personal_details": { "name": { "family_name": "Wheeler", "given_names": [ "Alex" ] } } }, "collection_steps": [ ], "creation_date": "2020-01-21 12:50:07", "display_name": "Alex Wheeler", "document_images": [ ], "events": [ ], "has_associates": false, "has_collection_steps": false, "id": "a2c4393a-e219-67a4-5ab4-2186952e9038", "linked_to": [ ], "role": "INDIVIDUAL_CUSTOMER", "root_id": "6bba3592-d9de-1ee5-8e97-ba8d8d13c558", "status": "NORMAL", "tags": [ ], "task_progress": { ... }, "task_types": [ "INDIVIDUAL_FRAUD_SCREENING" ], "tasks": [ { "check_ids": [ ], "creation_date": "2020-01-17 12:50:07", "form_instance_ids": [ ], "id": "3d7a333c-418d-72a1-007b-06854dbb28eb", "is_complete": false, "is_expired": false, "is_skipped": false, "state": "INCOMPLETE", "type": "INDIVIDUAL_FRAUD_SCREENING", "variant": { "alias": "fraud_check_individuals", "id": "ddc72ea7-6e45-cc3b-dc52-30a94b9ec8c2", "task_type": "INDIVIDUAL_FRAUD_SCREENING" } } ], "unresolved_event_types": [ ] }
Use the response to:
Confirm the profile has the right task. To run this check on an individual profile, there must be a task with the
INDIVIDUAL_FRAUD_SCREENING
type. To run this check on a company profile, there must be a task with theCOMPANY_FRAUD_SCREENING
type.Take note of the task ID, or
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"
. 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.If you're running the check on an individual profile, confirm it has these required keys in the
collected_data
object:personal_details.name.given_names
: The individual's first and, if applicable, middle names.personal_details.name.family_name
: The individual's surname.
If you're running the check on a company profile, confirm it has these required keys in the
collected_data
object:metadata.name
: The legal name of the company.metadata.number
: The company's registration number.
If the required fields don't exist on the profile or don't contain valid data, the check returns 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.
To learn which optional profile fields can be used for this check, see Configuring Cifas National Fraud Database.
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 Fraud check runs synchronously.
You can also send mode
as a query parameter to run the check asynchronously.
Body parameters for individual profiles:
When you make the POST
request for an individual profile, 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 string | Sample value: | When you're running the check on an individual profile, this is the unique identifier for the |
*Required object | For a sample value, see the following section, Example: Individual profile | 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. |
Body parameters for company profiles:
When you make the POST
request for a company profile, 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 string | Sample value: | When you're running the check on a company profile, this is the unique identifier for the |
*Required object | For a sample value, see the following section. Example: Company profile. | 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. |
Read the response
Use the response to see the result of the check:
If the check has passed, the
result
isPass
.If the check needs further review, the
result
isRefer
.If an error occurred, the
result
isError
.
The output_data
object that's returned in the response contains the information returned from the data provider:
fraud_detection.match_count
: This is the number of matches discovered in the Cifas National Fraud Database.fraud_detection.search_reference
: This is the reference number returned from Cifas. You can use it to get the full results from the Cifas portal.
Example: Individual profile
In the following example, we'll run the check on an individual profile.
We can see from the sample response that one match has been returned from the Cifas National Fraud Database , so the check result is Review.
Sample request body:
{ "check_type": "FRAUD_SCREENING", "task_ids": [ "3d7a333c-418d-72a1-007b-06854dbb28eb" ], "variant": { "alias": "default" } }
Sample response:
{ "check_type": "FRAUD_SCREENING", "completed_on": "2020-01-21 14:33:23", "decision": "WARN", "errors": [ ], "id": "72aadb55-8b02-8495-d6b0-e1627ec23612", "input_data": { "address_history": [ { "address": { "country": "GBR", "locality": "London", "original_freeform_address": "38, Crown Street, London, W1 2ZT", "original_structured_address": { "country": "GBR", "locality": "London", "postal_code": "W1 2ZT", "route": "Crown Street", "street_number": "38" }, "postal_code": "W1 2ZT", "route": "Crown Street", "street_number": "38", "type": "STRUCTURED" } } ], "contact_details": { }, "entity_type": "INDIVIDUAL", "personal_details": { "name": { "family_name": "Wheeler", "given_names": [ "Alex" ] }, "national_identity_number": { } } }, "instructed_on": "2020-01-21 14:33:23", "output_data": { "entity_type": "INDIVIDUAL", "fraud_detection": { "database_type": "CIFAS", "match_count": 1, "search_reference": "1579530803" } }, "performed_on": "2020-01-21 14:33:23", "providers": [ { "instructed_on": "2020-01-21 14:33:23", "provider_name": "Cifas National Fraud Database", "variant_name": "Cifas" } ], "result": "Refer", "started_on": "2020-01-20 14:33:23", "state": "COMPLETE", "task_ids": [ "3d7a333c-418d-72a1-007b-06854dbb28eb" ], "variant": { ... } }
Example: Company profile
In the following example, we'll run the check on a company profile.
We can see from the sample response that no matches have been returned from the Cifas National Fraud Database , so the check result is Pass.
Sample request body:
{ "check_type": "COMPANY_FRAUD_SCREENING", "task_ids": [ "3d7a333c-418d-72a1-007b-06854dbb28eb" ], "variant": { "alias": "default" } }
Sample response:
{ "check_type": "COMPANY_FRAUD_SCREENING", "completed_on": "2020-01-21 14:33:23", "decision": "PASS", "errors": [ ], "id": "72aadb55-8b02-8495-d6b0-e1627ec23612", "input_data": { "entity_type": "COMPANY", "metadata": { "addresses": [ { "address": { "country": "GBR", "locality": "London", "original_freeform_address": "38, Crown Street, London, W1 2ZT", "original_structured_address": { "country": "GBR", "locality": "London", "postal_code": "W1 2ZT", "route": "Crown Street", "street_number": "38" }, "postal_code": "W1 2ZT", "route": "Crown Street", "street_number": "38", "type": "STRUCTURED" } } ], "name": "AERIAL TRADERS", "number": "012345678" } }, "instructed_on": "2020-01-21 14:33:23", "output_data": { "entity_type": "COMPANY", "fraud_detection": { "database_type": "CIFAS", "match_count": 0, "search_reference": "1579607344" } }, "performed_on": "2020-01-21 14:33:23", "providers": [ { "instructed_on": "2020-01-21 14:33:23", "provider_name": "Cifas National Fraud Database", "variant_name": "Cifas National Fraud Database - Forexo Pro" } ], "result": "Pass", "started_on": "2020-01-21 14:33:23", "state": "COMPLETE", "task_ids": [ "3d7a333c-418d-72a1-007b-06854dbb28eb" ], "variant": { … } }