Position

Last updated: 11 Jul 2024

Integrate with PageUp's Core HR Position API with your HRIS to create, update and archive Position records.


Contents

  1. Overview
  2. Requesting API Credentials
  3. Before you begin
  4. Examples
  5. Validation Messages
  6. Error Messages
  7. URL format
  8. Postman Collection

Overview

The Core HR Position API allows you to manipulate positions. The purpose of this API is to provide an endpoint for the consumers to insert a new position or update an existing one. The Position API allows for:

  • Creating a record for a new position in the system.
  • Updating a record for an existing position in the system.
  • Archiving a record for an existing position in the system.

Requesting API Credentials

For information on how to obtain API credentials and to start integrating with the Core HR API, please visit the Getting started page.


Before you begin

To begin using any of the Core HR APIs, there are a few things that you will need:

  1. Authentication credentials for your chosen PageUp Client
  2. You will need a valid (oAuth)JWT token to authorize yourself to access the end points in this API. When requesting the bearer token with the authentication service please ensure you include the scope Public.HrCore.Write in the authentication request. Multiple scopes may be requested by specifying them as space separated list. The available scope is
    Public.HrCore.Write
    

This information will be provided to you when you register for API credentials.


Examples

Here are some examples on how to create and update Positions using the Core HR Positions API. Please note that the Position number and Name fields are mandatory for all requests, however there are certain fields that are mandatory based on the action that you are trying to perform. More details on these fields are available in the following sections.

Data types

Please ensure all dates adhere to ISO-8601 format (YYYY-MM-DD or YYYYMMDD). Any time passed in to the date fields (eg. 2021-10-01T01:42:21.534Z) will be disregarded while parsing the date.

Creating a Position

To create a position record, follow the example provided below. The fields that are required to create a position are ExternalId, Name. Other fields provided in the example below are optional. The consumer will be provided with a validation message in response if there are any required fields missing. For a full list of what fields are available and to also view details on requests and all types of responses, please refer to the API specifications below.

Request

PUT /hrcore/position
{
  "externalId": "CS123",
  "name": "Customer Specialist",
  "parentPositionExternalId": "CS122",
  "roleExternalId": "R58",
  "siteExternalId": "S967",
  "costCentreExternalId": "CC264",
  "payScaleExternalId": "PS364",
  "agreementExternalId": "A46",
  "workTypeExternalId": "WT468",
  "jobTypeExternalId": "JT36",
  "agreementTypeExternalId": "AT346",
  "agreementClassificationExternalId": "AC54",
  "jobSectorExternalId": "JS3476",
  "positionTypeExternalId": "PT2346",
  "fte": 1,
  "baseHours": 7.5,
  "critical": true,
  "funded": true,
  "vacant": true,
  "vacantDate": "2021-10-01",
  "archive": false,
  "businessUnit": {
    "level1ExternalId": "BRAN01",
    "level2ExternalId": "DEP04",
    "level3ExternalId": "SDEP07",
    "level4ExternalId": "DPOS35"
  },
  "supplementary": {
    "textField1": "TEXT1",
    "textField2": "TEXT2",
    "textField3": "TEXT3",
    "textField4": "TEXT4",
    "textField5": "TEXT5",
    "textField6": "TEXT6",
    "textField7": "TEXT7",
    "textField8": "TEXT8",
    "textField9": "TEXT9",
    "textField10": "TEXT10",
    "boolField1": true,
    "boolField2": true,
    "boolField3": true,
    "boolField4": true,
    "boolField5": true,
    "dateField1": "2022-06-27",
    "dateField2": "2022-06-26",
    "dateField3": "2022-06-25",
    "dateField4": "2022-06-24",
    "dateField5": "2022-06-23",
    "dateField6": "2022-06-22",
    "dateField7": "2022-06-21",
    "dateField8": "2022-06-20",
    "dateField9": "2022-06-19",
    "dateField10": "2022-06-18"
  },
  "genericList": [
    {
      "genericListTypeExternalId": "TYPE1",
      "genericListValueExternalId": "VALUE1"
    },
	{
      "genericListTypeExternalId": "GENLIST2",
      "genericListValueExternalId": "GENVALUE2"
    }
  ]
}

Updating a Position

To update a position record, follow the example provided below. The fields that are required to update a position are externalId and at least one additional field that needs to be updated. Other fields provided in the example below are optional. The consumer will be provided with a validation message in response if there are any required fields missing. If any of the fields are not provided they will not be modified however if you intend to delete a field from the record then pass that field as a null value this will trigger the field to be removed from the system. In terms of lists or collections in the payload if a collection is passed then it will be updated in the system with all the values in the current collection, if the collection is passed as null then it will be removed from the system. For a full list of what fields are available and to also view details on requests and all types of responses, please refer to the API specifications below.

Request

PUT /hrcore/position
{
  "externalId": "CS123",
  "name": "Customer Specialist",
  "parentPositionExternalId": "CS122",
  "roleExternalId": "R58",
  "siteExternalId": "S967",
  "costCentreExternalId": "CC264",
  "payScaleExternalId": "PS364",
  "agreementExternalId": "A46",
  "funded": false,
  "vacant": true,
  "vacantDate": "2021-10-01",
  "archive": false,
  "businessUnit": {
    "level1ExternalId": "BRAN01",
    "level2ExternalId": "DEP04",
    "level3ExternalId": "SDEP07",
    "level4ExternalId": "DPOS35"
  },
  "supplementary": {
    "textField1": "UPDATETEXT1",
    "textField2": "UPDATETEXT2",
    "textField3": "UPDATETEXT3",
    "boolField1": false,
    "dateField1": "2022-06-27"
  },
  "genericList": [
    {
      "genericListTypeExternalId": "TYPE1",
      "genericListValueExternalId": "VALUE1"
    },
	{
      "genericListTypeExternalId": "GENLIST1",
      "genericListValueExternalId": "GENVALUE1"
    }
  ]
}

Archiving a Position

To archive a position, follow the example provided below. The fields that are required to archive a position are externalId and archive. The consumer will be provided with a validation message in response if there are any required fields missing. For a full list of what fields are available and to also view details on requests and all types of responses, please refer to the API specifications below.

Request

PUT /hrcore/position
{
  "externalId": "CS123",
  "archive": true
}

Validation messages

When integrating with the Core HR API, you may receive validation messages in your responses. Each specific Core HR API resource documents the list of validation messages you may receive and what they mean.


Error messages

In addition to validation messages, you may also receive generic HTTP Status code error messages in your responses. Information on these error messages can be found on our Error handling page.


URL format

Root url:
https://<environment>.<dataCentreId>.pageuppeople.com/v3/<tenantId>/hrcore/...
Where
  environment = specify 'api' for production or 'apiuat' for development or testing
  dataCentreId = the data centre to connect to (e.g. dc2)
  tenantId = the organisation's tenant Id (e.g. 218)
Region dataCentreId
AUS dc2
UK / EMEA dc3
US dc4
SEA dc5

Please contact PageUp representative to find out the data centre and organisation's tenant Id if not known.

Example - connect to the 218 production environment on dc2

https://api.dc2.pageuppeople.com/v3/218/hrcore/position

Example - connect to the 218 development or testing environment on dc2

https://apiuat.dc2.pageuppeople.com/v3/218/hrcore/position

Postman Collection

The Postman collection is available publicly (Core HR API > Position API): Position API

Run in Postman