Integrate with PageUp's Core HR Generic List API with your HRIS to create, update and archive generic list values for use in Job, Offer, and Position forms.
The Core HR Generic List API allows you to manipulate Generic Lists. The purpose of this API is to provide an endpoint for the consumers to insert new Generic List Values, or update an existing one. The Generic List API allows for:
For information on how to obtain API credentials and to start integrating with the Core HR API, please visit the Getting started page.
To begin using any of the Core HR APIs, there are a few things that you will need:
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.
Here are some examples on how to create and update Generic List Values using the Core HR Generic List API. Please note that the Generic List Value ID (externalId
) field is 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. Also note that you will need to have the Generic List Type ID (listTypeExternalId
) available as this will be part of the API endpoint route (URL).
The route for the API endpoint is /hrcore/generic-list/{listTypeExternalId}/value
. The URL route listTypeExternalId
corresponds to the Generic List Type record to which this value belongs.
To create a Generic List Value record, follow the example provided below. The fields that are required to create a Generic List Value record are externalId
and value
.
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.
PUT /hrcore/generic-list/GENTYPE1/values
{
"externalId" : "GEN-VALUE1",
"value" : "Value Name",
"clientValue" : "Client Value Name",
"parentValueExternalId" : "PARENTLIST1-VALUE1",
"archive" : false
}
To update a Generic List Value record, follow the example provided below. The fields that are required to update a Generic List Value 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.
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.
PUT /hrcore/generic-list/GENTYPE1/values
{
"externalId" : "GEN-VALUE1",
"value" : "New Value Name",
"clientValue" : null
}
To archive a Generic List, follow the example provided below. The fields that are required to archive a Generic List 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.
PUT /hrcore/generic-list/GENTYPE1/values
{
"externalId" : "GEN-VALUE1",
"archive" : true
}
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.
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.
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/generic-list/type1/values
Example - connect to the 218 development or testing environment on dc2
https://apiuat.dc2.pageuppeople.com/v3/218/hrcore/generic-list/type1/values
The Postman collection is available publicly (Core HR API > Generic List API): Generic List API