How the product application lifecycle is tracked in the API

In Passfort, the individuals and companies applying for your products are called profiles. Profiles make product applications, which are then evaluated to see if these profiles qualify for your products.

The first time a product application is added to a profile, an applications array of objects is created on the profile. This array contains one object per product application the profile has made.

Each object in the applications array has two important fields to help you track the product application through its lifecycle:

status: Indicates what stage the product application is at in the onboarding or monitoring process. Use this field to determine whether the profile should have access to your product.
flag: Indicates what's currently happening to the product application or what needs to be done for it to progress to the next status. Use this field to understand the current processing state of the product application.

View an example applications array.

How the product application process is started using the API

The product application process is started by creating a profile and adding a product application to it.

You can do both actions with a single call to the API.

Alternatively, you can create a profile without any product applications, then use a separate call to the API to add a product application.

If you create a profile without product applications, it automatically applies to any products that have the auto_apply attribute. To see if a product has this attribute, sign into the portal, go to Policy Builder > Your 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. Contact us to remove this attribute from a product.

When you add a new product application, the following happens:

If this is the profile's first product application, the applications array is added to the profile.
A new object for the product application is added to the applications array.
The value for the status field in the application object is APPLIED.

If the profile has multiple product applications, the easiest way to distinguish them is by seeing which product each product application is for. This information is contained in the object's product field.

Product application statuses in the API

The product application status determines whether you need to take action to grant or limit access to your product.

These are the possible statuses:

APPLIED: The profile is going through the onboarding tasks and should not have access to your product. Your smart policy can be configured to change the status to APPROVED or REJECTED automatically, known as Straight through processing or STP. If the smart policy cannot change the status automatically, you or a user must take action to progress the product application. For more information, see About manual action for the APPLIED and IN_REVIEW statuses.
REJECTED: The profile has not been approved to use your product, and should not have access to it. In most cases, the product application lifecycle is done, so no further action is required in Passfort. However, it is possible to revert this decision via a call to the API or the portal so that the status may become APPLIED again.
APPROVED: The profile has been approved to use your product, and should be granted access to it. No action is currently required in Passfort, but you should note that the product application status may become IN_REVIEW at any time because ongoing monitoring is happening in the background. Equally, if you have Risk configured and the product application's risk level is recalculated, the product application status will change to IN_REVIEW automatically if the new risk score is above the rejection threshold. It's also possible to manually put the product application IN_REVIEW. Additionally, it's possible to change the status to CANCELLED anytime via a call to the API or the portal.
CANCELLED: The profile is no longer approved to use your product, and access to it should be revoked. In most cases, the product application lifecycle is done, so no further action is required in Passfort. However, it is possible to revert this decision via a call to the API or the portal so that the status may change to IN_REVIEW.
IN_REVIEW: The profile's approval to use your product is being reviewed, so you may want to limit the profile's access to your product. Your smart policy can be configured to change the status to APPROVED or CANCELLED automatically. If the smart policy cannot change the status automatically, you or a user must take action to progress the product application. For more information, see About manual action for the APPLIED and IN_REVIEW statuses.

Listen to the Product status changed webhook to learn when the product application status changes.

The Product badge changed webhook also fires whenever the product application status changes.

About manual action for the `APPLIED` and `IN_REVIEW` statuses

When the status comes back as APPLIED or IN_REVIEW, there may be manual work to do.

Listen to the Manual action required webhook to get a notification whenever a product application needs manual work.

Examples of manual work include adding profile data, running a check to add information to the profile, and passing or failing a task.

This webhook payload tells you what's needed for the product application to progress. You can decide whether to take action or leave it to your users.

If the status has changed from REJECTED to APPLIED or changed from CANCELLED to IN_REVIEW, ongoing monitoring is canceled. You must manually run the PEPs and sanctions screening check or Sanctions and adverse media screening check to resume monitoring for new PEPs, sanctions, or adverse media results. Automated actions may be taking place while the status is APPLIED or IN_REVIEW, for example, when the smart policy is being applied or risk is being calculated. The Manual action required webhook does not send a notification for automated actions. If you want your users to take action, you may want to consider sending them a notification from your system to let them know when and what manual action is required. You may want the check results to influence the next manual action. To learn more, see Get the check result.

Learn which data is required from the Manual action required webhook

When the Manual action required webhook returns a payload with the UPDATE_RISK_SCORE_DATA or UPDATE_REQUIRED_DATAaction_type, you can find out what data is missing by making a call to the applications endpoint.

In the request body, include the profile ID (data.profile_id) and the product application ID (data.actions.applications.id) from the webhook payload.

The information returned in the body of the response depends on the action_type you received from the Manual action required webhook:

UPDATE_RISK_SCORE_DATA: When this is the action_type, the response from the endpoint has a risk.breakdown.missing_required_components key that indicates what data needs to be completed.
UPDATE_REQUIRED_DATA: When this is the action_type, the response from the endpoint has an approval_blockers.blocking_element.property key that indicates what data needs to be completed.

To get a list of all possible values for the risk.breakdown.missing_required_components and approval_blockers.blocking_element.property keys, see the Get a product application in the Passfort API reference.

We recommend listening to the Manual action required webhook to find out when data is required because it's more efficient than continuously polling the applications endpoint.

Request endpoint:

GET https://api.passfort.com/4.0/profiles/{profile_id}/applications/{application_id}

In this example, the Manual action required webhook returned the UPDATE_RISK_SCORE_DATA action_type. We can see that the profile is missing an email address because the value for risk.breakdown.missing_required_components is Email.

Sample response:

{
    "approval_blockers": [ … ],
    "assignments": [ ],
    "flag": "REQUIRES_DATA",
    "flag_history": [ … ],
    "hidden": false,
    "history": [ ... ],
    "id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
    "product": {
        "alias": "forexo_basic",
        "automatically_approve": false,
        "id": "a2e7545b-cb67-7a0e-7108-a444461891a9",
        "name": "Forexo Basic Account"
    },
    "required_tasks": [ ],
    "risk": {
        "breakdown": {
            "category_grouping": [ ],
            "components": [ ... ],
            "missing_required_components": [
                "Email"
            ]
        },
        "is_pending": false,
        "overall": {
            "level": "UNDETERMINED"
        },
        "risk_model": {
            "id": "ca37e39b-b075-0420-68d6-a217010dc685",
            "version": "1980-02-01 00:00:00"
        },
        "thresholds": { ... }
    },
    "status": "APPLIED"
}

In the following example, the Manual action required webhook returned the UPDATE_REQUIRED_DATA action_type. We can see that the profile is missing a country of address because the value for approval_blockers.blocking_element.property.type is ADDRESS_COUNTRY.

Sample response:

{
    "approval_blockers": [
        {
            "blocker_type": "UNDETERMINED_OUTCOME",
            "blocking_element": {
                "child_elements": { ... },
                "element_type": "BRANCH",
                "id": "cd37ca40-6f7a-45d1-a4cf-df66bcb6f583",
                "matcher": {
                    "include": [
                        "GBR"
                    ],
                    "type": "STRING_LIST_INCLUDES"
                },
                "name": "Is from UK?",
                "property": {
                    "type": "ADDRESS_COUNTRY"
                }
            }
        }
    ],
    "assignments": [ ],
    "flag": "REQUIRES_DATA",
    "flag_history": [ ... ],
    "hidden": false,
    "history": [ … ],
    "id": "1fa5b230-ff13-11e9-af09-26c2e3647646",
    "product": {
        "alias": "forexo_basic",
        "automatically_approve": false,
        "id": "0fa0a038-e048-11e9-8b30-7a2630ac864b",
        "name": "Forexo Basic Account"
    },
    "required_tasks": [ ],
    "status": "APPLIED"
}

Product application processing statuses

It's best practice to display the current processing state in your systems so your users know what's happening with the product application.

Every product application in the applications array has a flag field, which indicates what's currently happening to the product application or what needs to be done for the product application to progress to the next status.

The possible values for the flag field are listed here. Only one flag is returned for a product application. If multiple flags apply, the first applicable flag in this list is returned:

AUTOMATING: The smart policy is being applied. New tasks or task versions are being created for the product application. Any checks configured to run automatically are being run. Although manual action can be taken at this time, no manual action is required right now.
RECALCULATING_RISK: The product application’s total risk score is being calculated by checking the profile’s details against the risk factor rules in the product’s risk model. No manual action is required at this time.
REQUIRES_RISK_SCORE: Profile data is needed to calculate the score for a required risk factor. For the product application to progress, the missing profile data must be added to the profile, either by updating the profile's collected data or by running a check. These actions can be completed with a call to the API or via the portal. Note that if you're using the new smart policies, this flag is only returned when the product application reaches a smart policy branch that uses the risk score or risk level property and the risk model could not calculate a risk score or level for the product application.
REQUIRES_DATA: The smart policy doesn't have the data required to choose a branch in the policy. For example, if the branch rule is "Is the country of address one of 'United Kingdom' or 'Canada'?", the REQUIRES_DATA flag is returned if the profile doesn't have a country of address. Note that this flag is only returned if you're using the new smart policies.
WAITING_ON_COLLECTION_STEPS: A customer must provide more information or upload a document to run a check. This can happen during a customer request, which is used to send an email request directly from the profile, or during registration flows, which are used to gather information at the beginning of the customer's journey.
WAITING_ON_CHECKS: A check you chose to run via the API or a user chose to run via the portal is being performed. Although manual action can be taken at this time, no manual action is required right now. Note that if the smart policy is running checks automatically, the AUTOMATING flag is used instead of this one.
REQUIRES_MANUAL_TASK_COMPLETION: All automatic checks have been run by the smart policy, but one or more tasks are incomplete or failed. For the product application to progress, the incomplete tasks must be completed manually, or the product application must be rejected manually. These actions can be completed with a call to the API or via the portal.
WAITING_ON_ESCALATIONS: One or more escalation teams must approve the escalation before the product application can be manually approved. Note that product applications with escalations cannot be approved automatically by the smart policy.
READY_FOR_DECISION: All tasks are passed and the product application is ready to be approved. For the product application to progress, it must be approved manually. This can be done with a call to the API or via the portal.
DECIDED: The product application has been approved, canceled, or rejected. If the product application is approved, ongoing monitoring is happening. Otherwise, no action is taking place.
NEARING_EXPIRY: An approved product application has at least one task version that's due to expire in 30 days or less. Note that this flag is only returned when the product application status is APPROVED.

Listen to the Product badge changed webhook to get a notification whenever the flag changes.

The Product badge changed webhook also fires whenever the product status changes, so if you're listening to this webhook, you do not need to listen to the Product status changed webhook.

You may want the results of a check to influence the next manual action.

For example, take the Verify identity task that has two associated checks: Electronic identity check and ID verification.

Because an Electronic identity check typically has a higher pass rate than an ID verification check, you might want to configure your smart policy to run the Electronic identity check automatically, and then build your integration so the ID verification check is run via a call to the API whenever the Electronic identity check fails or returns an error.

To get check results whenever a check is run, use the Check completed webhook.

Users can run additional checks, so we recommend running a check via the API only once. We don't recommend using this webhook to sync the result of every check to your back office because this information is easy for users to see, with more detail, in Passfort.

Profile data sync

Profile data can change at any time during the product application lifecycle. This can happen in Passfort and it may also happen in your systems.

It's best practice to ensure all data in your systems and Passfort match. Learn how to sync profile data with your system data.

Risk level sync

If you're using Risk, you likely want to display it in your back office.

The risk level is always determined when the product application is first added to the profile.

It may also change during the product application lifecycle. The product application risk level is re-evaluated automatically whenever the profile's data is changed.

To get a notification when an product application's risk level is first determined or changes, use the Risk level changed webhook.

Example product applications array

To get a profile's product applications, make a request to the applications endpoint.

Request endpoint:

POST https://api.passfort.com/4.0/profiles/{profile_id}/applications

The response returns everything in the profile's applications array.

Product applications arrays return one object per product application. Each object has four key parts:

status: The current status of the product application.
flag: The current product application processing state. To learn more, see Displaying the application processing state.
product.alias: The alias of the product that the product application is for.
required_tasks: This array of objects contains one object for every task that must be passed for the product application to be approved. Note that this array of objects does not indicate which tasks have been passed or failed.

In this example, a profile has made a product application for a product called Forexo Basic Account. The profile needs to have their identity and address verified, which we can see in the required_tasks array of objects.

The product application is going through the onboarding process, which we can see with the APPLIED status, and you or a user will need to take action to progress the product application, which we can see with the REQUIRES_MANUAL_TASK_COMPLETION flag.

Sample response:

[
    {
        "approval_blockers": [ … ],
        "assignments": [ ],
        "flag": "REQUIRES_MANUAL_TASK_COMPLETION",
        "flag_history": [ … ],
        "hidden": false,
        "history": [ … ],
        "id": "ce008152-e051-11e9-a92a-6afffe0a6a0d",
        "product": {
            "alias": "forexo_basic",
            "automatically_approve": false,
            "id": "0fa0a038-e048-11e9-8b30-7a2630ac864b",
            "name": "Forexo Basic Account"
        },
        "required_tasks": [
            {
                "id": "eaa715de-e04f-11e9-b722-825bcb8d9a3c",
                "name": "Verify identity - Forexo",
                "task_type": "INDIVIDUAL_VERIFY_IDENTITY"
            },
            {
                "id": "ddaa97da-e04f-11e9-82f3-56e83fc47e90",
                "name": "Verify address - Forexo",
                "task_type": "INDIVIDUAL_VERIFY_ADDRESS"
            }
        ],
        "status": "APPLIED"
    }
]

Additional information

In this section:

profiles