Manage product applications (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 key 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 a separate call to add a product application.

If you create a profile without any applications, it automatically applies to any products with 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, 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 status field of 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 value.

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.

Webhook: Product status changed

To enable this webhook, turn on the Product status changed event.

This webhook sends a callback whenever the product status on an application changes.

Callbacks from this webhook callback have four key parts:

  • new_status: This field contains the new status of the application.
  • data.product.alias: This field contains the alias of the product which the application is for.
  • data.profile_id: This field contains the ID of the profile that made the application.
  • user: This object contains details of the user who changed the status. If the smart policy changed the status, the value is null.

In this example, a callback was sent because a user, Morgan Rose, manually cancelled a profile's application for a product called Forexo Basic Account.

Sample callback:

{
"id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
"event": "PRODUCT_STATUS_CHANGED",
"secret": "yourSecret",
"timestamp": 1568997222,
"data": {
"apikey": {
"name": "KEY_NAME"
},
"application_id": "b0ce7c17-2cab-86e7-9a83-ebee0d4d5dc8",
"customer_ref": null,
"new_status": "CANCELLED",
"product": {
"alias": "forexo_basic",
"id": "edc23993-eb6a-9d89-bb79-5b8925b33224",
"name": "Forexo Basic Account"
},
"profile_id": "a2c4393a-e219-67a4-5ab4-2186952e9038",
"user": {
"email": "morgan.rose@forexo.com",
"id": "ec1565b6-82c7-0577-8b3a-94462b67c97a",
"name": "Morgan Rose"
}
}
}

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. This webhook callback also tells you what the work is, so you can decide if you want 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, 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.
You may want check results to influence the next manual action. To learn more, see Getting check results.
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.
Webhook: Manual action required

To enable this webhook, turn on the Manual action required event when you configure webhooks.

This webhook sends a callback in the following circumstances:

  • The smart policy has completed all automated processes, and tasks need to be completed manually or the application needs to be decided (approved, rejected, cancelled) manually.
  • A task is passed or failed manually, and more tasks need to be completed manually or the application needs to be decided manually.
  • The application is decided, and no manual actions are required.
A new callback is triggered every time a task is completed on an application that still has more incomplete tasks.

Callbacks from this webhook callback have six key parts:

  • data.profile_id: This field contains the ID of the profile that made the application.
  • data.actions: This is an array of objects where each object corresponds to a manual action required for the application to be approved. When one or more tasks on an application are incomplete, the array has one object for each incomplete task. When all tasks are passed and the application needs to be decided manually, the array has one object for the incomplete application. When the application has been decided and there are no manual actions left, the callback returns an empty array.
  • data.actions.action_type: This field indicates which manual action required. When a task needs to be completed, the value is COMPLETE_REQUIRED_TASK. When the application needs to be decided, the value is REVIEW_APPLICATION.
  • data.actions.product.alias: This field contains the alias of the product which the application is for.
  • data.actions.task.variant.alias: This field contains the alias of the task that requires action.
  • data.actions.task.state: This field contains the state of the task that requires action.

In this first example, an application for a product called Forexo Basic Account is currently in the APPLIED state and needs to have a task completed before it can be approved. We can see that the task that needs to be completed has the verify_address alias. We know that it's the only task that needs to be completed right now because it's the only object in the actions array.

Sample callback:

{
"id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
"event": "MANUAL_ACTION_REQUIRED",
"secret": "yourSecret",
"timestamp": 1569417715,
"data": {
"actions": [
{
"action_type": "COMPLETE_REQUIRED_TASK",
"applications": [
{
"id": "edc23993-eb6a-9d89-bb79-5b8925b33224",
"product": {
"alias": "forexo_basic",
"id": "b0ce7c17-2cab-86e7-9a83-ebee0d4d5dc8",
"name": "Forexo Basic Account"
},
"status": "APPLIED"
}
],
"due": "NOW",
"task": {
"id": "72aadb55-8b02-8495-d6b0-e1627ec23612",
"state": "INCOMPLETE",
"type": "INDIVIDUAL_VERIFY_ADDRESS",
"variant": {
"alias": "verify_address",
"id": "5562c4e4-4d12-b16a-a151-7c9eed6816e9",
"name": null
}
}
}
],
"customer_ref": null,
"profile_id": "a2c4393a-e219-67a4-5ab4-2186952e9038"
}
}

In this next example, the outstanding task on the application above has been passed and now the application needs to be approved or rejected manually.

Sample callback:

{
"id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
"event": "MANUAL_ACTION_REQUIRED",
"secret": "yourSecret",
"timestamp": 1569499655,
"data": {
"actions": [
{
"action_type": "REVIEW_APPLICATION",
"application": {
"id": "edc23993-eb6a-9d89-bb79-5b8925b33224",
"product": {
"alias": "forexo_basic",
"id": "b0ce7c17-2cab-86e7-9a83-ebee0d4d5dc8",
"name": "Forexo Basic Account"
},
"status": "APPLIED"
},
"due": "NOW"
}
],
"customer_ref": null,
"profile_id": "a2c4393a-e219-67a4-5ab4-2186952e9038"
}
}

In this last example, the application above has been decided and no manual actions are left.

Sample callback:

{
"id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
"event": "MANUAL_ACTION_REQUIRED",
"secret": "yourSecret",
"timestamp": 1569499659,
"data": {
"actions": [ ],
"customer_ref": null,
"profile_id": "a2c4393a-e219-67a4-5ab4-2186952e9038"
}
}

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 this flag is only returned if you're using the older version of smart policies.
  6. 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.
  7. 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.
  8. 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.

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.

Webhook: Product badge changed

To enable this webhook, turn on the Product status changed event when you configure webhooks.

This webhook sends a callback whenever an application flag changes.

Callbacks from this webhook callback have five key parts:

  • new_flag: This field contains the new application flag.
  • new_status: This field contains the status of the application. Note that it may not have changed since the flag was last updated.
  • data.product.alias: This field contains the alias of the product which the application is for.
  • data.profile_id: This field contains the ID of the profile that made the application.
  • user: This object contains details of the user who changed the status. If the smart policy changed the status, the value is null.

In this example, the callback was sent because a user, Morgan Rose, manually added a new product application for a product called Forexo Basic Account to a profile. We can tell it's a new application because the new_status is APPLIED, and we can tell that the smart policy is being applied because the new_flag is AUTOMATING.

Sample callback:

{
"id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
"event": "PRODUCT_BADGE_CHANGED",
"secret": "yourSecret",
"timestamp": 1569503987,
"data": {
"apikey": {
"name": "KEY_NAME"
},
"application_id": "edc23993-eb6a-9d89-bb79-5b8925b33224",
"customer_ref": null,
"new_flag": "AUTOMATING",
"new_status": "APPLIED",
"product": {
"alias": "forexo_basic",
"id": "b0ce7c17-2cab-86e7-9a83-ebee0d4d5dc8",
"name": "Forexo Basic Account"
},
"profile_id": "4f434848-e060-11e9-8fea-12bd74fbd3fc",
"user": {
"email": "morgan.rose@forexo.com",
"id": "ec1565b6-82c7-0577-8b3a-94462b67c97a",
"name": "Morgan Rose"
}
}
}

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.
Webhook: Check completed

To enable this webhook, turn on the Check completed event when you configure webhooks.

This webhook sends a callback whenever results are returned from a check.

Callbacks from this webhook callback have three key parts:

  • data.check.check_type: This field indicates what kind of check was run. To learn about the different check types, see What are PassFort's checks?
  • data.check.variant.alias: This field contains the alias for the check variant.
  • data.check.result: This field indicates the result of the check (e.g. Pass, Fail, Error). The possible results for a check depends on the data provider and configuration options used for the check variant. To get the possible results, see the configuration article for your data provider.

In this example, a variant of the Electronic identity check was run on an application and it failed.

Sample callback:

{
"id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
"event": "CHECK_COMPLETED",
"secret": "yourSecret",
"timestamp": 1569509539,
"data": {
"check": {
"check_type": "IDENTITY_CHECK",
"id": "ea565b55-47d9-1858-4588-3a22a3838707",
"result": "Fail",
"variant": {
"alias": "onfido_identity_check",
"id": "ea70ade9-3de3-1785-203b-68044cd3ecbb",
"name": "Onfido"
}
},
"customer_ref": null,
"profile_id": "4f434848-e060-11e9-8fea-12bd74fbd3fc"
}
}

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.

Webhook: Risk level changed

To enable this webhook, turn on the Risk level changed event when you configure webhooks.

Callbacks from this webhook callback have four key parts:

  • data.old_category: This field contains the application's risk level before it was changed.
  • data.new_category: This field contains the application's risk level after it was changed.
  • data.product.alias: This field contains the alias of the product which the application is for.
  • data.profile_id: This field contains the ID of the profile that made the application.

In this example, an application for a product called Forexo Basic had an Undetermined risk level that changed to a Low risk level.

Sample callback:

{
"id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
"event": "RISK_LEVEL_CHANGED",
"secret": "yourSecret",
"timestamp": 1569244762,
"data": {
"application_id": "b0ce7c17-2cab-86e7-9a83-ebee0d4d5dc8",
"customer_ref": null,
"new_category": "LOW",
"old_category": "UNDETERMINED",
"product": {
"alias": null,
"id": "edc23993-eb6a-9d89-bb79-5b8925b33224",
"name": "Forexo Basic Account"
},
"profile_id": "a2c4393a-e219-67a4-5ab4-2186952e9038"
}
}

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:

  • status: This field contains the current status of the application. To learn more, see Tracking the status.
  • flag: This field contains the current application processing state. To learn more, see Displaying the application processing state.
  • product.alias: This field contains the alias of the product which the application is for.
  • required_tasks: This array of objects contains one object for every task that will need to be passed for the application to be approved. Note that this array of objects does not indicate which tasks have been passed or failed. To learn when a task requires manual action, see Handling manual action for the APPLIED and IN_REVIEW status.

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