Custom Fields

This guide provides an overview of the Custom Fields API, detailing its endpoints and use cases. This API enables companies to define and manage custom fields for their employees, ensuring flexibility and configurability in handling data.

Create Custom Field

This endpoint is used to define new custom fields for a company. Here's an example of what a simple request body looks like:

{
  "data_entry_access": "company_admin_only",
  "required": true,
  "type": "percentage",
  "visibility_scope": "company_admin_only",
  "name": "Bonus"
}

In this request, you have:

  • data_entry_access: defines who can add and edit data in a custom field. Possible values are: company_admin_only, employee, or everyone.
  • required: is a boolean that defines whether this field is mandatory to fill out or not.
  • type: defines the type of the custom field that is being created. There are multiple types. These types are divided into three main parameters:
    • General fields: supports string, text, integer, date, boolean, percentage, decimal, and link.
    • Single select fields: supports choosing an item from a list. It requires a metadata object with an array of string options.
    • Currency fields: supports adding currency. It requires a metadata object specifying the ISO code of the currency. For example, for US dollars, the value entered would be USD.
  • visibility_scope: determines who can view the custom field. Possible values are: company_admin_only and everyone.
  • name: The desired name of the custom field.

ℹ️ When a custom field is created through UI, you have the option to set Profile section as personal details or job, but through API, custom fields are automatically assigned to the job profile section.

Example: Your company wants to track a bonus percentage for each employee. Using this API, you can create a custom field of type percentage and set the visibility to company_admin_only to restrict access.

ℹ️ When you set visibility_access to company_admin_only, the data_entry_access should be set to company_admin_only as well, otherwise you will get the following error:

"data_entry_access": [
            "must be 'company_admin_only' when visibility_scope is 'company_admin_only'"
        ]

List Custom Field Definitions

This endpoint fetches all custom fields created for a company. This returns a each custom field with its details that includes a unique ID. This ID can be used to query specific custom fields, as discussed in the later sections.

Update Custom Field Value

When you create a new custom field for a company, its value is defaulted to null for all employees. To populate its value for a specific employee, you can use this endpoint.

To make a successful call, you need to know the custom ID of that specific custom field (which you can get using the Lists custom fields definitions endpoint as discussed in the previous section). To set a value, you need to provide the custom fields ID and an employment ID of a specific employee. The header takes this value as data as follows:

--data '{"value":"test value"}'

ℹ️ You can only add/update value of one custom field at a time. Each custom field requires a separate endpoint call.

There are a few important points to understand here:

  • For type currency, values need to be provided in cents as decimals (e.g., $10.50 = 1050.00).
  • For single select option, the value refers to the ID of the actual value. You can retrieve this ID by calling the Lists custom fields definitions endpoint. The response will contain a snippet similar to the following:
    "options": [
        {
            "label": "your option 1",
            "value": "016b2e5f-0208-649d-8b7e-c40f8930be93"
        },
        {
            "label": "your option 2",
            "value": "016b2e5f-0208-64d8-8b7f-6fad98356129"
        },
        ...
    ]
    
    So, instead of using the label your option 1, you need to use the value instead.

Example: You are an admin who created a health insurance deduction field with type currency. You can use this endpoint to add a value to it for a specific employee by passing the value in cents ($50 = 5000.00) to ensure accurate record keeping.

custom_field.value_updated Webhook

Every time there is an update in a custom field's value, the custom_field.value_updated webhook is triggered. It sends an object with the employment_id and custom_field_id of the custom field that was changed.

ℹ️ When updates are made through UI, the object is sent with the changed as well as as all unchanged fields. In that case, this webhook is only triggered for the values that were changed.

Show Custom Field Value

This endpoint retrieves the value of a custom field for a specific employee. To make a successful call, you need to provide the custom field ID as well as the employee's employment ID.

{
  "data": {
    "custom_field_value": {
      "custom_field_id": "01c0e4d2-f41b-11ed-9d3f-cb3ecccebb58",
      "value": "UXH34HG"
    }
  }
}

In case the value returned shows null, it is an indication that no value was provided for this employee, so you can use the update custom field value endpoint to add the required values.