> ## Documentation Index
> Fetch the complete documentation index at: https://developers.lucca.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Using the user-properties API

> The UserProperties API can be used to retrieve information on the structure of all the properties that can be attached to a user. This API is read-only: only the HTTP `GET` request method is therefore available on this API.

The `UserProperties` API can be used to retrieve information on the structure of all the properties that can be attached to a user. This API is read-only: only the HTTP `GET` request method is therefore available on this API.

## UserProperty structure

```json theme={null}
{
    "id": "codeIdentifiantLaPropriete",
    "name": "Property name in logged-in user culture",
    "isMultivalue": false, 
    "isNullable": false, 
    "isReadOnly": true, 
    "category": 0, // see categories section
    "type": 4, // see "Property types and formats" section
    "format": {
        "key": "codeIdentifiantLeFormat"
        // The object sometimes contains other properties, see the section "Property types and formats"
    }
}
```

## Property types and formats

### Type

The `type` property of a UserProperty is an enumeration allowing to know the type of data that it is possible to store within a user property.

* `0` : Boolean ;
* `1` : Integer or list of values ;
* `2` : Numerical ;
* `3` : Date ;
* `4` : Texte ;
* `5` : Objet. Identifies UserProperties containing a value that is not simple, such as another user, an image, or a file. The `format` property described in the section below provides additional information on the type of data.

### Format

The `format` property of a UserProperty designates an object containing various information about how to display and edit a user property.

#### Format of boolean properties

Boolean type properties always have the following format:

```json theme={null}
{ "key": "boolean" }
```

#### Integer Value and Value List Property Formats

Integer value type properties always have the following format:

```json theme={null}
{ "key": "integer" }
```

Properties of type integer can also designate properties of type list of values, to which their format has the key `select`, or `radio` in the case of lists containing only two possible values. The following formats are possible in this case:

* If the property belongs to the native category:

```json theme={null}
{
	"key": "select",
	"entries": [ // Table containing the possible entries for the list of values
		{
			"key": "Female", // Unique character string for this property and identifying the list entry
			"description": "Femme",  // Name of the entry translated into the language of the logged in user
			"descriptions": {  // Translations of the entry in the different languages available
				"fr-FR": "Femme",
				"en-US": "Female"
			}
		},
		{
			"key": "Undefined",
			"description": "Non défini",
			"descriptions": {
				"fr-FR": "Non défini",
				"en-US": "Undefined"
			}
		},
		{
			"key": "Male",
			"description": "Homme",
			"descriptions": {
				"fr-FR": "Homme",
				"en-US": "Male"
			}
		}
	],
}
```

* If the property belongs to the extension category:

```json theme={null}
{
	"key": "select",
	"entries": [ // Table containing the possible entries for the list of values
		{
			"key": 48, // Integer value identifying the list entry
			"description": "Vide", // NName of the entry translated into the language of the logged in user
			"descriptions": { // Translations of the entry in the different languages available
				"fr-FR": "Vide",
                "en-US": "Empty"
			}
		},
		{
			"key": 49,
			"description": "Valeur 1",
			"descriptions": {
				"fr-FR": "Valeur 1",
                "en-US": "Value 1"
			}
		},
		{
			"key": 50,
			"description": "Value 2",
			"descriptions": {
				"fr-FR": "Valeur 2",
                "en-US": "Value 2"
			}
		}
	]
}
```

#### Formats of numeric value type properties

Numeric value type properties can have one of the following formats:

```json theme={null}
{ "key": "numeric" },
{ "key": "money" }
```

#### Format of date-type properties

Date type properties always have the following format:

```json theme={null}
{ "key": "date" }
```

#### Formats of text properties

Text type properties can have one of the following formats:

```json theme={null}
{ "key": "short", "maximumLength": 255 },
{ "key": "superShort", "maximumLength": 50 },
{ "key": "multi", "maximumLength": 4000 },
{ "key": "url", "maximumLength": 4000 },
{ "key": "iban", "maximumLength": 255 },
{ "key": "bic", "maximumLength": 255 },
```

#### Object Type Property Formats

Some properties contain a value retrieved via another Lucca API, in this case their format is as follows:

```json theme={null}
{
	"key": "department" | "user" | "scopeFiltered" | "culture" | "lucca_api_select" | "workcycle",
    // API URL to contact to retrieve possible values
    "url": "/api/v3/departments",
    // Filter to use during the API call to retrieve the correct values
    "filter": "isActive=true"
}
```

File and image type user properties contain a GUID that identifies a file stored on the Lucca server. Example of value:

```json theme={null}
{
	"id": "3411dc37-0242-48ea-9ef7-33a6ec05b4e1",
	"name": "file-name.pdf",
	"href": "https://xxx.local.dev/getFile.ashx?id=3411dc37-0242-48ea-9ef7-33a6ec05b4e1"
}
```

The properties identifying an image or a file have the following formats respectively:

```json theme={null}
{ "format": "picture" },
{ "format": "file" }
```

## Categories

There are different types of `UserProperties`. The `category` property of each `UserProperties` object lets you know to which category a `UserProperties` belongs.

* `0` : Native property ;
* `1` : Attribute property ;
* `2` : Applicative property  ;
* `3` : Extension property (extendedData) ;
* `4` : Analytical axes property ;
* `5` : Password property.

### 0 : Native property

These properties are static and necessary for the proper functioning of Lucca applications. Some of these properties are only reported by the `UserProperties` API if specific Lucca applications are instantiated.
`(~ config)` : depends on application configuration

| Name                            | Availability                                                |
| :------------------------------ | :---------------------------------------------------------- |
| `address`                       | if **Lucca Core HR** (\~ config)                            |
| `allowsElectronicPayslip`       | if **Lucca Payslips**                                       |
| `bankName`                      | always                                                      |
| `bic`                           | if **Lucca Expenses**                                       |
| `birthDate`                     | always                                                      |
| `calendar`                      | always                                                      |
| `civilTitle`                    | always                                                      |
| `corporateCard`                 | if **Lucca Expenses**                                       |
| `csp`                           | if **Lucca Absences**                                       |
| `culture`                       | always                                                      |
| `department`                    | always                                                      |
| `directLine`                    | always                                                      |
| `dtContractEnd`                 | always                                                      |
| `dtContractStart`               | always                                                      |
| `employeeNumber`                | always                                                      |
| `firstName`                     | always                                                      |
| `frenchCarTaxHorsePower`        | if **Lucca Expenses**                                       |
| `frenchMotocyclesTaxHorsePower` | if **Lucca Expenses**                                       |
| `gender`                        | always                                                      |
| `habilitedRoles`                | always                                                      |
| `iban`                          | if **Lucca Expenses**                                       |
| `insuranceNumber`               | if **Lucca Payslips** or if **Lucca Absences** (\~ config)  |
| `jobTitle`                      | always                                                      |
| `lastName`                      | always                                                      |
| `legalEntity`                   | always                                                      |
| `login`                         | always                                                      |
| `mail`                          | always                                                      |
| `manager`                       | if **Lucca Absences** and/or **Lucca Expenses** (\~ config) |
| `nationality`                   | always                                                      |
| `personalAccount`               | if **Lucca Expenses** (\~ config)                           |
| `personalEmail`                 | always                                                      |
| `personalMobile`                | always                                                      |
| `picture`                       | always                                                      |
| `professionalMobile`            | always                                                      |
| `quote`                         | always                                                      |
| `rolePrincipal`                 | always                                                      |
| `seniorityDate`                 | if **Lucca Absences**                                       |
| `site`                          | if **Lucca Absences**                                       |
| `unitSellPrice`                 | if **Lucca Absences** and/or **Lucca Compensation**         |
| `userWorkCycles`                | if **Lucca Timesheets** and/or if **Lucca Absences**        |

### 1 : Attribute properties

Attribute category properties are custom properties that were created through the custom fields admin (`xxx.ilucca.net/admin/extended-datas`). All of these properties are of type text and have a maximum length of 255 characters.

### 2 : Applicative properties

Application properties are specific to a specific Lucca application. The `UserProperties` API will only report these properties if the applications that use them are instantiated. In some cases, certain properties are only available if the relevant application has been configured to use them.

* Example for Lucca Absences : `profile_figgo` ; `manager2`.
* Example for Lucca expenses : `profile_cleemy`.

### 3 : Extension properties (extendedData)

Properties in the extension category, called **ExtendedData**, are custom properties that were created through the extensions admin (`xxx.ilucca.net/directory/settings#/hrfile/properties`) . These properties are basically similar to attribute type properties, but are more comprehensive and can have different types. These properties are only available if the HR Folder is instantiated. More information on the [ExtendedData](./extended-data) documentation page.

### 4 : Analytical axes properties

Properties in the Analytical Axes category are properties that have been created through the Analytical Axes admin (`xxx.ilucca.net/admin/axes`). These properties behave similarly to properties containing a value retrieved via another Lucca API. See the [Formats of object type properties](#formats-des-propetes-de-type-o-...) section.

### 5 : Password properties

This category of properties is only reserved for the `password` property.