This help guide will show you how to find the right entity and field in the HR API, including custom fields, manager details, leaving reasons and nationality.

Contents

• Introduction
• Check what your key can access
• Entities with different routes
• Where to find common fields
• ID fields and lookups
• Current and historical job data
• Custom fields
• Tips

Introduction

Data in the HR API is organised into entities (such as PersonDetail, AllJobPay and Absence), each with its own properties (fields). Most questions about "missing" data come down to one of three things: the data is held in a different entity, the field is an ID that needs looking up, or the entity or property has not been enabled on the API key.

Check what your key can access

The quickest way to see what your key can do is the API Help page:

1. Go to https://<yoursystem>.ciphr.com/api/Help
2. Enter your API key on the Authentication tab and click Connect
3. The Operations section then lists every entity, route and method (GET, POST, PUT, DELETE) available to that key, with the properties for each

If an entity does not appear, it is either not enabled on the key or none of its properties have been added. The error you receive tells you which:

Entities with different routes

Most entities are called directly, for example /api/PersonDetail or /api/AllJobPay. A few are only available through a parent record, so calling them directly returns a 404:

Some entities also support fewer methods than their access toggles suggest:

• PersonDetail supports GET and PUT only. New employee records can only be POST into the ATSApplicant entity which requires the Candidate Importer and configuration completed by Ciphr; create the employee in Ciphr HR first using the New Employee Wizard or importing through the Candidate Importer, then update them through the API.
• AllJobPay is read-only. To create or update job and pay records, use /api/PersonDetail/<PerID>/JobPay.

Where to find common fields

ID fields and lookups

Properties ending in ID hold the ID of a record in another entity. Where no matching description property is available, enable the lookup entity on the key and match the ID:

Lookup entities usually contain a small, fixed list, so it is more efficient to retrieve the whole list once (for example GET /api/LeavingReason) and match IDs locally than to call the API for each employee.

Current and historical job data

Custom fields

Further Information fields

Further Information fields on Personal Details and Job & Pay appear in the API as properties beginning CF, followed by the field's label with spaces removed. For example, a field labelled Agency/Referral Name appears as CFAgency/ReferralName.

• In the key's Configuration view, these properties are listed under their internal names (for example ClientFieldText1), not the CF name returned by the API.
• Labels can include characters such as / and (. These work in the f parameter as they are. When filtering on them, URL-encode the name, for example CFAgency%2FReferralName=[notnull].
• Give each Further Information field a unique label, so each CF property name is unique.

Additional Information (custom data categories)

Additional Information categories (for example Children or Health and Safety Incidents) can hold several records per employee, so they have their own entities:

1. List the categories and their IDs: GET /api/CustomDataCategory
2. Get the records for a category: GET /api/CustomDataCategory/<CategoryID>/CustomData

{"CustomData":[{"ID":<ID>,"PerID":<PerID>,"CatID":<CategoryID>,"Forenames":"Paul","Dateofbirth":"1995-07-01T00:00:00","Notes":null}]}

Each record includes the employee's PerID, and its other properties are named after the category's field labels with spaces removed. Job-related categories work in the same way through JobCustomDataCategory and JobCustomData.

Tips

• Property names are not case-sensitive in filters and the f parameter (surname and Surname both work).
• Use the f parameter to return only the fields you need, for example /api/PersonDetail?f=ID,EmployeeNumber,ManagerName. A property that is not enabled is silently left out of the response.
• Filtering on a property that is not enabled returns 400 Malformed query string with Unrecognised property.
• Check the Help page with your key whenever you change the configuration, to confirm the entities, routes and methods available.