Custom employee fields

Within the employee endpoint, you can have up to 40 custom fields - these are fields which are set up client by client for capturing data against each employee which are not standard system fields.

In the API, you can access and use these fields in the same way as standard fields - the documentation for the API does not explicitly list these out as each client will have different names for the fields etc hence the return will be different for each client.

To assist with using custom fields, we have added some information below which shows how these are used.

To check what custom fields you have set up go to https://www.naturalhr.net/hr/company/custom-fields

On this screen you will see something which looks like the below - your field set up will, of course, be different:

When you do a GET on an employee, it will return data that looks like the below:

{
    "data": [
        {
            "id": 265731,
            "works_id": "G7LQE7",
            "title": "Miss",
            "first_name": "Aimee",
            "known_as": "",
            "middle_name": "",
            "last_name": "Hancock",
            "custom_data": {
                "Fee earner?": "Yes",
                "Driving license number": "ABC1234",
                "Health plan ID": "88774994"
            }
        }
    ]
}

When you are adding or updating an employee, the data is used slightly differently - the fields are simply passed through like any other field to the API:

curl --location --request POST 'https://api02.naturalhr.net/api/v1/employee/265731' \
--header 'Authorization: YOUR KEY' \
--header 'Content-Type: application/json' \
--form 'first_name="Aimee Louise"' \
--form 'Fee earner?="No"' \
--form 'Health plan ID="88774994E"'

Finally when we then GET the employee these fields have changed accordingly:

{
    "data": [
        {
            "id": 265731,
            "works_id": "G7LQE7",
            "title": "Miss",
            "first_name": "Aimee Louise",
            "known_as": "",
            "middle_name": "",
            "last_name": "Hancock",
            "custom_data": {
                "Fee earner?": "No",
                "Driving license number": "ABC1234",
                "Health plan ID": "88774994E"
            }
        }
    ]
}