API Reference

/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:

[
    {
        "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:

keytypedescription
idstringThe legal entity identifier. Note that this id should be used when creating or updating an employee using the POST and PATCH endpoints respectively.
namestringThe common or colloquial name of the entity, location, or site
legal_namestringThe official or legal name of the entity. It may be null if not provided or not applicable.
typestringThe classification type of the object. Available values include entity, location, and site
parent_idstringA 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_namestringA concatenated, human-readable name which includes the hierarchy from entity to location to site
Language
Authorization
Header
URL
Click Try It! to start a request and see the response here!