> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.tribalhabits.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom fields

> Read and set your organisation's custom user fields.

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*.

```json theme={null}
"X-Country":"Australia",
"X-State":"Queensland",
"X-Preferred Name":"Jack"
```

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`.

```json theme={null}
"X-Nickname":"John",
"X-Birthdate":"23/01/1980",
"X-Age":27,
"X-Cars":"Toyota;Honda",
```

In responses, Date fields are returned as 'yyyy-mm-dd', Number fields as numbers, and List fields as an array of item names:

```json theme={null}
"X-Nickname":"John",
"X-Birthdate":"1980-01-23",
"X-Age":27.0,
"X-Cars":["Toyota","Honda"],
```

To filter users by a custom field, see the `x-[custom field name]` parameter of [Get all users](/api-reference/users/get-all-users).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.