ExtendedData are custom employee extension properties created through the HR File configuration interface.

It makes it possible to add custom data to your employees. First, by defining them through extensionUserDefinitions objects, then by setting their value through extendedData objects.

​
Introduction

ExtendedData values can be retrieved through the users API endpoint. They are listed as properties of a JSON object named extendedData.

Such extended data can be of different types and formats (refer to the UserProperties documentation). Here is an example with various format values.

​
Writing on ExtendedData Values

All example payloads described in this section are sent to the /api/v3/users/{userId} API endpoint ({userId} being the ID of the user that should be updated).

Extended data values are READ through the optional extendedData field on the User. But they are WRITTEN through passing their values at the root level of the User object.

Attempting to write on extended-data values through the extendedData User property will NOT work.

​
Simple Single-Value ExtendedData

A “simple” ExtendedData is an extension property that only has one property itself.
A “single-value” ExtendedData is an extension property that does not accept more than one value for each employee.
A

Creating a value for a simple single-value ExtendedData

To update an ExtendedData value that does not exist, you must not specify its Id (or set it to 0).

B

Updating the value of a simple single-value ExtendedData

To update an ExtendedData value that already exists, you must specify the ID of the ExtendedData value.

C

Deleting the value of a simple single-value ExtendedData

To delete the value from an ExtendedData, simply set its value property to null. The ExtendedData value ID must be specified.

​
Simple Multiple-Value ExtendedData

A “simple” ExtendedData is an extension property that only has one property itself.
A “multiple-value” ExtendedData is an extension property that accepts more than one value for each employee.
A

Creating a value for a simple multiple-value ExtendedData

To create a multiple-value ExtendedData value, you must send all the occurrences at the same time and not specify the ID of these occurrences (or set them to 0).

B

Appending values to a simple multiple-value ExtendedData

To add occurrences to a multi-valued ExtendedData value that already exists, all occurrences must be sent at the same time without specifying the IDs of the new occurrences (or setting them to 0).

C

Deleting values from a simple multiple-value ExtendedData

In order to delete some values of an existing multiple-values ExtendedData, you just have to send only the values you want to keep.

Note: sending an empty array results in the deletion of all existing values for this ExtendedData (and employee).

​
Composite Single-Value extendedData

A “composite” ExtendedData is an extension property that has more than one property itself.
A “single-value” ExtendedData is an extension property that does not accept more than one value for each employee.
A

Creating a value for a composite single-value ExtendedData

In order to create a value for an existing composite single-value ExtendedData, send a JSON object whose key is the name of the ExtendedData, and whose value is a JSON object with a value property which in itself is a JSON object setting the value of each of the ExtendedData properties.

When creating a value, the ExtendedData id may be either omitted or set to zero 0.

B

Updating the value of a composite single-value ExtendedData

In order to update a composite ExtendedData value, send ALL of its properties values along their own IDs.

C

Deleting the value of a composite single-value ExtendedData

In order to delete a composite ExtendedData value, send all the properties of the composite ExtendedData along their IDs with their values set to null.

​
Composite Multiple-Value ExtendedData

A “composite” ExtendedData is an extension property that has more than one property itself.
A “multiple-value” ExtendedData is an extension property that accepts more than one value for each employee.
A

Appending a value to a composite multiple-value ExtendedData

In order to create a multiple-value composite ExtendedData, send all the values at the same time while not givin IDs to the new ones (or set them to 0).

B

Deleting some values of a composite multiple-value ExtendedData

In order to delete some or all values of a multiple-value composite extendedData, only send the values to keep. To remove all values, send an empty array.

​
FAQ

​
Retrieve entries from a list type ExtendedData

The UserProperties API can be used to retrieve possible entries from a list of values. However, the ExtensionUserDefinitions API /api/v3/extensionuserdefinitions allows to retrieve more information about the possible entries for list type ExtendedData. The objects returned by this API contain an extensionUserPropertyListEntries property, which is an array containing useful information about the entries in the list:

  • id: numeric value identifying the list entry, which can be inserted into ExtendedData values via the users API;
  • name: lthe text associated with the list entry, translated into the language of the current user;
  • translation: the text associated with the list entry, translated into all available languages:
    • culturedLabels
      • culture.code: the language of the translation (“en-US”, “fr-FR”, “es-ES”, etc)
      • value: the translated text in the specified language

Was this page helpful?

Using the user-properties APIUsing employees' work-contracts