Create profiles in the API

This developer guide takes you through the steps to create a profile in the Passfort API 4.0.

What are profiles?

Profiles correspond to the applicants and customers who are applying for your products.

There are two profile types:

Individual profiles: Used for prospects and customers who are people.
Company profiles: Used for prospects and customers who are companies.

The profile’s type affects what data can be stored in it, which tasks it can have, and which checks can be run on it. But all profiles, regardless of type, go through the same product application processes for onboarding and monitoring.

There are three main fields for a profile when it’s first created:

role: This required field indicates whether the profile type is an individual or a company.

If you're creating a company associate, the role field indicates it's a company associate.

collected_data: This required field is an object that contains most of the information about the individual or company. For example, for individual profiles, it can contain the individual’s name, address history, and more. On company profiles, it can contain the company’s name, company number, country of incorporation, and more.
applications: This optional field is an array of objects used to assign product applications to the profile. Each product application corresponds to one object in the array.

To learn how to add a product application after you create the profile, using a separate call, see Add a product application to a profile. To learn how to onboard a company's associates, see Create a profile for an associate and link it to a company in the API.

Create a profile through the API

Use the API to create a profile.

Sending the request

Make a request to the following endpoint.

Request endpoint:

POST https://api.passfort.com/4.0/profiles

When you make the request, you need to pass these parameters:

role: The profile’s type. For individual profiles, the value is INDIVIDUAL_CUSTOMER. For company profiles, the value is COMPANY_CUSTOMER.
collected_data: An object that contains basic profile information, such as the individual’s name.

You may also want to pass one or more product applications in the applications array so the profile applies for those products. If you don’t pass any applications in the array, the profile automatically applies for any products on your account that have the auto_apply attribute.

All the required and optional fields you can pass are listed in the Create a profile developer resources.

If you’re passing a product application in the request, use the product’s alias, rather than the product ID, where possible to identify the product for the application.

Passfort does not have any character limitations for profile data unless otherwise specified in the API reference. However, your data provider may specify their own limitations for the data when it's used to run checks. Contact your data provider to find out more.

To use the portal to see if a product has the auto_apply attribute, go to Policy Builder > Products and select the product. If the New profiles will automatically apply for this product checkbox is selected, the product has the auto_apply attribute.

Reading the response

When the profile is created, there are some important parts that are added to the profile automatically, which you can see in the response:

tasks: An object containing a list of due diligence tasks that need to be completed for the profile’s product applications to be approved.
checks: An object containing a history of any checks that have been run on the profile to assist in completing tasks.

The smart policy for each product application determines which tasks are added to the profile and which checks are run automatically.

However, when you first create a profile, tasks and checks will likely be empty. This can happen for a number of reasons. For example, the application’s risk level may still be calculating, or the smart policy may require more profile data to continue.

If the profile has any product applications, the applications.flag field contains the application’s current state.

To get a notification when a check is completed, listen to the Check completed webhook. After you’ve created a profile, you can sync the profile data with your system data.

Example: Individual profile

In this example, an individual profile is created for someone named Alex D Wheeler with a custom field. The profile applies to a product with the alias forexo_basic.

If you’re copying this sample request for your own testing, remember to replace forexo_basic with your product alias or remove the applications object.

Sample request body:

{
    "applications": [
        {
            "product": {"alias": "forexo_basic"}
        }
    ],
    "role": "INDIVIDUAL_CUSTOMER",
    "collected_data": {
        "entity_type": "INDIVIDUAL",
        "personal_details": {
            "name": {
                "given_names": [
                    "Alex",
                    "D"
                ],
                "family_name": "Wheeler"
            }
        },
        "custom_fields_data": {
            "expected_monthly_payments": 1
        }
    }
}

We can see in the response that:

One task has been added to the tasks object. The task has the INDIVIDUAL_VERIFY_IDENTITY type.
No checks have been run. We can see this because the checks object is empty.

Sample response:

{
    "applications": [
        {
            "approval_blockers": [ … ],
            "assignments": [ ],
            "flag": "AUTOMATING",
            "flag_history": [ … ],
            "hidden": false,
            "history": [ … ],
            "id": "edc23993-eb6a-9d89-bb79-5b8925b33224",
            "product": {
                "alias": "forexo_basic",
                "automatically_approve": false,
                "id": "b0ce7c17-2cab-86e7-9a83-ebee0d4d5dc8",
                "name": "Forexo Basic Account"
            },
            "required_tasks": [ … ],
            "status": "APPLIED"
        }
    ],
    "category": "APPLICANT",
    "checks": [ ],
    "collected_data": {
        "entity_type": "INDIVIDUAL",
        "personal_details": { … },
        "custom_fields_data": {
            "expected_monthly_payments": 1
        }
    },
    "collection_steps": [ ],
    "display_name": "Alex D Wheeler",
    "document_images": [ ],
    "events": [ ],
    "has_associates": false,
    "has_collection_steps": false,
    "id": "a2c4393a-e219-67a4-5ab4-2186952e9038",
    "linked_to": [ ],
    "risk": { },
    "role": "INDIVIDUAL_CUSTOMER",
    "status": "NORMAL",
    "tags": [ ],
    "task_progress": {
        "completed_count": 0,
        "total_count": 1
    },
    "task_types": [
        "INDIVIDUAL_VERIFY_IDENTITY"
    ],
    "tasks": [
        {
            "check_ids": [ ],
            "creation_date": "2019-08-29 11:09:57",
            "form_instance_ids": [ ],
            "id": "3d7a333c-418d-72a1-007b-06854dbb28eb",
            "is_complete": false,
            "is_expired": false,
            "is_skipped": false,
            "state": "INCOMPLETE",
            "type": "INDIVIDUAL_VERIFY_IDENTITY",
            "variant": {
                "id": "ddc72ea7-6e45-cc3b-dc52-30a94b9ec8c2",
                "task_type": "INDIVIDUAL_VERIFY_IDENTITY"
            }
        }
    ],
    "unresolved_event_types": [ ]
}

Example: Company profile

In this example, a company profile is created for Passfort Limited. The profile applies to a product with the alias forexo_pro.

If you’re copying this sample request for your own testing, remember to replace forexo_pro with your product alias or remove the applications object.

Sample request body:

{
    "applications": [
        {
            "product": {"alias": "forexo_pro"}
        }
    ],
    "role": "COMPANY_CUSTOMER",
    "collected_data": {
        "entity_type": "COMPANY",
        "metadata": {
            "country_of_incorporation": "GBR",
            "number": "09565115",
            "name": "Passfort Limited"
        }
    }
}

We can see in the response that:

One task has been added to the tasks object. The task has the COMPANY_REVIEW_FILINGS type.
No checks have been run. We can see this because the checks object is blank.

Sample response:

{
    "applications": [
        {
            "approval_blockers": [ … ],
            "assignments": [ ],
            "flag": "AUTOMATING",
            "flag_history": [ … ],
            "hidden": false,
            "history": [ … ],
            "id": "379ec33c-5650-1c13-6288-e0369515b949",
            "product": {
                "alias": "forexo_pro",
                "automatically_approve": false,
                "id": "db3840b3-4d73-3c78-6b61-5b6262a47425",
                "name": "Forexo Pro Account"
            },
            "required_tasks": [ … ],
            "status": "APPLIED"
        }
    ],
    "category": "APPLICANT",
    "checks": [ ],
    "collected_data": {
        "entity_type": "COMPANY",
        "metadata": { … }
    },
    "collection_steps": [ ],
    "display_name": "Passfort Limited",
    "document_images": [ ],
    "events": [ ],
    "has_associates": false,
    "has_collection_steps": false,
    "id": "a2e7545b-cb67-7a0e-7108-a444461891a9",
    "linked_to": [ ],
    "risk": { },
    "role": "COMPANY_CUSTOMER",
    "status": "NORMAL",
    "tags": [ ],
    "task_progress": {
        "completed_count": 0,
        "total_count": 6
    },
    "task_types": [
        "COMPANY_REVIEW_FILINGS"
    ],
    "tasks": [
        {
            "check_ids": [ ],
            "creation_date": "2019-08-29 11:09:57",
            "form_instance_ids": [ ],
            "id": "72aadb55-8b02-8495-d6b0-e1627ec23612",
            "is_complete": false,
            "is_expired": false,
            "is_skipped": false,
            "state": "INCOMPLETE",
            "type": "COMPANY_REVIEW_FILINGS",
            "variant": {
                "id": "5562c4e4-4d12-b16a-a151-7c9eed6816e9",
                "task_type": "COMPANY_REVIEW_FILINGS"
            }
        }
    ],
    "unresolved_event_types": [ ]
}

In this section:

Using Passfort