Run a Fraud check (API)

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 Assess individual fraud risk task (INDIVIDUAL_FRAUD_SCREENING) or the Assess company fraud risk (COMPANY_FRAUD_SCREENING) 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 (documented below) for the Fraud check to run successfully.

Get the profile's 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 (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 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 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:

  1. 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.
  2. Take note of the task ID (tasks.id). Use the corresponding task alias (tasks.variant.alias) to confirm you're looking at the right task. 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.
  3. If you're running the check on an individual profile, confirm it has these required keys in the collected_data object:
    1. personal_details.name.given_names: The individual's first and, if applicable, middle names.
    2. personal_details.name.family_name: The individual's surname.
  4. If you're running the check on a company profile, confirm it has these required keys in the collected_data object:
    1. metadata.name: The legal name of the company.
    2. metadata.number: The company's registration number.

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.

To learn which optional profile fields can be used for this check, see Configuring Cifas National Fraud Database.

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 Fraud check runs synchronously. You can 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.

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.

Reading 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 example below, we'll run the check on an individual profile.

We can see from the sample response that 1 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"
]
}

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 example below, we'll run the check on an individual 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"
]
}

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


How did we do?


Powered by HelpDocs