Skip to main content
Organisations may configure custom fields to be associated with users to collect additional information such as demographics, organisational structure, etc. When configured, the corresponding attribute/value pairs are included in all user API responses and can be set in calls to create and update. Custom field names are prefixed with X- and any spaces are kept, so, for example, a custom field called Preferred Name is denoted by X-Preferred Name. The examples assume an organisation has configured 3 custom fields called Country, State and Preferred Name.
When filtering by a custom field with spaces in its name, URL-encode the spaces in the query parameter, eg x-preferred%20name=Jack. When creating or updating users, the custom field name after X- must match the field’s display name exactly (including case). Custom field names that do not match are ignored. Custom Fields values must be formatted by their respective types:
  • String - any characters
  • Date - In one of the following forms ‘dd/mm/yyyy’, ‘dd/mm/yy’, ‘yyyy-mm-dd’
  • Number - In form ‘nn’ or ‘nn.mm’
  • List - Semi-colon delimited list of named list items: ‘itemA;itemB’. List item names are matched case-insensitively and must already exist in your portal; you cannot create new list items through this API. An unknown list item returns 400.
In responses, Date fields are returned as ‘yyyy-mm-dd’, Number fields as numbers, and List fields as an array of item names:
To filter users by a custom field, see the x-[custom field name] parameter of Get all users.