Update an existing employee

The first step to updating an employee is to understand the people and jobs model in intelliHR. You can find more information about people and jobs here.

Making People and Job updates via the intelliHR API allows our customers to keep their people data in sync with their other systems. It is a key functionality that allows for integrations between intelliHR and your business systems.

For example, if you process a remuneration change in another system, you might want to make sure that it automatically appears in intelliHR.

This article covers:

• Finding the Person or Job ID
• List all People
• List all Jobs
• Update a Person
• What if the Person Record No Longer Exists?
• Update a Job

Finding the Person or Job ID

In order to make an update to a person or job in intelliHR we first need to return the relevant ID. There are a number of ways that you can do this via the the API.

List all People

Using the List All People endpoint, you can return all employees in your intelliHR tenant. The people endpoint will return both the personId and jobsId for all employees. Using the endpoints powerful filters, you can perform a search of characteristics. One of the more reliable methods of searching for a personId in intelliHR is to use the primaryEmailAddress filter. Depending update source and intelliHR share an externalId, it may be a more reliable method of filtering for the person record.

"url": <https://api.intellihr.io/v1/people>

"method": 'GET'

"headers": {
        "Content-Type": 'application/json',
        "Accept": 'application/json',
        "Authorization": `Bearer ${apikey}`,
        "Tenant": tenantname
  }

List all Jobs

Using the List All Jobs endpoint, you can return all jobs in your intelliHR tenant. The jobs endpoint will return the jobId and the attached personId. Using the endpoint’s filters, you can perform a search of job characteristics based on a number of parameters.

"url": <https://api.intellihr.io/v1/jobs>

"method": 'GET'

"headers": {
        "Content-Type": 'application/json',
        "Accept": 'application/json',
        "Authorization": `Bearer ${apikey}`,
        "Tenant": tenantname
  }

Update a Person

The update person endpoint allows you to make changes to the employee’s person record. This includes fields like their email address, phone numbers, emergency contacts and addresses. Using the personID we returned from the List All Users endpoints, we can construct a HTTP PATCH request to make these updates.

The following change requests that can be made on a person’s profile page can be found here.

Required field information include is the person’s id as the resource identifier string.

💡 You only need to include the information you are changing in your request.

In the example below, we are using the POST endpoint to update the employee’s dateOfBirth and emegencyContact.

"url": <https://api.intellihr.io/v1/people/{id}>

"method": 'PATCH'

"headers": {
        "Content-Type": 'application/json',
        "Accept": 'application/json',
        "Authorization": `Bearer ${apikey}`,
        "Tenant": tenantname
  }

"body": {
{
"firstName": "Bruce",
"middleName": "Thomas",
"lastName": "Wayne",
"preferredName": "Batman",
"dateOfBirth": "1989-07-23",
"gender": "Other",
"employeeNumber": "00001",
"title": "Mr",
"emergencyContact": {
	"name": "Alfred Pennyworth",
	"relationship": "Sibling",
	"phone": "0451 234 234",
	"email": "johndoe@example.com"
	}
   }

What if the Person Record No Longer Exists?

If the person record you are trying to update no longer exists, the intelliHR API will return a 404 Error when the PATCH request is made. This error means the requested resource (the person record) could not be found.

Update a Job

The Patch an Existing Job endpoint allows you to make changes to an employees job record in intelliHR via the API. These types of changes include Business Unit, Location, Remuneration and Supervisor Person.

Using the update jobs endpoint, you can iterate the response to update a person's job information.

Required field information can be found on the intelliHR API documentation here.

In the below example, we will use the PATCH endpoint to update the employee’s positionTitle and businessUnit.

"url": <https://api.intellihr.io/v1/jobs/{id}>

"method": 'PATCH'

"headers": {
        "Content-Type": 'application/json',
        "Accept": 'application/json',
        "Authorization": `Bearer ${apikey}`,
        "Tenant": tenantname
  }

"body": {
"effectiveFrom": "2022-12-19",
"name": "Customer Success Manager",
"businessUnit": {
	"name": "Customer Success"
	}
}

This example serves to demonstrate how the two main types of objects on the intelliHR API interact.

positionTitle is a field which means that if an option is sent via the API which does not already exist in the position title library, it will be automatically created.

businessUnit is a search object. This means that if you send a businessUnit, that does not already have an exact match in your tenant’s business unit library, your request will fail.

Tip: For information on creating and managing user accounts via the intelliHR API, contact your friendly intelliHR Integration Team! You can reach them at integrations@intellihr.com