Depending on the account type (i.e. individual, trust, corporate, etc.) there can be many different types of people associated with a brokerage account. For example, an IRA may have beneficiaries while a joint account will have a secondary account owner. Some other types of “people” associated with an account may be corporate entities, trustees, power of attorneys, and more. We collectively refer to all such people as "Related Persons" in our platform, signifying their connection to the account.

Advisors may require access to this information for various purposes. For example, to view details of all beneficiaries for a retirement account, such as their names, addresses or to utilize related person information in populating security-based lending applications.

Our Related Persons API is a component of the Accounts Management toolbox, enabling you to retrieve information on all related persons in addition to the account details accessible via the Accounts API.

Please note that, at present, we provide related persons information exclusively from the Pershing custodian. We plan to gradually expand this functionality to include coverage for all custodians that make this data available.

Use Cases and API Specification

There are a couple of key use cases where the Related Persons API proves to be exceptionally helpful:

Overseeing all related persons associated with a client's account.
Searching for specific information about an individual.
Identifying related persons using their SSN number.

Let's delve into the details of how to use the Related Persons API for each of these use cases.

Method	Endpoint URL	Description
`GET`	`/v2/account-management/related-persons`	Get all related persons for all accounts the application has an access to.
`POST`	`/v2/account-management/related-persons/filter`	Filter related persons by `account_id` or other personal information fields.

Use Case #1: Retrieving all related persons for the client's account

To obtain information about all related persons associated with a particular account, follow these steps:

'1. Retrieve the account_id by using the Filter Accounts API, which allows searching based on various parameters such as name, account_number, account_type, advisor_code, and others. For instance:

curl --request POST 'https://api.bridgeft.com/v2/account-management/accounts/filter' \
     --header 'Authorization: Bearer {YOUR_TOKEN}' \
     --header 'Content-Type: application/json' \
     --data '{
        "name":"Joe Johns"
}'

'2. Once you have obtained the account_id, make a POST request to the Filter Related Persons endpoint, providing it with this identifier. For example:

curl --request POST 'https://api.bridgeft.com/v2/account-management/related-persons/filter' \
     --header 'Authorization: Bearer {YOUR_TOKEN}' \
     --header 'Content-Type: application/json' \
     --data-raw '{
    "account_id": 23412
}'

The response will provide information about all related persons in the following JSON payload:

{
    "current_page": 1,
    "data": [
        {
            "account_id": 330156,
            "addresses": [
                {
                    "address_1": "1432 E NUBIAN LN",
                    "address_2": "",
                    "city": "ORANGE",
                    "country": "US",
                    "created_at_utc": "2023-10-26T20:13:22.382767Z",
                    "id": 26555,
                    "postal_code": "928663413",
                    "related_person_id": 32449,
                    "state": "CA",
                    "type": "Mailing",
                    "updated_at_utc": "2023-10-26T20:13:22.382767Z"
                },
                {
                    "address_1": "1432 E NUBIAN LN",
                    "address_2": "",
                    "city": "ORANGE",
                    "country": "US",
                    "created_at_utc": "2023-10-26T20:13:22.382767Z",
                    "id": 31730,
                    "postal_code": "928663413",
                    "related_person_id": 32449,
                    "state": "CA",
                    "type": "Legal",
                    "updated_at_utc": "2023-10-26T20:13:22.382767Z"
                }
            ],
            "created_at_utc": "2023-10-26T20:13:21.950757Z",
            "date_of_birth": null,
            "email": "",
            "entity_name": "O'MALLEY LIVING TRUST",
            "first_name": "",
            "id": 32449,
            "last_name": "",
            "middle_initial": "",
            "object": "account_management.related_person",
            "phone_numbers": [],
            "tax_id_token": "RvHcixZe5XDSEtA5L7UpL8",
            "type": "Trust Name",
            "updated_at_utc": "2023-10-26T20:13:21.950757Z"
        },
        {
            "account_id": 330156,
            "addresses": [
                {
                    "address_1": "1432 E NUBIAN LN",
                    "address_2": "",
                    "city": "ORANGE",
                    "country": "US",
                    "created_at_utc": "2023-10-26T20:13:22.382767Z",
                    "id": 25459,
                    "postal_code": "928663413",
                    "related_person_id": 37333,
                    "state": "CA",
                    "type": "Legal",
                    "updated_at_utc": "2023-10-26T20:13:22.382767Z"
                },
                {
                    "address_1": "1432 E NUBIAN LN",
                    "address_2": "",
                    "city": "ORANGE",
                    "country": "US",
                    "created_at_utc": "2023-10-26T20:13:22.382767Z",
                    "id": 25698,
                    "postal_code": "928663413",
                    "related_person_id": 37333,
                    "state": "CA",
                    "type": "Mailing",
                    "updated_at_utc": "2023-10-26T20:13:22.382767Z"
                }
            ],
            "created_at_utc": "2023-10-26T20:13:21.950757Z",
            "date_of_birth": "1948-12-18",
            "email": "",
            "entity_name": "",
            "first_name": "JOHN",
            "id": 37333,
            "last_name": "O'MALLEY",
            "middle_initial": "T",
            "object": "account_management.related_person",
            "phone_numbers": [],
            "tax_id_token": "RvHcixZe5XDSEtA5L7UpL8",
            "type": "Trustee",
            "updated_at_utc": "2023-10-26T20:13:21.950757Z"
        }
    ],
    "has_next": false,
    "has_previous": false,
    "object": "list",
    "orient": "row",
    "page_size_limit": 10000,
    "total_items": 2,
    "total_pages": 1
}

Use Case #2: Searching for specific information about a related person

If you need to retrieve specific personal information about a particular related person, simply make a call to the Filter Related Persons endpoint, providing the required search parameters. For example:

curl --request POST 'https://api.bridgeft.com/v2/account-management/related-persons/filter' \
    --header 'Authorization: Bearer {YOUR_AUTH_TOKEN}' \
    --header 'Content-Type: application/json' \
    --data '{
   "first_name": "JOHN",
   "last_name": "GROSS",
}'

Below are all the fields that can be used for searching:

Field	Type	Description
`id`	string	BridgeFT’s unique ID for this related person record
`account_id`	string	BridgeFT’s Account ID which this person is related to
`account_ids`	string array	BridgeFT’s Account IDs which this person is related to (in case if multiple associations)
`type`	string	The related person type provided by the custodian
`first_name`	string	Related person’s first name
`last_name`	string	Related person’s last name
`middle_initial`	string	Related person’s middle name
`date_of_birth`	string	Related person’s date of birth
`entity_name`	string	Typically a corporate name
`email`	string	Related person’s email address
`tax_id_token`	string	BridgeFT’s Tokenized representation of the related person's Tax ID

The response will provide all the personal information about the requested related person in the following format:

{
  "id": 1,
  "account_id": 23412,
  "type": "sometype",
  "first_name": "JOHN",
  "last_name": "GROSS",
  "middle_initial": "A",
  "date_of_birth": "1995-09-08",
  "email": "[email protected]",
  "entity_name": "John Doe's Company"
  "tax_id_token": "asdf1234fasdfa",
  "addresses": [
    {
      "address_1": "123 Example Ln",
      "address_2": "Apt 405",
      "city": "Some City",
      "state": "MO",
      "postal_code": "62324",
      "country": "US",
      "type": "SOMETYPE"
    }
  ],
  "phone_numbers": [
    {
      "phone_number": "5555555555",
      "type": "SOMETYPE"
    },
    {
      "phone_number": "2222222222",
      "type": "SOMETYPE"
    }
  ],
  "created_at_utc": "2023-10-03",
  "updated_at_utc": "2023-10-03"
}

Use Case #3: Bulk load all related persons

You can retrieve records of all related persons for all accounts accessible to your application by using the List All Related Persons endpoint. To do so, send the following request:

curl --request GET 'https://api.bridgeft.com/v2/account-management/related-persons' \
     --header 'Authorization: Bearer {YOUR_TOKEN}' \
     --header 'Content-Type: application/json' \

For large data queries, we recommend setting pagination parameters.

Use Case #4. Identifying related persons using their SSN number

This use case is a variant of the Use Case #2. The key point here is that this enables more specifically matching related persons using a unique tax_id_token. Follow the next steps to utilize person’s SSN and Tax ID token:

'1. Generate a tax_id_token using the persons SSN by querying Tax ID API:

curl --request POST 'https://api.bridgeft.com/v2/account-management/tax-id/000-00-0002' \
     --header 'Authorization: Bearer {YOUR_AUTH_TOKEN}'

In the response you will receive a tokenized representation of the SSN/Tax ID in the following format:

"Pr7myKRzgennb2qGe32i3t"

'2. Now using this token, search all related persons with the matching token. Each person returned will have an account_id associated with them:

curl --request POST 'https://api.bridgeft.com/v2/account-management/related-persons/filter' \
     --header 'Authorization: Bearer {YOUR_AUTH_TOKEN}' \
     --header 'Content-Type: application/json' \
     --data '{
    "tax_id_token": "Pr7myKRzgennb2qGe32i3t"
}'

This allows you find an information about account related person having known his(her) SSN or Tax ID number.