> ## 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.
# Learn about expenses custom fields
> When configuring Lucca Expenses, you may add custom fields to `expense-temp-items` and `expense-claim-items`.
## Retrieving the list of customFields enabled for an expense nature
Custom fields activation depends on the expense nature. For example, custom field "Bill back client (bool)" may be activated for travel expenses, but not for team building expenses.
```json List natures w/ customFields theme={null}
GET /api/expenseNatures?fields=id,name,url,customFields.id,customFields.name,customFields.url,customFields.type.tag,customFields.case.tag,customFields.compulsory,customFields.minLength,customFields.maxLength,customFields.defaultValue HTTPS/2
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Accept: application/json
< Response
{
"data": [
{
"id": 1,
"name": "Diner",
"url": "https://example.ilucca.net/api/expenseNatures/49"
"customFields": [
{
"id": "1",
"name": "Bill back client",
"url": "https://example.ilucca.net/api/expenseCustomFields/1",
"type": {
"tag": "Bool"
},
"case": {
"tag": "Insensitive"
},
"compulsory": false,
"minLength": 0,
"maxLength": null,
"defaultValue": "false"
}
]
}
]
}
```
Each custom field is typed, as indicated by the `customField.type.tag` discriminator:
| Type.Tag | Expected value (code) - actual values are always strings | Example |
| :----------- | :--------------------------------------------------------------------------------- | :-------------------- |
| `String` | Any text string as long as it conforms to `MinLength` and `MaxLength`. | `"test"` |
| `Bool` | Stringified boolean. | `"true"` or `"false"` |
| `Int` | Stringified integer | `"48"` |
| `Float` | Stringified float. | `"18.25"` |
| `Digits` | String of numbers, that must potentially conform to a `minLength` and `maxLength`. | `"0495846"` |
| `ListValues` | String among a list (i.e. enum; refer to `values` dictionary property). | `"foo"` |
```yaml Schema theme={null}
title: customField
type: object
properties:
id:
type: string
description: Unique identifier of the custom field. Keep in mind one custom field can apply to multiple expense natures.
name:
type: string
description: Name of the custom field
url:
type: string
format: uri
type:
type: object
properties:
tag:
type: string
enum: [String, Bool, Int, Float, Digits, ListValues]
description: |-
- `String`: any text string;
- `Bool`: stringified boolean value, i.e. `"true"` or `"false"`.
- `Int`: stringified integer value, i.e. `"234"`.
- `Float`: stringified float value, i.e. `"0.123"`.
- `Digits`: string of numbers, i.e. "0123456789".
- `ListValues`: string among an list of accepted values (i.e. enumeration).
case:
type: object
properties:
tag:
type: string
enum: [Insensitive, Uppercase, Lowercase]
description: Case sensitivity.
compulsory:
type: boolean
description: Whether a value MUST be set on expenses of this expense-nature or not.
default: false
minLength:
type: [integer, "null"]
minimum: 0
default: null
description: Minimum number of characters accepted for a value.
maxLength:
type: [integer, "null"]
minimum: 0
descritpion: Maximum number of characters accepted for a value.
defaultValue:
type: string
description: Explicit default for values.
values:
type: object
description: Dictionary valueCode => valueDisplayName. Lists the enum values for a `ListValues` typed custom field.
additionalProperties:
type: string
```
```json String theme={null}
{
"data": [
{
"id": 1,
"name": "Diner",
"url": "https://example.ilucca.net/api/expenseNatures/49",
"customFields": [
{
"id": "1",
"name": "Restaurant name",
"url": "https://example.ilucca.net/api/expenseCustomFields/1",
"type": {
"tag": "String"
},
"case": {
"tag": "Insensitive"
},
"compulsory": false,
"minLength": 0,
"maxLength": null,
"defaultValue": "",
"values": null
}
]
}
]
}
```
```json Bool theme={null}
{
"data": [
{
"id": 1,
"name": "Diner",
"url": "https://example.ilucca.net/api/expenseNatures/49",
"customFields": [
{
"id": "2",
"name": "Bill back client",
"url": "https://example.ilucca.net/api/expenseCustomFields/2",
"type": {
"tag": "Bool"
},
"case": {
"tag": "Insensitive"
},
"compulsory": false,
"minLength": 0,
"maxLength": null,
"defaultValue": "false",
"values": {
"true": "Yes",
"false": "No"
}
}
]
}
]
}
```
```json Digits theme={null}
{
"data": [
{
"id": 1,
"name": "Diner",
"url": "https://example.ilucca.net/api/expenseNatures/49",
"customFields": [
{
"id": "3",
"name": "Guests",
"url": "https://example.ilucca.net/api/expenseCustomFields/3",
"type": {
"tag": "Int"
},
"case": {
"tag": "Insensitive"
},
"compulsory": false,
"minLength": null,
"maxLength": null,
"defaultValue": 0,
"values": null
}
]
}
]
}
```
```json Digits theme={null}
{
"data": [
{
"id": 1,
"name": "Diner",
"url": "https://example.ilucca.net/api/expenseNatures/49",
"customFields": [
{
"id": "4",
"name": "Phone number",
"url": "https://example.ilucca.net/api/expenseCustomFields/4",
"type": {
"tag": "Digits"
},
"case": {
"tag": "Insensitive"
},
"compulsory": false,
"minLength": 10,
"maxLength": 10,
"defaultValue": "false",
"values": null
}
]
}
]
}
```
```json ListValues theme={null}
{
"data": [
{
"id": 1,
"name": "Diner",
"url": "https://example.ilucca.net/api/expenseNatures/49",
"customFields": [
{
"id": "5",
"name": "Michelin Stars",
"url": "https://example.ilucca.net/api/expenseCustomFields/5",
"type": {
"tag": "ListValues"
},
"case": {
"tag": "Sensitive"
},
"compulsory": false,
"minLength": null,
"maxLength": null,
"defaultValue": "false",
"values": {
"one": "⭐",
"two": "⭐⭐",
"three": "⭐⭐⭐"
}
}
]
}
]
}
```
***
## Retrieving the customFields values for an expense
In order to retrieve the list of customField values for an `ExpenseTempItem` or an `ExpenseClaimItem`, simply add "customFields" to the list of fields requested through the `?fields` query parameter:
```http ExpenseTempItem theme={null}
GET /api/v3/expenseTempItems?fields=id,customFields HTTPS/2
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Accept: application/json
```
```http ExpenseClaimItem theme={null}
GET /api/v3/expenseclaimitems?fields=id,customFields HTTPS/2
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Accept: application/json
```
The `customFields` field you'll retrieve is a JSON object whose keys are the IDs of the `customField`.
```json Bool theme={null}
{
"id": 23,
"customFields": {
"2": {
"code": "false",
"name": "No"
}
}
}
```
```json ListValues theme={null}
{
"id": 23,
"customFields": {
"5": {
"code": "two",
"name": "⭐⭐"
}
}
}
```
***