You can use Haiilo's API to customize profile fields. Below, we'll show an example of how you can add or change a profile field with Postman in just a few steps.
To make calls to the Haiilo API, you need to authenticate first. You can find detailed information about authenticating and using the API here.
Step 1: List profile fields
- Make a GET request to the endpoint
/api/users/profile/groupsto get a list of all profile groups and their fields.
Understand the response
You can see an example of what the response might look like below:
-
[
{
"id": "93977140-cf43-490d-b754-e9dca5cda06c",
"name": "basicInformation",
"sortOrder": 1,
"fields": [
{
"name": "birthday",
"type": "BIRTHDAY",
"order": 0,
"overview": false,
"important": false,
"userChooser": false,
"searchAggregation": false
},
{
"name": "languages",
"type": "TEXT",
"order": 1,
"overview": false,
"important": false,
"userChooser": false,
"searchAggregation": false
},
{
"name": "homeTown",
"type": "TEXT",
"order": 2,
"overview": false,
"important": false,
"userChooser": false,
"searchAggregation": false
}
],
"modifiable": true
},
{
"id": "183c5478-4cd3-49d4-bd2e-322d66116cef",
"name": "contact",
"sortOrder": 0,
"fields": [
{
"name": "phone",
"type": "PHONE",
"order": 0,
"overview": true,
"important": true,
"userChooser": false,
"searchAggregation": false
},
{
"name": "mobile",
"type": "PHONE",
"order": 1,
"overview": false,
"important": false,
"userChooser": false,
"searchAggregation": false
},
...
],
"modifiable": true
},
]
The JSON response corresponds to the profile fields you can see in a user's profile on the platform. The profile fields are divided into three groups by default:
contactbasicInformationwork
The parameter sortOrder determines the order of the groups.
Understand the parameters
There are parameters for each profile field. By default, most parameters - except for order - are set to false, i.e., deactivated. These are the possible customizations:
| Parameter | Description and notes |
overview |
If true, content is displayed in the user profile card and indexed for the search in the Colleagues list |
important |
If true, content is displayed on the left-side box in the user profile Activities tab |
userChooser |
If true, content is displayed in the pop-up that shows when @mentioning a user |
immutable |
If true, content cannot be edited |
searchAggregation |
If true, content is added as a filter in the Colleagues list |
searchAggregationOrder |
Defines the order of the displayed filter options in the Colleagues list |
order |
Order of the displayed profile fields inside the profile group |
name |
The language key required for Haiilo translations.
|
hidden |
If true, the field is hidden and won't be visible. Also requires that the name parameter starts with an underscore. |
type |
Determines the content's formatting type:
*If "options": {
|
Step 2: Add a new or edit an existing profile field
You can make changes to profile groups and fields as follows:
- Copy a complete profile field group from the response, starting from the first { to the last } for that group. E.g.,
{ "id": "79b14834-c6c9-4447-bf34-146ef3475592", "name": "work", "sortOrder": 2, "fields": [ { "name": "jobTitle", "type": "TEXT", "order": 0, "overview": false, "important": false, "userChooser": true, "searchAggregation": false }, { "name": "company", "type": "TEXT", "order": 1, "overview": false, "important": false, "userChooser": false, "searchAggregation": false }, { "name": "department", "type": "TEXT", "order": 2, "overview": true, "important": false, "userChooser": true, "searchAggregation": true, "searchAggregationOrder": 1 }, { "name": "office", "type": "TEXT", "order": 3, "overview": true, "important": false, "userChooser": true, "searchAggregation": true, "searchAggregationOrder": 2 }, { "name": "location", "type": "TEXT", "order": 4, "overview": false, "important": true, "userChooser": false, "searchAggregation": true, "searchAggregationOrder": 3 }, { "name": "education", "type": "TEXT", "order": 5, "overview": false, "important": false, "userChooser": false, "searchAggregation": false } ], "modifiable": true } - Enter the entire copied profile field group in the request body. Even if you only edit one field, the whole group needs to be included as a PUT request overwrites the current state.
- Make the desired changes to a profile field or add a new one.
- In our example, we are adding the field
room_numberand changing the order of the fields so that the new field is above thecompanyfield in theworkgroup.{ "id": "79b14834-c6c9-4447-bf34-146ef3475592", "name": "work", "sortOrder": 2, "fields": [ { "name": "jobTitle", "type": "TEXT", "order": 0, "overview": false, "important": false, "userChooser": true, "searchAggregation": false }, { "name": "room_number", "type": "TEXT", "order": 1, "overview": false, "important": false, "userChooser": false, "searchAggregation": false }, { "name": "company", "type": "TEXT", "order": 2, "overview": false, "important": false, "userChooser": false, "searchAggregation": false }, { "name": "department", "type": "TEXT", "order": 3, "overview": true, "important": false, "userChooser": true, "searchAggregation": true, "searchAggregationOrder": 1 }, { "name": "office", "type": "TEXT", "order": 4, "overview": true, "important": false, "userChooser": true, "searchAggregation": true, "searchAggregationOrder": 2 }, { "name": "location", "type": "TEXT", "order": 5, "overview": false, "important": true, "userChooser": false, "searchAggregation": true, "searchAggregationOrder": 3 }, { "name": "education", "type": "TEXT", "order": 6, "overview": false, "important": false, "userChooser": false, "searchAggregation": false } ], "modifiable": true }
- In our example, we are adding the field
- Make a PUT request to the endpoint
/api/users/profile/groups/<group_id>. The<group_id>is located at the top of the group's response after"id"(bolded in the above example)
You should receive a response showing the profile group with your changes included. Check the platform to see if your changes have been applied.
If you run into any errors when calling the API, one frequent source of error is the body syntax. Please ensure that all brackets are closed, all parameters are in quotation marks, and that there are commas between the individual fields in the list.
Step 3: Add or edit a language key
- For a new field, you need to create a new translation to change the field's name on the platform. Review Haiilo API: Import translations for instructions.
- For an existing field, you can edit the existing language key. Review Customizing interface text for instructions.
Example field: Pronouns
Another example of a new profile field can be to add a Pronouns field. For this, you can use the below request:
{
"name": "haiilo_pronouns",
"type": "TEXT",
"order": 1,
"overview": true,
"important": false,
"userChooser": false,
"searchAggregation": false
}
As long as the name is input as haiilo_pronouns, the pronouns will be added after the user's display name in the profile card (see image above).
If you have set up your Haiilo platform after version 45.0.90, the Pronouns field is automatically included for your users, and you do not need to add it.