Custom Employee Details Fields

Employee Details Fields let you define your own custom fields on employee profiles, beyond the standard set of name, business unit, job role and location. Use them to capture information that matters to your business, such as employment type, risk classification, internal vs. external hire status, or a second external job ID, and then use that information to filter your employee list, segment your dashboard, and drive CheckIntelligence rules.

This article covers what the feature does, how to set up and manage fields, how they appear for your team when adding or editing employees, and how they can be used in filtering, the API, and CheckIntelligence.

What you can do with Employee Details Fields

• Create your own custom fields on employee profiles, each with a chosen data type (text, number, yes/no, date, or an options field with values you define)
• Mark a field as mandatory, so it must be completed whenever an employee or candidate is created or their profile is edited
• Populate field values from the employee/candidate creation and edit workflows
• Filter your employee list by any custom field value; dashboard filtering support currently varies by field type
• Send and receive field values through the API
• Use field values as conditions in CheckIntelligence rules (e.g. "if Risk Level = High, require a Police Check")

Some example fields customers are using this for:

Where to manage fields

Custom fields are managed from the admin area, in the same section where you currently manage Business Units, Job Roles and Locations. Custom Employee Details Fields now sit alongside these as a fourth category in that section.

Only company admins can create, edit, or delete fields. Employees and candidates cannot create fields; they can only have values entered against fields your admins have already set up.

Creating a new field

When creating a field, you'll specify:

• Name: the label your team will see (e.g. "Risk Level"). This also generates a unique key for referencing the field in the API. Once the field is created, this key cannot be changed, so double-check the name before saving.
• Type: one of:
  • Text: free text
  • Number
  • Yes/No
  • Date
  • Options: a fixed list of values you define (e.g. "Casual", "Part-time", "Full-time")
• Option values (if applicable): the initial set of allowed options. You can add more later.
• Mandatory or optional: if set to mandatory, the field must be filled in whenever a new employee or candidate is added, and whenever an existing profile is next edited. Employees with no value currently in the field are not retroactively blocked until their profile is edited.

Editing a field

You can:

• Rename the field label at any time
• Add new option values at any time

You cannot:

• Change the field's data type once any employee has a value stored against it
• Remove an option value that's currently in use by an employee
• Delete a field while it still has employee data or option values attached to it

To delete a field, first clear all employee data and option values from it. Once it's empty, it can be deleted. Once deleted, the field and its values no longer appear anywhere, including the API — but the field's key isn't permanently reserved, so a new field could later be created with the same key.

A note on mandatory fields and your API integration: if you mark a field as mandatory after your API integration is already live, any future API call that omits that field will start returning a validation error. If you're integrated with our API, coordinate any change to a field's mandatory status with whoever manages that integration.

Adding values on employee and candidate profiles

Once a field exists, it appears automatically in:

• The Add Employee / Add Candidate screen
• The Edit Employee Profile screen

Options fields appear as a dropdown of the values your admin has configured; other field types use an appropriate input for their type (a text box, number box, date picker, or Yes/No toggle). Only your team's pre-configured option values are selectable from these screens; new option values can only be added from the admin area.

Filtering by Employee Details Fields

Once employees have values populated, those fields become available wherever you filter or segment employee data:

• Employee list: every custom field is automatically available as a filter option (e.g. show all employees where Employment Type = Part-time)
• Dashboard: custom fields can appear as additional filter options alongside your existing Business Unit, Location and Job Role filters, letting you segment your check volumes and statuses by custom field values — note that dashboard filtering support currently varies by field type, so not every custom field will show up as a dashboard filter yet

There's no extra setup required to make a field filterable on the Employee list; it happens automatically once the field exists. Dashboard filtering coverage is being extended over time.

Using Employee Details Fields in CheckIntelligence

While CheckIntelligence can utilise these fields, our UI upgrade to allow configuration of these rules directly in the CheckWorkRights admin section is still in progress. Please contact our team to discuss your requirements.

Using Employee Details Fields via the API

If you integrate with our public API, custom field values are returned on the employee object as a key/value map, using the field's key:

{   "details": 
  { 
    "employment_type": "full_time", 
    "risk_level": "high", 
    "external_job_id": "HJ-98234" 
  } 
}

Notes for integrators:

• Field values submitted via the API are validated against the field's configured type (and, for Options fields, against the allowed values). Requests with invalid values are rejected with a structured error rather than being silently dropped.
• If a field is later marked mandatory, integration calls that omit it will begin failing validation from that point forward (see the note above under Editing a field).
• This is an additive change to the employee object; existing integrations are unaffected unless you choose to start sending or reading details. Note that details requires API v3.0 or later — if your integration is on an earlier API version, you'll need to upgrade to use it.

FAQs

Can I change a field's type after it's created?
Only if no employee data has been entered against it yet. Once any employee has a value stored, the type is locked. If you need to change type, create a new field instead.

What happens to a field's data if I delete it?
You must remove all employee values and option values before a field can be deleted. Once deleted, the field disappears from your account and the API, but its key isn't permanently reserved — a newly created field could end up reusing that key.

Can employees or candidates create their own fields?
No, field creation is an admin-only capability. Employees and candidates can only have values entered against fields your admins have already configured.

Is there a limit to how many custom fields we can create?
There is no fixed limit at this stage, but we recommend keeping your field set purposeful. Internal support docs and best-practice guidance on when to use a custom field vs. requesting a standard field will be shared separately.

Have questions about setting up Employee Details Fields for your company? Reach out to your Account Manager or our support team.