Create a profile for an associate and link it to a company in the API

This developer guide takes you through the steps to create profiles for company associates in the Passfort API 4.0.

Why do associates have profiles?

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 have ongoing monitoring.

To learn more about the product application lifecycle, see Manage product applications.

The relationship between company tasks types and associate roles

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 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
`COMPANY_IDENTIFY_OFFICERS`	`COMPANY_SECRETARY` `DIRECTOR` `PARTNER` `OTHER` `RESIGNED_OFFICER`
`COMPANY_IDENTIFY_BENEFICIAL_OWNERS`	`BENEFICIAL_OWNER` `SHAREHOLDER`
`COMPANY_IDENTIFY_AUTHORISED_PERSONS`	`AUTHORIZED_PERSON`
`COMPANY_IDENTIFY_TRUSTEES`	`TRUSTEE`
`COMPANY_ASSESS_OWNERSHIP`	`SHAREHOLDER` `BENEFICIAL_OWNER` `GLOBAL_ULTIMATE_OWNER` `CONTROLLING_SHAREHOLDER`

Before you begin

To avoid potential errors, you should ensure your policy is configured correctly.

To follow these steps you need to have Read-only access for the Smart policies permission.

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 Profile data > Authorized persons.

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 Policy Builder > Tasks 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 Policy Builder > Your products.
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 Individual Policy > Smart Policy. If you're not, ensure there is a task set under Individual Policy > Task set.
If you're using Risk and you have a separate product for associates, take note of the risk models on the company product, Individual Policy > Risk model and Company Policy > Risk model, 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:
1. Set the Product for which associated profiles will apply option to the product that automatically approves all profiles.
2. Set the Criteria for automatic addition to the verification list option to Add all profiles.
3. Set the Policy for automatic task completion option to All profiles in the verification list must be approved.
On the normal associate task, set the Criteria for automatic addition to the verification list option to Automatic addition is disabled.

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 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

role

*Required

string

INDIVIDUAL_ASSOCIATED or COMPANY_ASSOCIATED

The profile's type.

For associates who are individuals, the value should be INDIVIDUAL_ASSOCIATED.

For associates who are companies, the value should be COMPANY_ASSOCIATED.

collected_data

*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 collected_data, see Create a profile in the developer resources.

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 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 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_data

Sample 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 an INDIVIDUAL or a COMPANY.
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 developer resources.

Officers object

Use the officers object when the associated_role is any of the following:

COMPANY_SECRETARY
DIRECTOR
PARTNER
OTHER
RESIGNED_OFFICER
TRUSTEE

These are the required parameters for the object.

Key	Value	Description
`officers` *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.
`officers.directors` 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.
`officers.directors.entity_type` *Required string	`INDIVIDUAL` or `COMPANY`	Whether the director is an individual or a company.
`officers.directors.linked_profile` 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.
`officers.directors.linked_profile.id` *Required string	Sample value: `a37764c1-134b-8c85-9527-7a9327ed9071`	The unique identifier for the associate's profile.
`officers.partners` Optional array of objects	For a sample, see the description for Update collected data in the developer resources.	This determines where the associate is displayed in the company structure. You can place the associate in more than one of these.
`officers.partners.entity_type` *Required atring	`INDIVIDUAL` or `COMPANY`	Whether the director is an individual or a company.
`officers.partners.linked_profile` *Required object	For a sample, see the description for Update collected data in the developer resources.	An object that contains the ID of the associate profile.
`officers.partners.linked_profile.id` *Required string	Sample value: `a37764c1-134b-8c85-9527-7a9327ed9071`	The unique identifier for the associate's profile.
`officers.secretaries` Optional array of objects	For a sample, see the description for Update collected data in the developer resources.	This determines where the associate is displayed in the company structure. You can place the associate in more than one of these.
`officers.secretaries.entity_type` *Required string	`INDIVIDUAL` or `COMPANY`	Whether the director is an individual or a company.
`officers.secretaries.linked_profile` *Required object	For a sample, see the description for Update collected data in the developer resources.	An object that contains the ID of the associate profile.
`officers.secretaries.linked_profile.id` *Required string	Sample value: `a37764c1-134b-8c85-9527-7a9327ed9071`	The unique identifier for the associate's profile.
`officers.trustees` Optional array of objects	For a sample, see the description for Update collected data in the developer resources.	This determines where the associate is displayed in the company structure. You can place the associate in more than one of these.
`officers.trustees.entity_type` *Required string	`INDIVIDUAL` or `COMPANY`	Whether the director is an individual or a company.
`officers.trustees.linked_profile` *Required object	For a sample, see the description for Update collected data in the developer resources.	An object that contains the ID of the associate profile.
`officers.trustees.linked_profile.id` *Required string	Sample value: `a37764c1-134b-8c85-9527-7a9327ed9071`	The unique identifier for the associate's profile.
`officers.other` Optional array of objects	For a sample, see the description for Update collected data in the developer resources.	This determines where the associate is displayed in the company structure. You can place the associate in more than one of these.
`officers.other.entity_type` *Required string	`INDIVIDUAL` or `COMPANY`	Whether the director is an individual or a company.
`officers.other.linked_profile` *Required object	For a sample, see the description for Update collected data in the developer resources.	An object that contains the ID of the associate's profile.
`officers.other.linked_profile.id` *Required string	Sample value: `a37764c1-134b-8c85-9527-7a9327ed9071`	The unique identifier for the associate's profile.
`officers.resigned` Optional array of objects	For a sample, see the description for Update collected data in the developer resources.	This determines where the associate is displayed in the company structure. You can place the associate in more than one of these.
`officers.resigned.entity_type` *Required string	`INDIVIDUAL` or `COMPANY`	Whether the director is an individual or a company.
`officers.resigned.linked_profile` *Required object	For a sample, see the description for Update collected data in the developer resources.	An object that contains the ID of the associate profile.
`officers.resigned.linked_profile.id` *Required string	Sample value: `a37764c1-134b-8c85-9527-7a9327ed9071`	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
`authorized_persons` *Required array of objects	For a sample, see the description for Update collected data in the developer resources.	An object that lists the individuals who are authorized to purchase and, where relevant, use the product on behalf of the company.
`authorized_persons.entity_type` *Required string	`INDIVIDUAL` or `COMPANY`	Whether the associate is an individual or a company.
`authorized_persons.linked_profile` *Required object	For a sample, see the description for Update collected data in the developer resources.	An object that contains the ID of the associate's profile.
`authorized_persons.linked_profile.id` *Required string	Sample value: `a37764c1-134b-8c85-9527-7a9327ed9071`	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
`ownership_structure` *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.
`ownership_structure.beneficial_owners` 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.
`ownership_structure.beneficial_owners.entity_type` *Required string	`INDIVIDUAL` or `COMPANY`	Whether the beneficial owner is an individual or a company.
`ownership_structure.beneficial_owners.linked_profile` *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.
`ownership_structure.beneficial_owners.linked_profile.id` *Required string	Sample value: `a37764c1-134b-8c85-9527-7a9327ed9071`	The unique identifier for the associate's profile.
`ownership_structure.controlling_shareholders` Optional array of objects		This object lists the individuals and companies defined as having a controlling threshold of share ownership in the company.
`ownership_structure.controlling_shareholders.entity_type` *Required string	`INDIVIDUAL` or `COMPANY`	Whether the controlling shareholder is an individual or a company.
`ownership_structure.controlling_shareholders.linked_profile` *Required object		An object that contains the ID of the associate's profile.
`ownership_structure.controlling_shareholders.linked_profile.id` *Required string	Sample value: `a37764c1-134b-8c85-9527-7a9327ed9071`	The unique identifier for the associate's profile.
`ownership_structure.global_ultimate_owners` Optional array of objects		This object lists the individuals and companies defined as being the global ultimate owners of the company.
`ownership_structure.global_ultimate_owners.entity_type` *Required string	`INDIVIDUAL` or `COMPANY`	Whether the global ultimate owner is an individual or a company.
`ownership_structure.global_ultimate_owners.linked_profile` *Required object		An object that contains the ID of the associate's profile.
`ownership_structure.global_ultimate_owners.linked_profile.id` *Required string	Sample value: `a37764c1-134b-8c85-9527-7a9327ed9071`	The unique identifier for the associate's profile.
`ownership_structure.share_classes` Optional array of objects		This object details the share classes owned by the shareholders.
`ownership_structure.share_classes.name` *Required string	Sample value: `Ordinary`	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 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_data

Body 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 products specified in the associate tasks.
tasks: An object containing a list of the due diligence tasks that the associate needs to pass before their applications can be approved. Each task only needs to be passed or failed once, even when it's shared across multiple applications. In this example, the individual will need to have their identity and address verified before their application as a director and their 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 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 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 applications array that has the product alias you're using. In the preceding example, the applications array has one object with forexo_pro as the product alias applications.product.alias.
When you've found the right object, look in its required_tasks to find the one with the task_type that matches the task you're using applications.required_tasks.task_type, then take the corresponding variant ID applications.required_tasks.id. In this example, the task with the COMPANY_IDENTIFY_OFFICERS task type has bdb87a86-bd8d-6d83-b976-e114959a38d9 as the task variant ID.

In this section:

Using Passfort