Understanding Qualification Instances
Qualifications are used to record certificates, licences and job requirements in intelliHR. You can manage the following qualification objects via the API:
- Qualification Library items. Qualification Library Item represent a type of qualification. E.g. A Drivers license.
- Qualification Instances: Qualification Instance represents an instance of a qualification library item E.g. The specific instance of a driver licence for a given employee.
At a basic level Qualification Library items are created to represent a possible qualification an employee can hold, like a driver’s licence. Then a qualification instance of that library item is created on an employee’s record.
The intelliHR Public API allows API users to create, find, update and delete qualification library items, and allows API users to create, find, update and delete qualification instances.
This article covers:
- Create and Maintain Qualification Library Items
- Create and Maintain Qualification Instances
- Checking the Employee
- Understanding Qualification Statuses
- Create an instance
- Update or remove an instance
Create and Maintain Qualification Library Items
Typically Qualification Library items are established during the implementation process of intelliHR, but you may find that you have a need to just-in-time provision library items if a new qualification library item is generated upstream, or perhaps you want to synchronise qualification library items are initialisation.
The “Create a new Qualification Library Item” allows a client application to create a Qualification Library item via a POST request.
The Qualification Library item object requires a Qualification Type id that defines the category of qualification the Library item belongs to. System default types include types like licence, membership, registration. These options can edited in platform via Settings > Qualification Types.
We recommend performing a just-in time GET request to retrieve the approach qualification type id before performing the POST request to create a new qualification library item.
💡GET qualification types > search for desired type by name > collect type id > POST to create qualification library item.
Once you’ve decided how you’d like to handle qualification type id’s, you’ll need to perform a POST request to the url endpoint, including a payload containing the following information.
"url": https://api.intellihr.io/v1/qualification-library-items
"method": 'POST'
"headers": {
"Content-Type": 'application/json',
"Accept": 'application/json',
"Authorization": `Bearer ${apikey}`,
"Tenant": ‘tenantname'
}
body: {
"name": "<string>",
"qualificationTypeId": "<string>",
"qualificationExpiryType": "EXPIRY_REQUIRED",
"qualificationRegistrationNumberVisibilityType": "REGISTRATION_NUMBER_REQUIRED",
"qualificationAttachmentRequirementType": "DOCUMENTS_OPTIONAL",
"expiryWarningPeriod": "<number>",
"sendExpiryWarning": "<boolean>"
}
You can also PATCH qualification library items to update them, using the system id of the qualification library item in the path parameter of the /qualification-library-items.
💡 https://api.intellihr.io/v1/qualification-library-items/{id}
Create and Maintain Qualification Instances
The more common use-case for Qualifications via the API is to create and update Qualification Instances. Often another system like a workforce management tool or a rostering tool might contain a qualification self-service functionality, and you’d like to send this data to intelliHR to keep intelliHR profiles up to date.
Generally, you’ll have an event upstream like “new qualification created” or “qualification updated” that will prompt your client to send data to intelliHR.
Checking the Employee
We recommend starting your integration flow by checking if the employee has an instance of the qualification library item to help decide what to do next.
The API supports a List all Qualification Instances endpoints with quality of life filters specifically for this use-case.
We suggest using an identifier filter, personId or employeeNumber, in combination with the qualificiationLibraryItemId to narrow the list to the specific qualification library item that employee owns. If they do not have an existing instance of that qualification library item, the data object will return an empty array.
If the employee doesn’t have any instances of that qualification library item, you’ll need to create one. If the employee does have an instance of the qualification, you’ll most likely want to create a new instance of the qualification. The main use of the update endpoint is to correct or update the details of an instance, rather than register new information.
For example, if an employee has an instance of a Driver’s Licence for six months that comes up for expiry, and then register their new licence, you’ll still want to create a new instance of the qualification in intelliHR in order to reflect the new licence, and retain the historical instance.
Understanding Qualification Statuses
When creating or updating qualification instances, it’s important to understand the role of status in how the instance will be created.
The status determines whether or not the qualification instance is a draft, awaiting approval or approved. Generally you’ll want to create instances with the status of awaiting approval if an administrator or supervisor needs to review the qualification instance before it shows as compliant. Most qualifications should be created as approved if the upstream system has determined that employee holds a valid instance of that qualification.
Create an instance
To create a qualification instance, you’ll need to obtain the personId and qualification library id and include these in the body of your POST request.
"url": https://api.intellihr.io/v1/qualifications
"method": 'POST'
"headers": {
"Content-Type": 'application/json',
"Accept": 'application/json',
"Authorization": `Bearer ${apikey}`,
"Tenant": tenantname
}
body: {
"qualificationLibraryItemId": "<string>",
"personId": "<string>",
"status": "FUTURE",
"issuingOrganisation": "<string>",
"registrationNumber": "<string>",
"issueDate": "<string>",
"expiryDate": "<string>",
"expiryNotificationQueuedAt": "<string>",
"notes": "<string>"
}
Update or remove an instance
Generally you shouldn’t need to update or remove an instance unless you’re aiming to resolve incorrect data. You can update or remove an instance by referencing it’s system generated Id. The API supports the PATCH method for updating and the DELETE method to remove a qualification instance.
Managing Job Requirements
Job Requirements likewise can be created, edited, and deleted via the API.
Job Requirements are like an extra layer on top of qualification instances. They share the same data and therefore parameters like the qualificiationLibraryItemId are the same strings used in the qualifications data.
Unique paramters like qualificiationLibraryItemType are either “QUALIFICATION_LIBRARY_ITEM” or “JOB_REQUIREMENT_GROUP”.
Creating Job Requirements
"url”: https://api.intellihr.io/v1/jobs/{jobID}/job-requirements
"method”: 'POST'
"headers": {
"Content-Type": 'application/json',
"Accept":'application/json',
"Authorization": `Bearer ${apikey}`,
"Tenant": ‘tenantname'
}
body: {
“startDate”: "<string>",
“endDate”: "<string>",
“notifyEmployee”: “true”,
“jobRequirementableId”: "<string>",
“jobRequirementableType”: "<string>",
}
Updating Job Requirements
The {id} at the end of the URL will need to be fetched via a GET request.
"url”: https://api.intellihr.io/v1/jobs/{jobID}/job-requirements/{id}
"method”: 'PATCH'
"headers": {
"Content-Type": 'application/json',
"Accept":'application/json',
"Authorization": `Bearer ${apikey}`,
"Tenant": ‘tenantname'
}
body: {
“startDate”: "<string>",
“endDate”: "<string>",
“notifyEmployee”: “true”,
}
Deleting Job Requirements
"url”: https://api.intellihr.io/v1/jobs/{jobID}/job-requirements/{id}
"method”: 'DELETE'
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