Create a profile for an associate and link it to a company using the API
This developer guide takes you through the steps to create profiles for company associates in the Passfort API 4.0.
About due diligence on associates
When a company applies to one of your products, you may wish to perform due diligence on associates, for example, officers, owners, shareholders, trustees, and authorized persons, before you approve the company's product application.
You can use any of the following company tasks to perform due diligence on associates:
Identify officers
COMPANY_IDENTIFY_OFFICERS: Verify and approve key decision-makers at the board level, like directors and company secretaries.Identify shareholders
COMPANY_IDENTIFY_BENEFICIAL_OWNERS: Verify and approve the company's shareholders and beneficial owners with significant voting rights and control.Identify trustees
COMPANY_IDENTIFY_TRUSTEES: Verify and approve the charity's key decision-makers at the board level, like chairs and secretaries.Identify authorized persons
COMPANY_IDENTIFY_AUTHORISED_PERSONS: Verify and approve the individuals who are authorized to purchase and, where relevant, use the product on behalf of the company.Assess company ownership
COMPANY_ASSESS_OWNERSHIP: Verify and approve associates that play either a direct or indirect role in an onboarded company's ownership.
When configuring these tasks, you should specify which product associates will apply to. This determines which due diligence tasks associates need to pass before they can be approved for the company's task.
To onboard an associate, first create their profile, then link it to the company.
When you link the associate's profile, specify which tasks the associate is being verified for. The appropriate product application will be added to the associate's profile so due diligence can begin.
Associates that are companies can have their own due diligence tasks to verify their associates. Likewise, any of those associates that are companies can have their own tasks to verify their associates, and so on.
If you reject or cancel a company's product application, you should reject/cancel the product applications for the related associates too. If you don't, the associates' profiles will stay in ongoing monitoring.
To learn more about the product application lifecycle, see How the product application lifecycle is tracked in the API.
Possible associate roles for company tasks
Each company task type is used to verify associates with specific roles on their product applications.
For example, the COMPANY_ASSESS_OWNERSHIP task type can be used to verify associates with a BENEFICIAL_OWNER, CONTROLLING_SHAREHOLDER, or GLOBAL_ULTIMATE_OWNER role on their product application.
If you have enabled Automatic addition to the verification list for the task, associates added to the profile's collected data, or returned by checks, are automatically added to the verification list based on your specified criteria. If you have disabled this option, you must explicitly add any associates you wish to investigate further onto the verification list.
The possible associate roles for each company task are as follows.
Company task | Possible associate roles |
|---|---|
|
|
|
|
|
|
|
|
|
|
Before you begin
To avoid potential errors, you should ensure your policy is configured correctly.
Ensure the tasks are configured correctly
If an associate profile does not have the right product application for a task, you may encounter the following error:
When you view the Identify authorized persons task in the portal, associates will not be displayed at all; however, you will be able to see the associates by going to .
We recommend enabling associates to be added to the task verification list automatically to simplify the integration.
To see if this configuration option is enabled, go to and follow these steps for the Identify officers, Identify shareholders, Identify trustees, Assess company ownership and Identify authorized persons tasks:
Go to the Tasks section and select the task name.
Confirm the Product for which associated profiles will apply option is set to the desired product.
Confirm the Automatic addition to the verification list option is set to Add all profiles or Add up to a specific number of profiles. If so, the option is enabled.
To update your configuration, contact us.
If you're using checks for these tasks, the automatic addition to the verification list option also determines which are added to the verification list automatically. If you do not want to use the configuration option, follow these steps.
Ensure the product is configured correctly
If you want to onboard associates who are individuals, your product should have a smart policy for individuals or a task set for individuals. If not, an error will be returned when you try to create the associate profile.
Additionally, if you're using Risk and you have a product for associates that's different from the product for the parent company, the same companies risk model must be used on both products and, equally, the same individuals risk model must be used on both products. Otherwise, the risk may not be calculated correctly.
To see if your product has a smart policy or task set for individuals:
Go to .
Select your product.
If you're using the new smart policies the Profiles will use the flow chart smart policy for this product checkbox is selected, ensure there is a smart policy under . If you're not, ensure there is a task set under .
If you're using Risk and you have a separate product for associates, take note of the risk models on the company product, and , and ensure they match the risk models for the associate product.
To update your configuration, contact us.
Disable the automatic addition of an associate
By default, any associates you create through the portal will be added to the verification list so their onboarding can begin.
In the portal, the first panel lists associates which have been added to the verification list.
The other panel lists candidates for the verification list that have been returned by checks or added through the API. You can use the API to add a candidate or to add associates to the verification list. Or you can request that Passfort add candidates in order to let your users choose which ones should be moved to the verification list for onboarding.
This configuration is not available for the Identify authorized persons task, which doesn't have a left side.
If you would like associates to be displayed on the left side of the task, we'll make the following changes to your configuration:
Create a duplicate of the associate task and add it to the product you use to onboard companies.
Create a new product that automatically approves all profiles that apply to it. This product does not do anything else.
On the duplicate associate task:
Set the option to the product that automatically approves all profiles.
Set the Criteria for automatic addition to the verification list option to .
Set the Policy for automatic task completion option to .
On the normal associate task, set the Criteria for automatic addition to the verification list option to .
When this configuration is enabled, users will see both versions of the task.
Whenever you create a profile for an associate, they'll be added to the verification list of the auto-approve task, then copied to the left side of the normal task automatically.
Users can then use the normal task to view associates on the left and move them to the verification list.
The auto-approve task will be displayed as Passed as soon as you add an associate. Users should avoid using this task.
Because automatic addition to the verification list is enabled on the auto-approve task, you do not need to send the product applications array when you create the profile.
If you have duplicate tasks - one with automatic addition to the verification list and one without:
The task without automatic addition displays under a heading called [Associate type] from '[name of automatic addition task]' verification list, for example, Shareholders from the Identify shareholders verification list.
The task with automatic addition displays associates on the verification list.
Note that before automation has finished running, for both tasks, associates are displayed on the verification lists with No application.
Create the associate profile and get its ID
To create a profile for the associate, make a request to the following endpoint.
Take note of the id in the response. You'll need the id for the next step.
Request:
POST https://api.passfort.com/4.0/profiles
Body parameters:
When you make the POST request, include the following parameters in the body.
Key | Value | Description |
|---|---|---|
*Required string |
| The profile's type. For associates who are individuals, the value should be For associates who are companies, the value should be |
*Required any (EntityData) | See the following sample request body for a sample value. | An object that contains basic profile information, like the individual’s or company's name. For the full list of parameters, you can pass in |
If you have the Automatic addition to the verification list option enabled, you should not send the applications array of objects in the request. The correct product application will be added to the associate profile automatically when you link the associate profile to the company profile in Link the associate profile to the company profile.
In this example, we'll create an associate who's an individual named Nayab Ali Khan.
This sample assumes the Automatic addition to the verification list option is enabled, so it does not include the associate's product application and role in the request.
Sample request body:
{
"role": "INDIVIDUAL_ASSOCIATED",
"collected_data": {
"entity_type": "INDIVIDUAL",
"personal_details": {
"name": {
"given_names": [
"Nayab"
],
"family_name": "Ali Khan"
}
}
}
}Sample response:
{
"applications": [ ],
"category": "INACTIVE_APPLICANT",
"checks": [ ],
"collected_data": {
"entity_type": "INDIVIDUAL",
"personal_details": {
"name": {
"family_name": "Ali Khan",
"given_names": [
"Nayab"
]
}
}
},
"collection_steps": [ ],
"creation_date": "2020-02-27 15:00:18",
"display_name": "Nayab Ali Khan",
"document_images": [ ],
"events": [ ],
"has_associates": false,
"has_collection_steps": false,
"id": "a37764c1-134b-8c85-9527-7a9327ed9071",
"linked_to": [ ],
"role": "INDIVIDUAL_ASSOCIATED",
"root_id": "5d90cbd1-d872-28a6-86ed-cb4c7778c25a",
"status": "NORMAL",
"tags": [ ],
"task_progress": {
"completed_count": 0,
"total_count": 0
},
"task_types": [ ],
"tasks": [ ],
"unresolved_event_types": [ ]
}Select the company profile
Choose which company profile you'll link the associate to.
Get the ID number of the company's profile, for example, a2e7545b-cb67-7a0e-7108-a444461891a9. You'll need it to make the request to get its collected data in the next step.
If you haven't created the profile yet, follow the steps to create a company profile and add a product application. The id is returned in the response.
Link the associate profile to the company profile
To link the associate to the company, update the company’s collected_data with the associate's information.
First get the company's existing collected data, then modify it and pass the modified data back to the company.
Get the company's existing collected data
Use the company's profile id that you used in Create the associate profile and get its ID to make a request to the following endpoint.
The response returns everything that currently exists in the profile's collected_data.
Request:
GET https://api.passfort.com/4.0/profiles/{profile_id}/collected_dataSample response:
{
"entity_type": "COMPANY",
"metadata": {
"country_of_incorporation": "GBR",
"name": "AERIAL TRADERS",
"number": "09565115",
"structured_company_type": { }
}
}Copy the entire response so you have it for the next step.
Also copy the ETag from the response header.
It's important to copy the entire response body because, in the next step, you must send everything you want to keep in collected_data. It's not possible to use the request to update specific fields.
Modify the company's collected data
Take the response you copied and add the associate's information to the objects that correspond to their roles at the company.
At a minimum, you must pass the following information in each object:
entity_type: Whether the associate is anINDIVIDUALor aCOMPANY.id: The ID for the associate's profile, which you copied in Create the associate profile and get its ID.
The possible objects and their required parameters are as follows.
There are additional optional fields you can add to each object to store granular information like the associate's appointed date or share amount. For a complete list of optional fields, see the documentation for Create a profile in Passfort's API reference.
Officers object
Use the officers object when the associated_role is any of the following:
COMPANY_SECRETARYDIRECTORPARTNEROTHERRESIGNED_OFFICERTRUSTEE
These are the required parameters for the object.
Key | Value | Description |
|---|---|---|
*Required object | For a sample, see the sample request body in Send the modified data. | An object that lists the individuals who are officers of the company or charity. |
Optional array of objects | For a sample, see the sample request body in Send the modified data. | This determines where the associate is displayed in the company structure. You can place the associate in more than one of these. |
*Required string |
| Whether the director is an individual or a company. |
*Required object | For a sample, see the sample request body in Send the modified data. | An object that contains the ID of the associate profile. |
*Required string | Sample value:
| The unique identifier for the associate's profile. |
Optional array of objects | For a sample, see the description for Update collected data. | This determines where the associate is displayed in the company structure. You can place the associate in more than one of these. |
*Required string |
| Whether the director is an individual or a company. |
*Required object | For a sample, see the description for Update collected data. | An object that contains the ID of the associate profile. |
*Required string | Sample value:
| The unique identifier for the associate's profile. |
Optional array of objects | For a sample, see the description for Update collected data. | This determines where the associate is displayed in the company structure. You can place the associate in more than one of these. |
*Required string |
| Whether the director is an individual or a company. |
*Required object | For a sample, see the description for Update collected data. | An object that contains the ID of the associate profile. |
*Required string | Sample value:
| The unique identifier for the associate's profile. |
Optional array of objects | For a sample, see the description for Update collected data. | This determines where the associate is displayed in the company structure. You can place the associate in more than one of these. |
*Required string |
| Whether the director is an individual or a company. |
*Required object | For a sample, see the description for Update collected data. | An object that contains the ID of the associate profile. |
*Required string | Sample value:
| The unique identifier for the associate's profile. |
Optional array of objects | For a sample, see the description for Update collected data. | This determines where the associate is displayed in the company structure. You can place the associate in more than one of these. |
*Required string |
| Whether the director is an individual or a company. |
*Required object | For a sample, see the description for Update collected data. | An object that contains the ID of the associate's profile. |
*Required string | Sample value:
| The unique identifier for the associate's profile. |
Optional array of objects | For a sample, see the description for Update collected data. | This determines where the associate is displayed in the company structure. You can place the associate in more than one of these. |
*Required string |
| Whether the director is an individual or a company. |
*Required object | For a sample, see the description for Update collected data. | An object that contains the ID of the associate profile. |
*Required string | Sample value:
| The unique identifier for the associate's profile. |
Authorized persons object
Use the authorized_persons object when the associated_role is AUTHORIZED_PERSON.
These are the required parameters for the object.
Note that if you add an authorized person with past tenure dates through the API, they will be considered a former authorized person and will not be added to the verification list.
Key | Value | Description |
|---|---|---|
*Required array of objects | For a sample, see the description for Update collected data. | An object that lists the individuals who are authorized to purchase and, where relevant, use the product on behalf of the company. |
*Required string |
| Whether the associate is an individual or a company. |
*Required object | For a sample, see the description for Update collected data. | An object that contains the ID of the associate's profile. |
*Required string | Sample value:
| The ID of the associate's profile. |
Ownership structure object
Use the ownership_structure object when the associated_role is GLOBAL_ULTIMATE_OWNER, BENEFICIAL_OWNER, CONTROLLING_SHAREHOLDER , or SHAREHOLDER.
These are the required parameters for the object.
Key | Value | Description |
|---|---|---|
*Required object | For a sample, see the sample request body in Send the modified data. | An object that lists the individuals and companies who are global ultimate owners, beneficial owners, controlling shareholders, and/or shareholders. |
Optional array of objects | For a sample, see the sample request body in Send the modified data. | This object lists the individuals and companies who are beneficial owners, meaning they own or control more than 25% of the company's shares or voting rights, or otherwise exercise control over the company or its management. |
*Required string |
| Whether the beneficial owner is an individual or a company. |
*Required object | For a sample, see the sample request body in Send the modified data. | An object that contains the ID of the associate's profile. |
*Required string | Sample value:
| The unique identifier for the associate's profile. |
Optional array of objects | This object lists the individuals and companies defined as having a controlling threshold of share ownership in the company. | |
*Required string |
| Whether the controlling shareholder is an individual or a company. |
*Required object | An object that contains the ID of the associate's profile. | |
*Required string | Sample value:
| The unique identifier for the associate's profile. |
Optional array of objects | This object lists the individuals and companies defined as being the global ultimate owners of the company. | |
*Required string |
| Whether the global ultimate owner is an individual or a company. |
*Required object | An object that contains the ID of the associate's profile. | |
*Required string | Sample value:
| The unique identifier for the associate's profile. |
Optional array of objects | This object details the share classes owned by the shareholders. | |
*Required string | Sample value:
| The share class name. |
ownership_structure can also detail the quantity and/or percentage of each share class an associate owns.
Send the modified data
Use the following request to post the collected_data you modified back to the company's profile.
In the request header, send a parameter called If-Match with the value of the ETag you copied when you got the company's existing collected data.
In the example, we'll link the profile for the associate named Nayab Ali Khan, which we created in Select the company profile.
Nayab Ali Khan is both a director and a beneficial owner of the company, so we'll add their details to the officers object and the ownership_structure object.
Request:
POST https://api.passfort.com/4.0/profiles/{profile_id}/collected_dataBody parameters:
For the body parameters for the POST request, see Modify the company's collected data.
Sample request body:
{
"entity_type": "COMPANY",
"metadata": {
"country_of_incorporation": "GBR",
"name": "AERIAL TRADERS",
"number": "09565115",
"structured_company_type": { }
},
"officers": {
"directors": [
{
"entity_type": "INDIVIDUAL",
"linked_profile": {
"id": "a37764c1-134b-8c85-9527-7a9327ed9071"
}
}
]
},
"ownership_structure": {
"beneficial_owners": [
{
"entity_type": "INDIVIDUAL",
"linked_profile": {
"id": "a37764c1-134b-8c85-9527-7a9327ed9071"
}
}
]
}
}Sample response:
{
"entity_type": "COMPANY",
"metadata": {
"country_of_incorporation": "GBR",
"name": "AERIAL TRADERS",
"number": "09565115",
"structured_company_type": { }
},
"officers": {
"directors": [
{
"entity_type": "INDIVIDUAL",
"linked_profile": {
"applications": [
{
"approval_blockers": [ … ],
"assignments": [ ],
"associated_role": "DIRECTOR",
"flag": "REQUIRES_MANUAL_TASK_COMPLETION",
"flag_history": [ … ],
"hidden": false,
"history": [ … ],
"id": "b125a317-002d-4109-7551-242d9d7519ad",
"product": {
"alias": "forexo_pro_associates",
"automatically_approve": false,
"id": "4ed3796b-9a43-4dd4-e969-cae676e6705a",
"name": "Forexo Pro Associates"
},
"required_tasks": [
{
"id": "bdb87a86-bd8d-6d83-b976-e114959a38d9",
"name": "Identify officers",
"task_type": "COMPANY_IDENTIFY_OFFICERS"
},
{
"id": "913c68e8-c246-463d-b59b-78c4444647b9",
"name": "Identify shareholders",
"task_type": "COMPANY_IDENTIFY_BENEFICIAL_OWNERS"
}
],
"status": "APPLIED"
},
{
"approval_blockers": [ … ],
"assignments": [ ],
"associated_role": "BENEFICIAL_OWNER",
"flag": "REQUIRES_MANUAL_TASK_COMPLETION",
"flag_history": [ … ],
"hidden": false,
"history": [ … ],
"id": "b35074de-3dd2-651d-1d65-c33e5e3d0238",
"product": {
"alias": "forexo_pro_associates",
"automatically_approve": false,
"id": "4ed3796b-9a43-4dd4-e969-cae676e6705a",
"name": "Forexo Pro Associates"
},
"required_tasks": [
{
"id": "bdb87a86-bd8d-6d83-b976-e114959a38d9",
"name": "Identify officers",
"task_type": "COMPANY_IDENTIFY_OFFICERS"
},
{
"id": "913c68e8-c246-463d-b59b-78c4444647b9",
"name": "Identify shareholders",
"task_type": "COMPANY_IDENTIFY_BENEFICIAL_OWNERS"
}
],
"status": "APPLIED"
}
],
"category": "APPLICANT",
"collected_data": { … },
"display_name": "Nayab Ali Khan",
"has_associates": false,
"has_collection_steps": false,
"id": "a37764c1-134b-8c85-9527-7a9327ed9071",
"role": "INDIVIDUAL_ASSOCIATED",
"status": "NORMAL",
"tags": [ ],
"task_progress": { ... },
"tasks": [ ... ],
"unresolved_event_types": [ ]
},
"merged_resolver_ids": [ ],
"resolver_id": "a52cdc09-c428-3ada-3e20-7a21062e698d",
"task_variant_ids": [ … ]
}
]
},
"ownership_structure": {
"beneficial_owners": [
{
"entity_type": "INDIVIDUAL",
"linked_profile": {
"applications": [ … ],
"category": "APPLICANT",
"collected_data": { … },
"display_name": "Nayab Ali Khan",
"has_associates": false,
"has_collection_steps": false,
"id": "a37764c1-134b-8c85-9527-7a9327ed9071",
"role": "INDIVIDUAL_ASSOCIATED",
"status": "NORMAL",
"tags": [ ],
"task_progress": { … },
"tasks": [ ... ],
"unresolved_event_types": [ ]
},
"merged_resolver_ids": [ ],
"resolver_id": "a52cdc09-c428-3ada-3e20-7a21062e698d",
"task_variant_ids": [ … ]
}
]
}
}We can see in the response that when the associate profile is created, there are some important parts added to the profile automatically:
applications: An array of objects containing the associate's applications to the ensure the tasks are configured correctly.tasks: An object containing a list of the due diligence tasks that the associate needs to pass before their product applications can be approved. Each task only needs to be passed or failed once, even when it's shared across multiple product applications. In this example, the individual will need to have their identity and address verified before their product application as a director and their product application as a beneficial owner can be approved.
When you first create an associate profile, applications and tasks will likely not be returned immediately. This can happen for a number of reasons. For example, the product application's risk level may still be calculating, or the smart policy may require more profile data to continue.
If the associate profile has a product application, the applications.flag field contains the current state of the product application.
If you don't want associates to be added to the verification list automatically
If you don't want to use the option to add associates to the verification list automatically, you need to specify which associates should be explicitly added to the verification list.
The task_variant_ids field is present on each associate and stores the list of task variant IDs for this associate.
An associate can belong to one or more verification lists. The verification lists are determined by the task variant IDs field.
When adding the associate to the parent profile, your request should appear as follows:
Sample request body:
{
"entity_type": "COMPANY",
"metadata": {
"country_of_incorporation": "GBR",
"name": "AERIAL TRADERS",
"number": "09565115",
"structured_company_type": { }
},
"officers": {
"directors": [
{
"entity_type": "INDIVIDUAL",
"linked_profile": {
"id": "a37764c1-134b-8c85-9527-7a9327ed9071"
},
"task_variant_ids": ["bdb87a86-bd8d-6d83-b976-e114959a38d9"]
}
]
},
"ownership_structure": {
"beneficial_owners": [
{
"entity_type": "INDIVIDUAL",
"linked_profile": {
"id": "a37764c1-134b-8c85-9527-7a9327ed9071"
},
"task_variant_ids": ["913c68e8-c246-463d-b59b-78c4444647b9"]
}
]
}
}Note that the task variant IDs shown here are examples only and will need to be replaced with IDs specific to your institution.
Get the task variant ID
Make a request to the following endpoint, using the company profile ID.
Request endpoint:
GET https://api.passfort.com/4.0/profiles/{profile_id}Sample response:
{
"applications": [
{
"approval_blockers": [ ... ],
"assignments": [ ],
"flag": "REQUIRES_MANUAL_TASK_COMPLETION",
"flag_history": [ … ],
"hidden": false,
"history": [ … ],
"id": "a2e7545b-cb67-7a0e-7108-a444461891a9",
"product": {
"alias": "forexo_pro",
"automatically_approve": false,
"id": "379ec33c-5650-1c13-6288-e0369515b949",
"name": "Forexo Pro Account"
},
"required_tasks": [
{
"alias": "forexo_pro_identify_officers",
"id": "bdb87a86-bd8d-6d83-b976-e114959a38d9",
"name": "Identify officers",
"task_type": "COMPANY_IDENTIFY_OFFICERS"
},
{
"alias": "forexo_pro_identify_shareholders",
"id": "913c68e8-c246-463d-b59b-78c4444647b9",
"name": "Identify shareholders",
"task_type": "COMPANY_IDENTIFY_BENEFICIAL_OWNERS"
}
],
"status": "APPLIED"
}
],
"category": "APPLICANT",
"checks": [ ... ],
"collected_data": {
"entity_type": "COMPANY",
"customer_ref": "",
"metadata": {
"country_of_incorporation": "GBR",
"name": "AERIAL TRADERS",
"number": "09565115",
"structured_company_type": { }
},
"officers": { … },
"ownership_structure": { … }
},
"collection_steps": [ ],
"creation_date": "2020-02-27 14:48:07",
"display_name": "AERIAL TRADERS",
"document_images": [ ],
"events": [ ],
"has_associates": true,
"has_collection_steps": false,
"id": "a2e7545b-cb67-7a0e-7108-a444461891a9",
"linked_to": [ ],
"role": "COMPANY_CUSTOMER",
"root_id": "822789de-c438-ac0a-94a4-9c80d704c0ec",
"status": "NORMAL",
"tags": [ ],
"task_progress": { … },
"task_types": [ … ],
"tasks": [ … ],
"unresolved_event_types": [ ]
}To find the task variant ID in the response:
Find the object in the
applicationsarray that has the product alias you're using. In the preceding example, theapplicationsarray has one object withforexo_proas the product aliasapplications.product.alias.When you've found the right object, look in its
required_tasksto find the one with thetask_typethat matches the task you're usingapplications.required_tasks.task_type, then take the corresponding variant IDapplications.required_tasks.id. In this example, the task with theCOMPANY_IDENTIFY_OFFICERStask type hasbdb87a86-bd8d-6d83-b976-e114959a38d9as the task variant ID.