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)