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
, oreveryone
.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
, andlink
. - 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
.
- General fields: supports
visibility_scope
: determines who can view the custom field. Possible values are:company_admin_only
andeveryone
.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
tocompany_admin_only
, thedata_entry_access
should be set tocompany_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:So, instead of using the label"options": [ { "label": "your option 1", "value": "016b2e5f-0208-649d-8b7e-c40f8930be93" }, { "label": "your option 2", "value": "016b2e5f-0208-64d8-8b7f-6fad98356129" }, ... ]
your option 1
, you need to use thevalue
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.
Updated 6 days ago