1. Haiilo Support Center
  2. Features & capabilities
  3. REST API

Haiilo API: Edit and configure profile fields

You can customize profile fields in Haiilo using the REST API. You can get a detailed insight into the technical documentation for the REST API here. 

We recommend the program Postman for the connection to Haiilo. Another alternative would be the program cURL.

We use an example here to show you how you can make changes in just a few steps. All of the screenshots that you can see in this article come from the program Postman.

Note:
To make changes via API, you need to log in as a super-admin and activate moderator mode. You can also activate moderator directly via API command if you have the permission for this:

PUT /api/users/<id>/moderatorMode

Step 1: Authenticate yourself

Parameter

First of all, you need what’s known as your 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. 

Please note that 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 your 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 here without quotation marks.

Step 2: Send profile fields query

Open a new, overarching 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 
      } 
    ],
    "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. 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 how 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 

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. e.g. hyperlinks are linked
    • 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
       

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 now make the desired changes, copy the corresponding profile field group, open a new tab and paste all of the parameters into the "body" . Make the desired changes and then execute what’s known as a "PUT" command.

Here’s an example of what customization in the profile field group "work" would look like. We want to display in which rooms colleagues can be found.

You now have two options: Either rename a field that 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 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

We have one instruction here 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 you to set 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?