/legal_entities

Returns a collection of your account legal entities. Required scope: r_account. Accessible with all token types.

🚧

This endpoint uses r_account scope which can be enabled through the Integrations section found within the Settings menu. This endpoint is only accessible for accounts that have enabled Employee Management features.

Results

Calling the /legal_entities endpoint will return a collection of the defined legal_entities for the account. An example of the response follows:

JSON

[
    {
        "id": "8b588cb9-8ab2-4ae4-9b14-99a8e0f910f6",
        "name": "Demo Entity US",
        "legal_name": "",
        "type": "entity",
        "parent_id": null,
        "display_name": "Demo Entity US"
    },
    {
        "id": "218baa69-a0f2-44bb-a0b4-11cd002f2d6a",
        "name": "Boston, MA, USA",
        "legal_name": null,
        "type": "location",
        "parent_id": "8b588cb9-8ab2-4ae4-9b14-99a8e0f910f6",
        "display_name": "Demo Entity US | Boston, MA, USA"
    },
    {
        "id": "f06cd9dd-005c-4a87-bf2d-f972953d96a8",
        "name": "Financial District",
        "legal_name": null,
        "type": "site",
        "parent_id": "218baa69-a0f2-44bb-a0b4-11cd002f2d6a",
        "display_name": "Demo Entity US | Boston, MA, USA | Financial District"
    },
    {
        "id": "ae48fc93-6b2c-453e-9e51-5909e090044d",
        "name": "Demo Entity UK",
        "legal_name": "",
        "type": "entity",
        "parent_id": null,
        "display_name": "Demo Entity UK"
    },
    {
        "id": "e697173f-5853-48c0-8eb4-b9c67ca11a93",
        "name": "London, England, United Kingdom",
        "legal_name": null,
        "type": "location",
        "parent_id": "ae48fc93-6b2c-453e-9e51-5909e090044d",
        "display_name": "Demo Entity UK | London, England, United Kingdom"
    },
    {
        "id": "ab745273-9327-4baf-860f-8ec0a267303c",
        "name": "London",
        "legal_name": null,
        "type": "site",
        "parent_id": "e697173f-5853-48c0-8eb4-b9c67ca11a93",
        "display_name": "Demo Entity UK | London, England, United Kingdom | London"
    },
    {
        "id": "552e100e-b12e-4712-99e9-abb456373019",
        "name": "Demo Entity Australia",
        "legal_name": "",
        "type": "entity",
        "parent_id": null,
        "display_name": "Demo Entity Australia"
    },
    {
        "id": "ebc4650f-3f8b-4306-90f3-7a18558cdd8f",
        "name": "Sydney, New South Wales, Australia",
        "legal_name": null,
        "type": "location",
        "parent_id": "552e100e-b12e-4712-99e9-abb456373019",
        "display_name": "Demo Entity Australia | Sydney, New South Wales, Australia"
    }
]

Each legal_entity will have the following keys:

key	type	description
id	string	The legal entity identifier. Note that this id should be used when creating or updating an employee using the POST and PATCH endpoints respectively.
name	string	The common or colloquial name of the entity, location, or site
legal_name	string	The official or legal name of the entity. It may be null if not provided or not applicable.
type	string	The classification type of the object. Available values include entity, location, and site
parent_id	string	A reference to the unique identifier of the parent object. For entity types, this is often null. For location, it typically refers to an entity. For site, it typically refers to a location
display_name	string	A concatenated, human-readable name which includes the hierarchy from entity to location to site