Position

List Positions

Retrieve a paginated list of HR positions for an organisation. By default only active positions are returned; pass show_archived=true to include archived positions. Results can be filtered by work site and cost centre.

GET

https://api.employmenthero.com/api/v1/organisations/:organisation_id/positions

Path Parameters

organisation_iduuidrequired

The ID of the organisation.

Query Parameters

show_archivedboolean

Include archived positions in the response. Defaults to false (active positions only).

work_site_idsuuid[]

Filter results to positions belonging to the specified work site IDs.

cost_centre_idsuuid[]

Filter results to positions belonging to the specified cost centre IDs.

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

Response Body

A paginated list of HR positions for the organisation. Each item includes work site, cost centre, title, team assignment, and roster position details.

dataobject

itemsobject[]

iduuid

Unique identifier for the HR position.

statusenum<string>

The status of the HR position.

hr_position_titleobject

The HR position title details.

roster_positions_countnumber

The number of active roster positions for this HR position.

cost_centreobject

The cost centre associated with this HR position.

colorenum<string>

The color associated with this HR position.

team_assign_modeenum<string>

The team assign mode of this HR position.

member_idsuuid[]

Array of unique identifiers for members assigned to this HR position.

team_idsuuid[]

Array of unique identifiers for teams assigned to this HR position.

Note

This field corresponds to 'Groups' in the Employment Hero UI.

roster_positionsobject[]

Array of active roster positions assigned to this HR position.

work_siteobject

The work site associated with this HR position.

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

total_itemsnumber

Total items

total_pagesnumber

Total pages

Example

curl -X GET \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/positions" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"

Response

{  "data": {    "items": [      {        "id": "74aae202-676b-4e8e-8c56-55612ced8e2d",        "status": "active",        "hr_position_title": {          "id": "c44cfdca-7433-46e9-9502-038fa6333dce",          "name": "Barista"        },        "roster_positions_count": 2,        "cost_centre": {          "id": "0b7ef29a-5172-4437-a6fd-2c9291eb04a9",          "name": "AU Operations"        },        "color": "smalt",        "team_assign_mode": "auto_assign",        "team_ids": [          "7d5046b1-b63c-427c-bfdd-917f733e8496"        ],        "member_ids": [          "fe179bf9-19e3-4779-b458-e2d418127186",          "a1b2c3d4-e5f6-7890-abcd-ef1234567890"        ],        "roster_positions": [          {            "id": 1234,            "member_id": "fe179bf9-19e3-4779-b458-e2d418127186"          },          {            "id": 1235,            "member_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"          }        ],        "work_site": {          "id": "aea965c5-c095-49ea-896e-131bc5c4cf3b",          "name": "Melbourne CBD"        }      }    ],    "page_index": 1,    "item_per_page": 20,    "total_items": 1,    "total_pages": 1  }}

Get Position

Retrieve a single HR position by its identifier. Returns the full position record including work site, cost centre, assigned members, and roster position details. Returns 404 if the position does not exist or is outside the requester's permitted work site scope.

GET

https://api.employmenthero.com/api/v1/organisations/:organisation_id/positions/:id

Path Parameters

organisation_iduuidrequired

The ID of the organisation.

iduuidrequired

The ID of the HR position to retrieve.

Response Body

The requested HR position object, including work site, cost centre, title, team assignment, and roster position details.

dataobject

iduuid

Unique identifier for the HR position.

statusenum<string>

The status of the HR position.

hr_position_titleobject

The HR position title details.

roster_positions_countnumber

The number of active roster positions for this HR position.

cost_centreobject

The cost centre associated with this HR position.

colorenum<string>

The color associated with this HR position.

team_assign_modeenum<string>

The team assign mode of this HR position.

member_idsuuid[]

Array of unique identifiers for members assigned to this HR position.

team_idsuuid[]

Array of unique identifiers for teams assigned to this HR position.

Note

This field corresponds to 'Groups' in the Employment Hero UI.

roster_positionsobject[]

Array of active roster positions assigned to this HR position.

work_siteobject

The work site associated with this HR position.

Example

curl -X GET \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/positions/:id" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"

Response

{  "data": {    "id": "74aae202-676b-4e8e-8c56-55612ced8e2d",    "status": "active",    "hr_position_title": {      "id": "c44cfdca-7433-46e9-9502-038fa6333dce",      "name": "Barista"    },    "roster_positions_count": 2,    "cost_centre": {      "id": "0b7ef29a-5172-4437-a6fd-2c9291eb04a9",      "name": "AU Operations"    },    "color": "smalt",    "team_assign_mode": "auto_assign",    "team_ids": [      "7d5046b1-b63c-427c-bfdd-917f733e8496"    ],    "member_ids": [      "fe179bf9-19e3-4779-b458-e2d418127186",      "a1b2c3d4-e5f6-7890-abcd-ef1234567890"    ],    "roster_positions": [      {        "id": 1234,        "member_id": "fe179bf9-19e3-4779-b458-e2d418127186"      },      {        "id": 1235,        "member_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"      }    ],    "work_site": {      "id": "aea965c5-c095-49ea-896e-131bc5c4cf3b",      "name": "Melbourne CBD"    }  }}

Create Position

Create a new HR position for a work site. The position can be assigned to specific members and teams, and can have a color associated with it for visual identification.

POST

https://api.employmenthero.com/api/v1/organisations/:organisation_id/positions

Path Parameters

organisation_iduuidrequired

The ID of the organisation

Request Body

namestringrequired

The name of the HR position

work_site_iduuidrequired

Unique identifier for an existing work site

cost_centre_iduuidrequired

Unique identifier for an existing cost centre

member_idsuuid[]

Array of unique identifiers for members assigned to this HR position.

team_idsuuid[]

Array of unique identifiers for teams assigned to this HR position.

Note

This field corresponds to 'Groups' in the Employment Hero UI.

team_assign_modeenum<string>

The team assign mode for the HR position

colorenum<string>

The color associated with the HR position.

Response Body

The created position object.

dataobject

iduuid

Unique identifier for the HR position.

statusenum<string>

The status of the HR position.

hr_position_titleobject

The HR position title details.

roster_positions_countnumber

The number of roster positions for this HR position.

cost_centreobject

The cost centre associated with this HR position.

colorenum<string>

The color associated with this HR position.

team_assign_modeenum<string>

The team assign mode of this HR position

member_idsuuid[]

Array of unique identifiers for members assigned to this HR position.

team_idsuuid[]

Array of unique identifiers for teams assigned to this HR position.

Note

This field corresponds to 'Groups' in the Employment Hero UI.

roster_positionsobject[]

Array of active roster positions assigned to this HR position.

Example

curl -X POST \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/positions" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \  -H "Content-Type: application/json" \  -d '{    "name": "Position",    "work_site_id": "382443a5-f39d-4d55-bf30-1489f7fd6acf",    "cost_centre_id": "0b7ef29a-5172-4437-a6fd-2c9291eb04a9",    "member_ids": [      "fe179bf9-19e3-4779-b458-e2d418127186"    ],    "team_ids": [      "7d5046b1-b63c-427c-bfdd-917f733e8496"    ],    "color": "smalt",    "team_assign_mode": "auto_assign"  }'

Response

{  "data": {    "id": "74aae202-676b-4e8e-8c56-55612ced8e2d",    "status": "active",    "hr_position_title": {      "id": "c44cfdca-7433-46e9-9502-038fa6333dce",      "name": "Position"    },    "roster_positions_count": 5,    "cost_centre": {      "id": "0b7ef29a-5172-4437-a6fd-2c9291eb04a9",      "name": "AU"    },    "color": "smalt",    "team_assign_mode": "auto_assign",    "team_ids": [      "7d5046b1-b63c-427c-bfdd-917f733e8496"    ],    "member_ids": [      "fe179bf9-19e3-4779-b458-e2d418127186"    ],    "roster_positions": [      {        "id": 1234,        "member_id": "fe179bf9-19e3-4779-b458-e2d418127186"      }    ]  }}

Update Position

Update an existing HR position. All parameters are optional, allowing you to update only the fields you need.

PATCH

https://api.employmenthero.com/api/v1/organisations/:organisation_id/positions/:position_id

Path Parameters

organisation_iduuidrequired

The ID of the organisation

position_iduuidrequired

The ID of the position

Request Body

namestring

The name of the HR position

cost_centre_iduuid

Unique identifier for an existing cost centre

member_idsuuid[]

Array of unique identifiers for members assigned to this HR position.

team_idsuuid[]

Array of unique identifiers for teams assigned to this HR position.

Note

This field corresponds to 'Groups' in the Employment Hero UI.

team_assign_modeenum<string>

The team assign mode for the HR position

colorenum<string>

The color associated with the HR position.

Response Body

The updated HR position object.

dataobject

iduuid

Unique identifier for the HR position.

statusenum<string>

The status of the HR position.

hr_position_titleobject

The HR position title details.

roster_positions_countnumber

The number of roster positions for this HR position.

cost_centreobject

The cost centre associated with this HR position.

colorenum<string>

The color associated with this HR position.

team_assign_modeenum<string>

The team assign mode of this HR position

member_idsuuid[]

Array of unique identifiers for members assigned to this HR position.

team_idsuuid[]

Array of unique identifiers for teams assigned to this HR position.

Note

This field corresponds to 'Groups' in the Employment Hero UI.

roster_positionsobject[]

Array of active roster positions assigned to this HR position.

Example

curl -X PATCH \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/positions/:position_id" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \  -H "Content-Type: application/json" \  -d '{    "name": "Updated Position Name",    "cost_centre_id": "0b7ef29a-5172-4437-a6fd-2c9291eb04a9",    "member_ids": [      "fe179bf9-19e3-4779-b458-e2d418127186"    ],    "team_ids": [      "7d5046b1-b63c-427c-bfdd-917f733e8496"    ],    "color": "green",    "team_assign_mode": "auto_assign"  }'

Response

{  "data": {    "id": "74aae202-676b-4e8e-8c56-55612ced8e2d",    "status": "active",    "hr_position_title": {      "id": "c44cfdca-7433-46e9-9502-038fa6333dce",      "name": "Position"    },    "roster_positions_count": 5,    "cost_centre": {      "id": "0b7ef29a-5172-4437-a6fd-2c9291eb04a9",      "name": "AU"    },    "color": "smalt",    "team_assign_mode": "auto_assign",    "team_ids": [      "7d5046b1-b63c-427c-bfdd-917f733e8496"    ],    "member_ids": [      "fe179bf9-19e3-4779-b458-e2d418127186"    ],    "roster_positions": [      {        "id": 1234,        "member_id": "fe179bf9-19e3-4779-b458-e2d418127186"      }    ]  }}