Employee Custom Field

Get Employee Custom Fields

This endpoint retrieves a list of all custom fields for a specific employee.

GET

https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/custom_fields

Path Parameters

organisation_iduuidrequired

The ID of the organisation to retrieve

employee_iduuidrequired

The ID of the employee to retrieve

Query Parameters

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

Response Body

A hash with a data property that contains an array of up to limit employee custom fields. Each entry in the array is a separate employee custom field object. If there are no more employee custom fields, the resulting array will be empty.

dataobject

itemsobject[]

iduuid

The id of the custom field

valuestring | object[]

The value of the custom field filled in by your employee, it is a string when type is free_text and an array when type is single_select or multi_select

namestring

The name of the custom field

descriptionstring

The description of the custom field

typeenum<string>

The type of the custom field

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

total_itemsnumber

Total items

total_pagesnumber

Total pages

Example

curl -X GET \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/custom_fields" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"

Response

{  "data": {    "items": [      {        "id": "78869738-f730-4a92-8978-dd64e5asb0be",        "value": [          {            "id": "18e33075-7233-4c0a-9fc9-6ce48e07c807",            "value": "Medium"          }        ],        "name": "Tshirt Size",        "description": "Tshirt sizing for purchasing uniforms",        "type": "single_select"      },      {        "id": "f497b9a4-464b-4637-9c23-0e65bg9ae968",        "value": [          {            "id": "2c6fb761-f7b2-4ddc-a6b1-cfe734cfc54d",            "value": "Friday"          },          {            "id": "3c0677ec-7c57-46c2-a584-1a1058ffe184",            "value": "Tuesday"          },          {            "id": "e66bd01e-e563-429f-b476-0956be7c5d04",            "value": "Wednesday"          }        ],        "name": "Work day preference",        "description": "Tracking workday preferences to help with rostering ",        "type": "multi_select"      }    ],    "page_index": 1,    "item_per_page": 20,    "total_items": 2,    "total_pages": 1  }}

Update Employee Custom Field

This endpoint updates the value of a single custom field for a specific employee.

PATCH

https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/custom_fields/:custom_field_id

Path Parameters

organisation_iduuidrequired

The ID of the organisation

employee_iduuidrequired

The ID of the employee

custom_field_iduuidrequired

The ID of the custom field definition

Request Body

valuestring

The text value to set. Use for free_text fields only. Pass an empty string to clear the value.

option_idsuuid[]

UUIDs of the selected custom field option records. Use for single_select and multi_select fields. Pass an empty array to clear.

Field type examples

Provide either value or option_ids — not both. The field to use depends on the custom field's type.

free_text:

{ "value": "HR-001" }

single_select:

{ "option_ids": ["uuid-of-custom-field-option"] }

multi_select:

{ "option_ids": ["uuid-of-option-1", "uuid-of-option-2"] }

Response Body

Returns the updated custom field definition with its new value. The shape of value depends on the field type — a string for free_text, or an array of { id, value } objects for single_select and multi_select.

dataobject

iduuid

The id of the custom field

valuestring | object[]

The value of the custom field filled in by your employee, it is a string when type is free_text and an array when type is single_select or multi_select

namestring

The name of the custom field

descriptionstring

The description of the custom field

typeenum<string>

The type of the custom field

Example

curl -X PATCH \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/custom_fields/:custom_field_id" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \  -H "Content-Type: application/json" \  -d '{    "option_ids": [      "18e33075-7233-4c0a-9fc9-6ce48e07c807"    ]  }'

Response

{  "data": {    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",    "name": "Employment Type",    "description": "Employment classification for this employee",    "value": [      {        "id": "18e33075-7233-4c0a-9fc9-6ce48e07c807",        "value": "Full Time"      }    ],    "type": "single_select"  }}

Bulk Update Employee Custom Fields

This endpoint updates multiple custom field values for a specific employee in a single request. Only fields included in the request are updated — all other custom fields retain their existing values.

PATCH

https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/custom_fields/bulk

Path Parameters

organisation_iduuidrequired

The ID of the organisation

employee_iduuidrequired

The ID of the employee

Request Body

custom_fieldsobject[]required

List of custom field update entries. Only fields included in this array are updated — all other custom fields for the employee retain their existing values.

Response Body

Always returns HTTP 200 even when some fields fail — this endpoint uses a best-effort strategy. Check summary.total_failed and errors to detect partial failures.

dataobject

itemsobject[]

Successfully updated custom field objects.

summaryobject

Counts of updated and failed fields.

errorsobject[]

Validation errors for fields that failed. Empty when all fields succeed.

Partial failure example

When one or more fields fail validation, successfully updated fields are still returned in items and the failures are reported in errors.

{
  "data": {
    "items": [
      {
        "id": "uuid-of-custom-field",
        "name": "Department Code",
        "description": "The HR department identifier",
        "value": "HR-001",
        "type": "free_text"
      }
    ],
    "summary": {
      "total_updated": 1,
      "total_failed": 1
    },
    "errors": [
      {
        "custom_field_id": "uuid-of-failed-field",
        "message": "option_ids contains UUIDs that do not belong to this custom field"
      }
    ]
  }
}

Example

curl -X PATCH \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/custom_fields/bulk" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \  -H "Content-Type: application/json" \  -d '{    "custom_fields": [      {        "custom_field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",        "option_ids": [          "c3d4e5f6-a7b8-9012-cdef-123456789012"        ]      },      {        "custom_field_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",        "option_ids": [          "18e33075-7233-4c0a-9fc9-6ce48e07c807"        ]      }    ]  }'

Response

{  "data": {    "items": [      {        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",        "name": "Department Code",        "description": "The HR department identifier",        "value": [          {            "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",            "value": "HR-001"          }        ],        "type": "single_select"      },      {        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",        "name": "Employment Type",        "description": "Employment classification for this employee",        "value": [          {            "id": "18e33075-7233-4c0a-9fc9-6ce48e07c807",            "value": "Full Time"          }        ],        "type": "single_select"      }    ],    "summary": {      "total_updated": 2,      "total_failed": 0    },    "errors": []  }}