API: Customizing profile fields

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

  1. Make a GET request to the endpoint /api/users/profile/groups to 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:

  • contact
  • basicInformation
  • work

The parameter sortOrder determines the order of the groups.

user profile information tab overview.png

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.
  • If the name starts with an underscore, the field will be hidden and you don't need to specify a translation. A hidden field requires that the hidden parameter has been set to true.
  • To customize the display names of the profile fields, you need to customize the language key translations. New translations need to be added with a REST API command.
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:
  • TEXT: Pure text
  • EMAIL: Content is given an email link /"mailto:"
  • LINK: Content is displayed as a hyperlink
  • PHONE: Content is automatically checked for validity
  • BIRTHDAY: Date display
  • OPTIONS: Drop-down menu*
  • TIMESTAMP: ISO 8601 formatted timestamp with date, time, and offset information, e.g., 2023-08-02T12:00:05+02:00

*If type is selected as OPTIONS, a drop-down menu must be displayed as an array:

"options": {
"location01": "Atlanta",
"location02": "Basel",
"location03": "Boston"
},

Step 2: Add a new or edit an existing profile field

You can make changes to profile groups and fields as follows:

  1. 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
    } 
    
  2. 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.
  3. Make the desired changes to a profile field or add a new one.
    • In our example, we are adding the field room_number and changing the order of the fields so that the new field is above the company field in the work group.
      { 
          "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
      }          
              
  4. 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.

Screenshot 2023-11-21 at 16.55.57.png

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

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.

Was this article helpful?