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.

Add contractor member profiles with custom fields

Before you start, add the required custom fields in WhosOnLocation. You can't create new custom fields using the API. 
  1. Load the available custom fields in WhosOnLocation (GET /customfield/element/sp-member).
  2. POST Request to /sp/member with a key that is called customfields, holding the id: value pair of the data.

    Your return will show you the type of contractor member custom field, its ID number, and its name in WhosOnLocation. The example below shows a short-text custom field, titled 'Vehicle Registration', ID number 82. 

    Screen_Shot_2021-05-25_at_10.28.57_AM.png
  3. Fire the POST updating the custom field.

    For example: 
    {
     "name":"contractor member's name",
      "customfields": {
         "82" : "information to add to the custom field"
       }