Locations

Authentication: All endpoints require an Authorization: Bearer <access token> header.

Most endpoints require an X-Company-ID: <company_id> header to scope requests to a specific company. This is the recommended header for most API operations.

Some endpoints require an X-Location-ID: <location_id> header when the query doesn't accept a locationId parameter.

See Authentication for details on how to obtain and use these headers.

Query Locations

Retrieve all locations configured for the company. Locations represent physical sites, offices, or organizational units where employees work.

Query Parameters:

This query takes no parameters and returns all locations configured for the company.

Response Fields:

Field Description
id Unique identifier for the location
name Name of the location (e.g., "Brisbane Office")
timeZone IANA timezone identifier (e.g., "Australia/Brisbane")
rosterable Whether this location can be used for roster/scheduling
parentId ID of the parent location (for hierarchical organization)

For the complete Location type reference and all available fields, see the GraphQL Schema Reference.

Implementation Notes:

  • Locations can be organized hierarchically using the parentId field
  • A parentId of "0" indicates a top-level location with no parent
  • The timeZone field uses IANA timezone database format
  • When rosterable is false, the location cannot be used in roster/shift scheduling
  • Only active (non-deleted) locations are returned by default
  • Locations are company-specific and all accessible locations are returned in a single query

GraphQL Query

query Locations {
  locations {
    id
    name
    timeZone
    rosterable
    parentId
  }
}

Example Variables

{}

Example Response

{
  "data": {
    "locations": [
      {
        "id": "12325",
        "name": "Integration Sandbox",
        "timeZone": "Australia/Brisbane",
        "rosterable": true,
        "parentId": "0"
      },
      {
        "id": "12326",
        "name": "Brisbane Office",
        "timeZone": "Australia/Brisbane",
        "rosterable": true,
        "parentId": "12325"
      }
    ]
  }
}

Add Location

Create a new location. This allows you to add new physical sites, offices, or organizational units for your company.

Mutation Parameters:

Parameter Type Required Description
input AddLocationInput! Yes Input object containing location details
input.name String! Yes Name of the location
input.rosterable Boolean! Yes Whether the location can be used for rosters

For the complete input type reference, see AddLocationInput.

Response Fields:

Field Description
id Unique identifier for the created location
name Name of the location
rosterable Whether the location can be used for rosters

For the complete Location type reference and all available fields, see the GraphQL Schema Reference.

Implementation Notes:

  • The location name must be unique within the company
  • Newly created locations are active by default
  • The rosterable flag determines if the location can be used in shift scheduling
  • The system will assign a default timezone based on company settings

GraphQL Mutation

mutation AddLocation($input: AddLocationInput!) {
  addLocation(input: $input) {
    id
    name
    rosterable
  }
}

Example Variables

{
  "input": {
    "name": "Milton Office",
    "rosterable": true
  }
}

Example Response

{
  "data": {
    "addLocation": {
      "id": "12754",
      "name": "Milton Office",
      "rosterable": true
    }
  }
}

Update Location

Update an existing location's details. This allows you to modify the name, rosterable status, or other properties of a location.

Mutation Parameters:

Parameter Type Required Description
input UpdateLocationInput! Yes Input object containing updated details
input.id String! Yes ID of the location to update
input.name String! Yes Updated name for the location
input.rosterable Boolean! Yes Whether the location can be used for rosters

For the complete input type reference, see UpdateLocationInput.

Response Fields:

Field Description
id Unique identifier for the location
name Updated name of the location
rosterable Whether the location can be used for rosters

For the complete Location type reference and all available fields, see the GraphQL Schema Reference.

Implementation Notes:

  • The location ID must be valid and belong to the company
  • The updated name must be unique within the company
  • Changing the rosterable flag to false may affect existing rosters and shifts
  • Updates are applied immediately and affect all associated data
  • You cannot update a deleted location; restore it first using the restore mutation

GraphQL Mutation

mutation UpdateLocation($input: UpdateLocationInput!) {
  updateLocation(input: $input) {
    id
    name
    rosterable
  }
}

Example Variables

{
  "input": {
    "id": "12754",
    "name": "Park Road Office",
    "rosterable": true
  }
}

Example Response

{
  "data": {
    "updateLocation": {
      "id": "12754",
      "name": "Park Road Office",
      "rosterable": true
    }
  }
}

Delete Location

Soft delete a location. The location is marked as deleted but not permanently removed, allowing it to be restored later if needed.

Mutation Parameters:

Parameter Type Required Description
id ID! Yes ID of the location to delete

Response Fields:

Field Description
(string) Returns the ID of the deleted location

Implementation Notes:

  • This is a soft delete operation - the location is not permanently removed
  • Deleted locations will not appear in the standard locations query
  • You cannot delete a location that has active employees, rosters, or other dependencies
  • The deletion can be reversed using the restore mutation
  • Deleting a parent location does not automatically delete child locations
  • Child locations will need to be reassigned to a new parent or deleted separately

GraphQL Mutation

mutation DeleteLocation($id: ID!) {
  deleteLocation(id: $id)
}

Example Variables

{
  "id": "12761"
}

Example Response

{
  "data": {
    "deleteLocation": "12761"
  }
}

Restore Location

Restore a previously deleted location. This reverses a soft delete operation and makes the location active again.

Mutation Parameters:

Parameter Type Required Description
id ID! Yes ID of the location to restore

Response Fields:

Field Description
(string) Returns the ID of the restored location

Implementation Notes:

  • Only soft-deleted locations can be restored
  • The location will be restored with all its original settings and properties
  • Restored locations will immediately appear in the standard locations query
  • Any hierarchical relationships (parent/child) are preserved
  • You cannot restore a location if its parent location is still deleted
  • Restore the parent location first, then restore child locations

GraphQL Mutation

mutation RestoreLocation($id: ID!) {
  restoreLocation(id: $id)
}

Example Variables

{
  "id": "12761"
}

Example Response

{
  "data": {
    "restoreLocation": "12761"
  }
}