Manage associated entities for a Business

Add, edit and remove associated entities for a business

Suggest Edits

Associative entities can be managed against an entity via APIs. The features that are currently available

  • Make a new entity a directly associated entity of a parent organisation.
  • Make an existing entity a directly associated entity of a parent organisation, or update an existing association.
  • Remove a previously created association between an entity and a parent organisation.

📣

️ Call Out

  • Associated Parties can only be added after an ownership query run succesfully.
  • There is no validation to enforce only a total of 100% ownership being added via the associated parties.

Make a new entity a directly associated entity of a parent organisation

This allows you to create a new entity and associate it with a parent organisation in one call.

The request needs to contain the following details:

  • Details of the entity to be created organisation or individual
  • Percentage held by the entity
  • Roles that this entity is playing in the parent organisation

Endpoint

{{entityId}}/associateEntity/new

Sample Request and Response

Request

{
    "entity": {
        "addresses": [
            {
                "addressType": "RESIDENTIAL",
                "buildingName": "test",
                "careOf": "testcareof",
                "country": "AUS",
                "postalCode": "3100",
                "region": "Australia",
                "startDate": "2020-01-01",
                "state": "VIC",
                "streetName": "Test Avenue",
                "streetNumber": "123",
                "streetType": "Street",
                "suburb": "Clayton",
                "town": "Melbourne",
                "unitNumber": "1"
            }
        ],
        "dateOfBirth": {
            "country": "AUS",
            "dateOfBirth": "1990-01-01",
            "locality": "Melbourne",
            "yearOfBirth": "1990"
        },
        "name": {
            "displayName": "QA 2",
            "familyName": "2",
            "givenName": "QA"
        },
        "entityType": "INDIVIDUAL",
        "gender": "M"
    },
    "percentageHeld": {
        "beneficially": 25
    },
    "roles": [
        {
            "type": "DIR",
            "typeDescription": "Director"
        },
        {
            "type": "SHRH",
            "typeDescription": "Share holder"
        }
    ],
    "addedBy": "Test"
}

{
     "entity": {
          "extraData": [
               {
                    "kvpKey": "ABN",
                    "kvpType": "id.external",
                    "kvpValue": "39930279816"
               }
          ],
          "organisationData": {
               "adverseCreditDataPresent": false,
               "registeredName": "test"
          },
          "entityType": "ORGANISATION"
     },
    "percentageHeld": {
        "beneficially": 25
    },
    "roles": [
        {
            "type": "DIR",
            "typeDescription": "Director"
        },
        {
            "type": "SHRH",
            "typeDescription": "Share holder"
        }
    ],
    "addedBy": "Test"
}

Response

{
    "entity": {
        "addresses": [
            {
                "addressId": "c1b0f9d9-018f-fde5-570c-84525171fa70",
                "addressType": "RESIDENTIAL",
                "buildingName": "test",
                "country": "AUS",
                "endDate": "0001-01-01",
                "extraData": [
                    {
                        "kvpKey": "original_source",
                        "kvpType": "general.string",
                        "kvpValue": "frankie-kyb"
                    }
                ],
                "postalCode": "3100",
                "region": "Australia",
                "startDate": "2020-01-01",
                "state": "VIC",
                "streetName": "Test Avenue",
                "streetNumber": "123",
                "streetType": "Street",
                "suburb": "Clayton",
                "town": "Melbourne",
                "unitNumber": "1"
            },
            {
                "addressId": "f26e3e8f-73cf-1897-a825-1b28adbc6434",
                "addressType": "RESIDENTIAL",
                "buildingName": "test",
                "country": "AUS",
                "endDate": "0001-01-01",
                "postalCode": "3100",
                "region": "Australia",
                "startDate": "2020-01-01",
                "state": "VIC",
                "streetName": "Test Avenue",
                "streetNumber": "123",
                "streetType": "Street",
                "suburb": "Clayton",
                "town": "Melbourne",
                "unitNumber": "1"
            },
            {
                "addressId": "aacf95f5-ed3a-ff29-3787-f69b7a86b77f",
                "addressType": "RESIDENTIAL",
                "buildingName": "test",
                "country": "AUS",
                "endDate": "0001-01-01",
                "postalCode": "3100",
                "region": "Australia",
                "startDate": "2020-01-01",
                "state": "VIC",
                "streetName": "Test Avenue",
                "streetNumber": "123",
                "streetType": "Street",
                "suburb": "Clayton",
                "town": "Melbourne",
                "unitNumber": "1"
            }
        ],
        "dateOfBirth": {
            "country": "AUS",
            "dateOfBirth": "1990-01-01",
            "locality": "Melbourne",
            "yearOfBirth": "1990"
        },
        "entityId": "8d54f5a7-a170-cc41-421c-8f9009a658fc",
        "entityType": "INDIVIDUAL",
        "extraData": [
            {
                "kvpKey": "original_source",
                "kvpType": "general.string",
                "kvpValue": "frankie-kyb"
            }
        ],
        "flags": [
            {
                "flag": "created_by_ff",
                "value": 1
            }
        ],
        "gender": "M",
        "name": {
            "displayName": "QA Testing 2",
            "familyName": "2",
            "givenName": "QA Testing"
        }
    },
    "percentageHeld": {
        "beneficially": 25,
        "total": 25
    },
    "requestId": "01G3A82WCKX82F7JQNDGD5FDX0",
    "roles": [
        {
            "type": "DIR",
            "typeDescription": "Director"
        },
        {
            "type": "SHRH",
            "typeDescription": "Share holder"
        }
    ]
}

{
    "entity": {
        "entityId": "93a3a0a6-7f34-fed9-1e12-85701259219c",
        "entityType": "ORGANISATION",
        "extraData": [
            {
                "kvpKey": "ABN",
                "kvpType": "id.external",
                "kvpValue": "39930279816"
            }
        ],
        "flags": [
            {
                "flag": "change_count",
                "value": 1
            }
        ],
        "name": {
            "displayName": "QA Testing",
            "familyName": "Test",
            "givenName": "MY PRETTY LITTLE RIBBON"
        },
        "organisationData": {
            "lastCheckDate": "0001-01-01",
            "registeredName": "test",
            "registration": {
                "date": "0001-01-01",
                "state": "VIC"
            },
            "startDate": "0001-01-01"
        }
    },
    "percentageHeld": {
        "beneficially": 25,
        "total": 25
    },
    "requestId": "01G3AC4K73EBRAB4EJTYV75NCK",
    "roles": [
        {
            "type": "DIR",
            "typeDescription": "Director"
        },
        {
            "type": "SHRH",
            "typeDescription": "Share holder"
        }
    ]
}

Make an existing entity a directly associated entity of a parent organisation, or update an existing association

This allows you to create an association with an existing entity and parent organisation. This can also be used to updated the precentage held and the roles of an already existing association between the entity and the organisation.

The request can contain the following depending on the type of call:

  • Percentage held by the entity
  • Roles that this entity is playing in the parent organisation

Endpoint

/{entityId}/associateEntity/{otherId}

otherId - existing entity

entityId - parent organisation

Sample Request and Response

Request

{
    "percentageHeld": {
        "beneficially": 25
    },
    "roles": [
        {
            "type": "DIR",
            "typeDescription": "Director"
        },
        {
            "type": "SHRH",
            "typeDescription": "Share holder"
        }
    ],
    "addedBy": "Test"
}

Response

{
    "entity": {
        "addresses": [
            {
                "addressId": "be25e9a9-d48c-a238-1664-5b473b745f9a",
                "addressType": "RESIDENTIAL1",
                "country": "AUS",
                "endDate": "0001-01-01",
                "longForm": "1/1 Clayton Road Alley, Clayton Victoria 3168, Australia",
                "postalCode": "3168",
                "startDate": "0001-01-01",
                "state": "VIC",
                "streetName": "Clayton Road",
                "streetNumber": "1",
                "streetType": "Alley",
                "town": "Clayton",
                "unitNumber": "1"
            }
        ],
        "dateOfBirth": {
            "dateOfBirth": "1990-01-01",
            "yearOfBirth": "1990"
        },
        "entityId": "a362b307-1584-9318-7748-a8979008808b",
        "entityProfile": "sole_trader",
        "entityType": "INDIVIDUAL",
        "extraData": [
            {
                "kvpKey": "kyc.method",
                "kvpValue": "electronic"
            },
            {
                "kvpKey": "check_type.alias",
                "kvpValue": "sole_trader"
            },
            {
                "kvpKey": "age_group",
                "kvpValue": "over18"
            },
            {
                "kvpKey": "customer_reference",
                "kvpType": "id.external"
            },
            {
                "kvpKey": "dob.Buddhist",
                "kvpValue": "2533-01-01"
            },
            {
                "kvpKey": "consent.general",
                "kvpValue": "true"
            },
            {
                "kvpKey": "consent.docs",
                "kvpValue": "true"
            },
            {
                "kvpKey": "consent.creditheader",
                "kvpValue": "true"
            }
        ],
        "flags": [
            {
                "flag": "verification_runs",
                "value": 1
            }
        ],
        "identityDocs": [
            {
                "country": "AUS",
                "documentId": "279e53a6-6b23-29ba-f344-3fb74ee43a7d",
                "extraData": [
                    {
                        "kvpKey": "kyc_document_category",
                        "kvpValue": "primary_photographic"
                    }
                ],
                "idExpiry": "0001-01-01",
                "idIssued": "0001-01-01",
                "idNumber": "123456789",
                "idType": "DRIVERS_LICENCE",
                "region": "VIC"
            },
            {
                "country": "AUS",
                "documentId": "91da0a2f-facb-7fc9-8f09-441507a1b951",
                "idExpiry": "0001-01-01",
                "idIssued": "0001-01-01",
                "idNumber": "1234567890",
                "idType": "MSISDN"
            }
        ],
        "name": {
            "familyName": "1",
            "givenName": "QA testing"
        }
    },
    "percentageHeld": {
        "beneficially": 25,
        "total": 25
    },
    "requestId": "01G0JWF295E05EZHQMTAQ00T6R",
    "roles": [
        {
            "type": "DIR",
            "typeDescription": "Director"
        },
        {
            "type": "SHRH",
            "typeDescription": "Share holder"
        }
    ]
}

Remove a previously created association

This allows you to remove an already created association betwen an entity and an organisation created by either of the above calls.

Endpoint

{{entityId}}/associateEntity/{{otherId}}

Sample Request and Response

Request

curl --request DELETE \
     --url https://api.demo.frankiefinancial.io/compliance/v1.2/business/{{entityId}}/associateEntity/{{otherId}} \
     --header 'X-Frankie-CustomerID: YOUR_CUSTOMER_ID' \
     --header 'api_key: YOUR_API_KEY'
     --header 'content-type: application/json' \

Response

{
  "requestId": "01BFJA617JMJXEW6G7TDDXNSHX",
  "statusMsg": "Thingy has been successfully processed."
}

📘

Percentage Held

The percentage can be held Beneficially, Jointly or Non Beneficially

📘

Roles

The various roles type that can be used are and also a single entity can hold more than one role.

(Type - Type Description)

  • DIR - Director
  • SCR - Secretary
  • OWNR - Owner
  • SHRH - Shareholder
  • TRST - Trustee
  • BEN - Beneficiary
  • SET - Settler
  • APP - Appointer
  • ALDI - Alternate Director
  • APAU - Appointed Auditor
  • OTH - Other (please specify free text for description)

Please note: the types and descriptions can have custom values defined. The above values are default.

Updated about 2 months ago