Manage associated entities for a Business
Add, edit and remove associated entities for a business
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 10 months ago