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 /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 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 the COMPANY_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
`check_type` *Required string	`FRAUD_SCREENING`	The type of check that's being run.
`task_ids` Optional, but we recommend including it whenever possible string	Sample value: `3d7a333c-418d-72a1-007b-06854dbb28eb`	When you're running the check on an individual profile, this is the unique identifier for the `INDIVIDUAL_FRAUD_SCREENING` task.
`variant` *Required object	For a sample value, see the following section, Example: Individual profile	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.

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
`check_type` *Required string	`COMPANY_FRAUD_SCREENING`	The type of check that's being run.
`task_ids` Optional, but we recommend including it whenever possible string	Sample value: `3d7a333c-418d-72a1-007b-06854dbb28eb`	When you're running the check on a company profile, this is the unique identifier for the `COMPANY_FRAUD_SCREENING` task.
`variant` *Required object	For a sample value, see the following section. Example: Company profile.	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.

Read the response

Use the response to see the result of the check:

If the check has passed, the result is Pass.
If the check needs further review, the result is Refer.
If an error occurred, the result is Error.

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.