Custom fields API

The custom fields API retrieves your employee and contractor custom fields and tabs.

How it works

If your organization has enabled the custom fields add-on, an additional property will be returned for your employees (staff) and contractors organizations and members.

You can retrieve the following information:

Field type Endpoint
All contractor member custom fields GET /customfield/element/sp-member
All contractor organization custom fields GET /customfield/element/sp-org
All employee custom fields GET /customfield/element/staff
All contractor member custom field tabs GET /customfield/tab/sp-member
All contractor organization custom field tabs GET /customfield/tab/sp-org
All employee custom field tabs GET /customfield/tab/staff

To learn more, check our API schema.

Custom fields data types

Each custom field contains a value pair, which consists of the field ID as the key and a string representation as the value.

As custom fields contain a range of data types, the API responds with a JSON-string representation for nested data.

The fields that contain nested data are:

  • Date and Time fields if they contain a date or time range. The JSON-Format is {“start”: “value”, “end”:”value”}
  • Option fields where ‘Multiple Selection’ is activated. The value is a string representation of a JSON-Array in the format. For example, [“value1”, “value2”]
  • Person fields where ‘Multiple Selection’ is activated. The format is a string representation of a JSON-Array containing user identifiers. E.g. [1,2,3].

    ID can either be a contractor member identifier or an employee (staff) identifier. For example, if you add the Person field ‘Contractors from any organization’ to your employee custom fields, we’ll use the GET /customfield/element/staff endpoint to determine whether the identifier represents a contractor member or an employee.
  • If the Person field is set to ‘Single Selection’, the results will be a string representation of an identifier, eg 1
  • Checkbox fields will have a string representation of 1 if the field is selected or 0 if it is not.
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request