Manage the product application lifecycle (API)

In PassFort, the individuals and companies applying for your products are called profiles. Profiles make product applications to see if they qualify for your products.

What is the product application lifecycle?

The process of determining whether a profile is approved to use your products is called onboarding. It begins as soon as an application is added to a profile.

During the onboarding process, a series of due diligence tasks are added to the application.

The purpose of the tasks is to ensure the profile intends to use your product for legitimate purposes. Examples of tasks include verifying the profile's identity, verifying the profile's bank account, and assessing whether the profile has any sanctions.

For an application to be approved, the profile must pass all the tasks for it.

If you're using PassFort's optional Risk module, you can configure the smart policy to add tasks based on how much risk the profile's application poses to your company. Typically, a higher risk level means that the profile will need to pass more tasks for their application to be approved.

If the profile is approved to use your product, the application moves into the monitoring process.

During the monitoring process, the application is continually reviewed to ensure the profile still meets the requirements of the due diligence tasks.

If, at any time, the profile no longer meets the requirements of a task, or if a new task is added to the application, the application goes into review.

Applications that are in review need to have their incomplete tasks passed before they can be approved again. If the application is approved again, it goes back into monitoring.

If an application is not approved

If the profile does not pass the onboarding tasks, their application is rejected. This means the profile should not be granted access to your product.

If the application is initially approved, but it goes into review and the profile doesn't pass the incomplete tasks, the application is cancelled. This means the profile should no longer have access to your product.

If the application is rejected or cancelled, this is the end of the lifecycle in most cases. However, it is possible to manually revert either decision. If a decision to reject an application is reverted, the application goes back to the onboarding process. If a decision to cancel an application is reverted, the application goes into review. Either way, the profile will need to pass any failed or incomplete tasks before their application can be approved.

How is the lifecycle tracked in the API?

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

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

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

Managing a product application through its lifecycle

Starting the product application process

To start the process, create a profile and add a product application to it.

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

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

If you create a profile without any applications, it automatically applies to any products that have the auto_apply attribute. To see if a product has this attribute, log 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. To remove this attribute from a product, contact us.

When you add a new application, the following happens:

  • If this is the profile's first application, the applications array is added to the profile.
  • A new object for the application is added to the applications array.
  • The value for the status field in the application object is APPLIED.
If the profile has multiple applications, the easiest way to distinguish them is by seeing which product each application is for. This information is contained in the object's product field.

Tracking the status

The status of the application determines whether you might 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 (which is known as Straight through processing or STP). If the smart policy cannot change the status automatically, you or a user will need to take action to progress the application. For more information, see Handling 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 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 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 application's risk level is recalculated, the application status will change to IN_REVIEW automatically if the new risk score is above the rejection threshold. Additionally, it's possible to change the status to CANCELLED at any time 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 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 REJECTED automatically. If the smart policy cannot change the status automatically, you or a user will need to take action to progress the application. For more information, see Handling manual action for the APPLIED and IN_REVIEW statuses.

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

Handling 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 an application needs manual work.

Examples of manual work include adding profile data, running a check to add information to the profile (e.g. a Company registry check), and passing/failing a task.

This webhook callback tells you what's needed for the application to progress. You can decide if you want to take the 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 cancelled. 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 (e.g. 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 check results to influence the next manual action. To learn more, see Getting check results.
Learn which data is required

When the Manual action required webhook returns a callback with the UPDATE_RISK_SCORE_DATA or UPDATE_REQUIRED_DATA action_type, you can find out what data is missing by making a call to the endpoint below.

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

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 below 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 below 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 API Resources for Get a product application.

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

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 next 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"
}

Displaying the application processing state

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

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

The flag field can have these values:

  1. AUTOMATING: The smart policy is being applied. New tasks or task versions are being created for the 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.
  2. NEARING_EXPIRY: An approved 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 application status is APPROVED.
  3. DECIDED: The application has been approved, cancelled, or rejected. If the application is approved, ongoing monitoring is happening. Otherwise, no action is taking place.
  4. RECALCULATING_RISK: The 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.
  5. REQUIRES_RISK_SCORE: Profile data is needed to calculate the score for a required risk factor. For the 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 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 application.
  6. 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.
  7. 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.
  8. 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 application to progress, the incomplete tasks must be completed manually or the application must be rejected manually. These actions can be completed with a call to the API or via the portal.
  9. READY_FOR_DECISION: All tasks are passed and the application is ready to be approved. For the application to progress, it must be approved manually. This can be done with a call to the API or via the portal.
  10. WAITING_ON_ESCALATIONS: One or more escalation teams need to approve the escalation before the application can be approved manually. Note that applications with escalations cannot be approved automatically by the smart policy.

Only one flag is returned for an application. If multiple flags apply, the first applicable flag in the order above is returned.

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

Getting check results

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 are able to 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.

Syncing profile data

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

It's best practice to make sure all data in your systems and in PassFort matches. Learn how to sync profile data with your system data.

Syncing risk levels

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

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

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

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

Example applications array

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

Request endpoint:

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

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

Applications arrays return one object per application. Each object has four key parts:

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

The 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 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"
}
]


How did we do?


Powered by HelpDocs (opens in a new tab)