Create a business entity

Creating an entity object for an ORGANISATION is not all that obvious from the raw documentation, so here is what is needed as a minimum to create an entity that can be used to run business reports and queries and ultimate beneficial owner checks.

Key Entity Attributes

Using the standard entity object, we first need to set the following attribute:

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 we retrieve the business details 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 for ABN)
    "kvpValue": "001234567",
    "kvpType": "id.external"
}

📘

Note

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

Example minimal ORGANIZATION entity

Endpoint
https://api.demo.frankiefinancial.io/compliance/v1.2/entity

....../entity

Below is a sample Request where an Organisation entity will be created

{
    "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 where an Organisation 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. We will need to subsequently run a check/report 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
		}
	}