This help guide explains why employees or leavers may be missing from your HR API results, and how to check and correct your API key's filtering settings.

Contents

• Introduction
• Quick checklist
• Filtering settings
• How excluded people appear in the API
• Paging and query parameters
• Properties not enabled
• Good practice

Introduction

Each API key only returns the people allowed by its Filtering settings. If an employee, leaver or future starter is outside those settings, the API behaves as if they do not exist: they are left out of every entity, including PersonDetail, AllJobPay and Absence, and no error explains why.

Most cases of "missing" employees are caused by one of the following:

• The employee's record group or payroll code is not included on the key
• The employee is a leaver whose leaving date is outside the Past Leavers period
• The employee is a future starter whose start date is outside the Future Starters period
• The integration is only reading the first page of results

Quick checklist

If a specific person is missing from your API results, work through these checks in order:

1. Check their record group or payroll code. Open the employee's record in Ciphr HR and confirm their record group (or payroll code) is listed in the key's People Filtering.
2. If they are a leaver, check their leaving date against the key's Past Leavers setting.
3. If they have not started yet, check their start date against the key's Future Starters setting.
4. Check your request. If you use paging, make sure every page is read (see Paging and query parameters).
5. After any change, click Update at the bottom of the Filtering page. Changes, including newly added record groups, are not applied until you do.

Filtering settings

The filtering settings can be accessed via the following area:

• System Configuration > API Configuration

Click Filtering against the relevant key. The current Past Leavers and Future Starters settings for each key are also shown in the key list.

Past Leavers

The Past Leavers period is a rolling window. A leaver is returned only while their leaving date falls within the number of months selected, counted back from today. Once their leaving date moves outside the window, they drop out of all API results automatically.

For example, with Past Leavers set to 6 months on 14 October, leavers with leaving dates of 1 August, 29 May and 23 May are returned, but a leaver from 1 April is not.

Future Starters

Future Starters works in the same way for employees whose start date is in the future. With a setting of 0, new starters are not returned until their start date. If your integration needs to set up accounts or equipment before an employee starts, set a period that covers how far ahead your starters are entered.

People Filtering

Only employees in the record groups (or payroll codes) listed on the key are returned. To add one:

1. Click Add under People Filtering
2. Select the record group or payroll code and click Add
3. Click Update at the bottom of the page to save

How excluded people appear in the API

The API does not tell you that a person has been filtered out. Instead, they are treated as if they do not exist:

To check how many people your key can currently see, use the count parameter:

GET https://<yoursystem>.ciphr.com/api/PersonDetail?count

{"Count": <number of people>}

Compare this with the number you expect. If it is lower, review the filtering settings above.

Paging and query parameters

A request without paging parameters returns all matching records. If you use paging, the following applies:

Properties not enabled

Fields can also appear to be "missing" if their properties are not enabled on the key:

• Filtering on a property that is not enabled, for example /api/PersonDetail?WorkEmailAddress=..., returns 400 Malformed query string with Unrecognised property. Enable Read Access on that property in the key's Configuration view.
• Requesting a property that is not enabled in the f parameter, for example ?f=ID,WorkEmailAddress, does not return an error. The field is simply left out of the response.

If a field is missing from your results, check that the property is enabled on the entity in the key's Configuration view, and click Update to save.

Good practice

• Set Past Leavers to match your integration. Systems that remove access for leavers need enough months to catch late-processed leavers; data warehouses that keep history usually need All.
• Set Future Starters if you onboard in advance. With 0, new starters are not visible until their start date.
• Review API keys when record groups change. A new record group is not added to existing keys automatically.
• Always click Update. Changes on the Filtering page, including added record groups, are not applied until you save.
• Use the count parameter to check coverage. A quick ?count after any change confirms how many people the key can see.
• Read every page. If your integration uses paging, include s and l and loop through all pages.