1. Haiilo Support Center
  2. Add-ons & integrations
  3. REST API

Haiilo API: Edit and configure profile fields

You can customize profile fields in Haiilo using the REST API. The technical documentation for the Haiilo REST API can be found here. Below, we'll show an example of how you can make changes to the profile fields with Postma in just a few steps.

To make changes via API, you need to log in as a super-admin and activate moderator mode. You can also activate moderator mode via an API command if you have permission: PUT /api/users/<id>/moderatorMode

Step 1: Authenticate yourself

Parameter

First of all, you need a bearer_token. This is used to authenticate your subsequent queries and commands. To obtain this, identify yourself via the OAuth2 interface using your Haiilo account. You have the same permissions as in your Haiilo Web environment with API access to Haiilo. So, it makes a difference whether you have activated moderator mode or are logged in as a super-admin.

curl -x POST https://<your-coyo-domain>/api/oauth/token?grant_type=password&username=<loginName>&password=<password>

1.1.jpg

Authorization

On the second tab, "Authorization", select the type "Basic Auth" and enter your Haiilo API client ID in the fields. You can find this in the Haiilo Administration under API Clients.

22.jpg

If you now click on "Send", the answer should look something like this.

{ 
  "access_token": "d3cd7b86-234b-4037-9f9f-6083b4df355e", 
  "token_type": "bearer", 
  "refresh_token": "aa2c35f7-4448-46af-94d5-6427d777ada7", 
  "expires_in": 3599, 
  "scope": "read write" 
}

Copy the access token from the response without quotation marks.

Step 2: Send profile fields query

Open a new tab and select a "GET" command in the drop-down menu, enter the following command, and paste your copied token.

curl -x GET https://<your-coyo-domain>/api/users/profile/groups

On the "Authorization" tab, select the type Bearer Token and paste your key in the corresponding field. The response that you get from Haiilo should look something like this:

[
  { 
    "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 
      }, 
      { 
        "name": "website", 
        "type": "LINK", 
        "order": 7, 
        "overview": false, 
        "important": false, 
        "userChooser": false, 
        "searchAggregation": false 
      } 
    ], 
    "modifiable": false 
  }, 
  { 
    "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": "_employedSince", 
        "type": "DATE", 
        "order": 2, 
        "overview": false, 
        "important": false, 
        "userChooser": false, 
        "searchAggregation": false,
        "hidden": true 
      }   
    ],
    "modifiable": true 
  } 
]

This JSON contains a list of all of the profile fields that you can also see in your Haiilo environment as a user. Profile fields marked as "hidden" will not be shown. The profile fields are divided into three groups as a default setting:

  • "contact"
  • "basicInformation"
  • "work"

The order of the groups is determined by the parameter "sortOrder".

In the following screenshot, you can see what the JSON looks like in Haiilo.

44.jpg 

 

Our "fields" parameters

As you can see in the example output from the JSON, here are many more parameters than just the name of the field. We explain the possible customizations to you below: 

By default, all of the parameters - except for the order ("order") - are set to false, i.e., deactivated.

  • overview: Content is displayed in the overview of the list of colleagues and indexed for the search in the list of colleagues (from v25)
  • important: Content is displayed in the user profile, "Activities" tab
  • userChooser: Content is displayed with the @mention of a user
  • immutable: Content cannot be edited
  • searchAggregation: Content can be set as a filter in the list of colleagues
  • searchAggregationOrder: Order of the displayed filter options in the list of colleagues
  • order: Order of the displayed profile fields
  • name: The language key required for Haiilo translations. If the name starts with an underscore, the field will be hidden. In this case, you don't need to specify a translation. A hidden field requires that the "hidden" parameter has been set to "true".
  • hidden: The field is hidden and will not be visible. This requires the "name" to start with an underscore.

Note:
To customize the display names of the profile fields, you need to customize the language keys in Administration: "Administration" > "Languages" > "Translations" 

New translations must be added with a REST API command.

  • type: Formatting type for the content:
    • TEXT: Pure text
    • EMAIL: Content is given an e-mail 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 

Note:
A drop-down menu must be displayed as an array.

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

Step 3: Customization of the profile fields

To make the desired changes, copy the corresponding profile field group, open a new tab, and paste all parameters into the "body". Make the desired changes and then execute what's known as a "PUT" command.

Below is an example of what customization in the profile field group "work" would look like if we want to display in which rooms colleagues can be found. You have two options: Either rename a field you don't need or create a new one. In both cases, it's important that you copy the entire group from "body" in step 2. Starting with the curly bracket:

{
  "id": "xxxxx",
  …

and ending with the closing curly bracket:

  "modifiable": true
}

A complete individual profile field looks like this:

{
  "name": "about",
  "type": "TEXTAREA",
  "order": 3,
  "overview": false,
  "important": false,
  "userChooser": false,
  "searchAggregation": false
} 

Note:
One frequent source of error is the syntax. It's best to check one more time:

  • Are all of the brackets closed?
  • Are the parameters in quotation marks?
  • Are there commas between the individual fields in the list?

Now make the desired changes or expansions in the HTML and enter the following command in the URL bar. Please note that you add the ID of the group to be changed at the end.

curl -x PUT https://<your-coyo-domain>/api/users/profile/groups/<group-id>

In our example, we add the field "Room number" and also change the order of the fields so that the new field "Room number" is above the field "Company".

{ 
  "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": 2, 
      "overview": false, 
      "important": false, 
      "userChooser": false, 
      "searchAggregation": false 
    }, 
    { 
      "name": "roomnumber", 
      "type": "TEXT", 
      "order": 1, 
      "overview": false, 
      "important": false, 
      "userChooser": false, 
      "searchAggregation": false 
    }  
  ], 
  "modifiable": true 
}

Step 4: Complete the field 

To complete the new field straight away, open another "POST" command and add the "value" in the "body".

curl -x POST https://<your-coyo-domain>/api/users/<user-ID>/profile/fields
{ 
  "roomnumber" : "41" 
}

The result then looks as follows:

55.jpg

As you can see, the field now has the name "USER.ROOMNUMBER". This is due to the Multi-Language feature in Haiilo, which works using language keys. This new language key has now been added by us, and we will now give it a distinct name in every language.

Step 5: Add language key

Review the below instructions for adding a language key:

Make profile fields searchable in the colleague search

From Cloud version 25, you can use the search in the colleague overview to also search for expertise. This requires setting the field "overview" to "true" in the fields configured via API. 

{
 "name": "about",
 "type": "TEXTAREA",
 "order": 3,
 "overview": true,
 "important": false,
 "userChooser": false,
 "searchAggregation": false
} 

Note about the user profile widget

In the user profile widget, only the standard Haiilo fields can be displayed: Email, Phone number (phone) and Job title (jobTitle). As soon as you change or replace these profile fields, they cannot be displayed in the widget anymore. 

Was this article helpful?