Create a business entity

Learn how to create an Entity object that represents a business.

Suggest Edits

Create organisations in FrankieOne to represent business entities. Below are steps to create an entity that can be used to run business reports and query for ownership.

Key Entity Attributes

Using the standard entity object, the following attribute will be set as part of entity creation:

entityType: ORGANISATION

Because this isn't a person, there's no need to set the name, dateOfBirth, and gender fields.

Addresses can also be provided, although these will be populated when business details are retrieved from ABR and ASIC.

Documents can also be added to the entity object if there is a need to store additional data.

The extraData KVP array is also there if there's a need to capture additional information. This is important for key corporate attributes and identifiers such as ABN/ACN. See below.

Also, for a custom reference number, the optional customer_reference key can be added.

The organizationData structure is where the bulk of the organization details can be found. The API documentation covers most of these fields in some detail, but the key one to note is the organizationData.registeredName which is the actual name of the organization.

Setting ABN and/or ACN

Australian Company Number (ACN) and Australian Business Number (ABN) are defined as external IDs in the entity.extraData KVP array.

To do this, create a KVP of the form:

{
    "kvpKey": "ACN",    //same structure for ABN
    "kvpValue": "001234567",
    "kvpType": "id.external"
}

📘

Note

Ensure the kvpType is set to id.external so that this is correctly identified and indexed within the system.

Example minimal ORGANIZATION entity

Create entity API reference

Below is a sample request to create Organisation entity.

curl --request POST \
     --url https://api.kycaml.uat.frankiefinancial.io/compliance/v1.2/entity \
     --header 'accept: application/json' \
     --header 'api_key: {api_key}' \
     --header 'X-Frankie-CustomerId: {customer_id}' \
     --header 'content-type: application/json'  \
     --data '
{
    "entityType": "ORGANISATION",
    "extraData": [
        {
            "kvpKey": "ACN",
            "kvpValue": "001234567",
            "kvpType": "id.external"
        },
        {
            "kvpKey": "ABN",
            "kvpValue": "61001234567",
            "kvpType": "id.external"
        }
    ],
    "organisationData": {
        "registeredName": "Example Corporation Ltd"
    }
}'

Below is a sample response for a Organisation that is successfully created.

{
    "entity": {
        "entityId": "1aa5fb8f-0595-895f-ed0e-247f8806597e",
        "entityType": "ORGANISATION",
        "extraData": [
            {
                "kvpKey": "ACN",
                "kvpType": "id.external",
                "kvpValue": "001234567"
            },
            {
                "kvpKey": "ABN",
                "kvpType": "id.external",
                "kvpValue": "61001234567"
            }
        ],
        "organisationData": {
            "lastCheckDate": "0001-01-01",
            "registeredName": "Example Corporation Ltd",
            "startDate": "0001-01-01"
        }
    },
    "requestId": "01FZEFXC6D6C45X9DMAVSHGVET"
}

🚧

Business Ownership

This API just creates an organisation entity. Subsequent API calls can run check or generate reports on the created entity as required (e.g. business ownership query).

Business Organisation Data

It's possible to have additional data in the business especially after a business ownership query has been run. The entity will have a organisationData object with the possible information below .

	"organisationData": {
		"class": {
			"code": "LMSH", // This is the company class code as defined by ASIC 
			"description": "Limited By Shares" // This is the company class code description  as defined by ASIC 
		}, 
		"registeredName": "FRANKIE FINANCIAL PTY LTD",
		"registration": {
			"date": "2017-03-31",
			"state": "VIC"
		},
		"reviewDate": "2024-03-31", //The date on which an organisation or business name should review their details with ASIC to ensure they are correct
		"startDate": "2017-12-19",
		"status": {
			"code": "REGD",  //This is the business's status code in ASIC
			"description": "Registered"  //This is the business's status code descritption  in ASIC
		},
		"subclass": {
			"code": "PROP", //This is the company sub class as defined by ASIC
			"description": "Proprietary Company" //This is the company sub class description as defined by ASIC
		},
		"type": {
			"code": "APTY", //This is the business type 
			"description": "Australian Proprietary Company" ////This is the business type description
		}
	}

Updated 10 days ago