Skip to main content

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:

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 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.

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": { … }
}

Additional information