Retrieve a position

Operation ID: getPosition

Group: People Management › Positions

Open in the interactive reference

GET /people/positions/{id}

Read-only: Reads and returns; changes nothing.

Retrieves a position. Use the position's id, not its positionNumber.

Parameters

Name In Type Required Description
Api-Version header string · v1 yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.
id path string yes The unique identifier of the position you want to retrieve.

Response

200 Success

Under data (getPositionOutput):

Field Type Required Description
id string yes The unique identifier for the position.
positionNumber string no The system-generated position number, for example 'POS-100010'. Absent while none has been assigned.
name string yes The display name of the position.
description string no A free-form description of the position's responsibilities. Absent when none is set.
desiredHeadcount number no The target number of people to fill this position.
employeeCount number no The number of employees currently in this position.
expectedSalary number no The expected annual salary for this position, in the entity's currency.
overtimeStatus string no The overtime eligibility of the position. Possible values: 'EXEMPT', 'NON_EXEMPT'.
status string no The fill status of the position. Possible values: 'unfilled', 'partiallyFilled', 'filled', 'overfilled', 'inactive'.
timelineStatus string no The timeline status of the position. Possible values: 'planned', 'inactive', 'active', 'canceled'.
startDate string no The date the position becomes active. Format YYYY-MM-DD.
endDate string no The date the position becomes inactive. Format YYYY-MM-DD. Absent for an open-ended position.
hiringManagerId string no The identifier of the hiring manager. Absent when none is assigned. See id on GET people/person/:id.
hiringManagerName string no The full name of the hiring manager. Absent when none is assigned.
jobProfileId string no The identifier of the associated job profile. Absent when none is assigned. There is no endpoint for it.
jobProfileName string no The name of the associated job profile. Absent when none is assigned.
regionId string no The identifier of the region the position is based in. Absent when none is assigned. There is no endpoint for it.
regionName string no The name of the region the position is based in. Absent when none is assigned.
lastModifiedDate date-time yes The date and time the position record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. 
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "positionNumber": "<positionNumber>",
    "name": "<name>",
    "description": "<description>",
    "desiredHeadcount": 0,
    "employeeCount": 0,
    "expectedSalary": 0,
    "overtimeStatus": "<overtimeStatus>",
    "status": "<status>",
    "timelineStatus": "<timelineStatus>",
    "startDate": "<startDate>",
    "endDate": "<endDate>",
    "hiringManagerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "hiringManagerName": "<hiringManagerName>",
    "jobProfileId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "jobProfileName": "<jobProfileName>",
    "regionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "regionName": "<regionName>",
    "lastModifiedDate": "2026-01-15T09:30:00.000Z"
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Errors

Code Status
NOT_FOUND 400

Statuses