# Fields



The following sections on this page document and describe how you can work with the fields on a Matter or Contract.

## What are fields?

Fields represent the custom data that users can add to Matters and Contracts based on their type (Matter Type or Contract Type).

There are two types of fields; LawVu fields and custom fields. LawVu fields are available by default in a new LawVu environment, while custom fields are created by organization administrators for use by your organization.

More information about fields can be found on the [help site](https://help.lawvu.com/en/collections/3686578-fields)

## How to use fields in the LawVu API

Matters and Contracts expose a `fields` property which contains a [key](#field-api-names)/[value](#field-value-shapes) pair of the fields that are currently available on the Matter Type or Contract Type that the Matter or Contract is currently for.

When interacting with a given field, you can reference the field by the Field API Name, and provide a value for it in the correct shape for the given field type. This is supported for both creating, and updating fields.

### Field API Names

Field API Names are a specific identifier that can be set by a user against a field via the LawVu website so that you can control how you reference fields and allow for these references to be consistent between sandbox and production environments.

To find out more about how to set a field API name, refer to the [help page](https://help.lawvu.com/en/articles/11548695-working-with-field-api-names)

### Field types

The table below maps each LawVu application field type to its API type, describes what it represents, and shows whether its options can be managed via the API.

| API type | LawVu application type | Description | Supports option management | Properties |
|  --- | --- | --- | --- | --- |
| Text | Long Text | Multi-line text | - | - |
| Text | Short Text | Single line text | - | - |
| Decimal | Currency | Monetary value | - | - |
| Decimal | Number | Numeric value | - | - |
| Decimal | Slider | Numeric slider | - | - |
| Boolean | Checkbox | True/false toggle | - | - |
| Boolean | Urgent | True/false toggle | - | - |
| Date | Datepicker | Date value (midnight only) | - | - |
| Option | Billing Method | Single selection from a fixed list | - | - |
| Option | Contract Entity | Single selection from a list | ✓ | - |
| Option | Department | Single selection from a list | ✓ | `parentId` (integer) |
| Option | Dropdown | Single selection from a list | ✓ | - |
| Option | Fee Arrangement | Single selection from a fixed list | - | - |
| Option | Invoice Recipient | Single selection from a list | ✓ | - |
| Option | Litigious Outcome | Single selection from a fixed list | - | - |
| Option | Lookup | Single selection from a list | ✓ | - |
| Option | Priority | Single selection from a fixed list | - | - |
| Option | Radio Group | Single selection from a list | ✓ | - |
| Option | Region | Single selection from a list | ✓ | - |
| Multi Option | Checkbox List | Multiple selections from a list | ✓ | - |
| Multi Option | Lookup (multi) | Multiple selections from a list | ✓ | - |
| User | Person | A user account in LawVu | - | - |


### Field value shapes

The following shows the JSON shape for each API field type when reading or writing field values on a Matter or Contract.

#### Text

Represents any text string, both single line and multi line.


```json
"fields": {
    "my_text_field": "my text value",
}
```

#### Decimal

Represents any number based value. Supporting integers, double, floats and decimals.


```json
"fields": {
    "my_decimal_field": 78659.84,
}
```

#### Boolean

Represents any boolean value.


```json
"fields": {
    "my_boolean_field": true,
}
```

#### Date

Represents a date value. The only accepted time portion is midnight. Any other times are not supported.


```json
"fields": {
    "my_date_field": "2025-05-06",
    "my_date_midnight_field": "2025-05-06T00:00:00",
}
```

#### Option

Represents a single selection option which aligns with a pick list of predefined values. e.g. A dropdown


```json
"fields": {
    "my_option_field": {
      "label": "Option 1",
      "value": "option_1"
    },
}
```

#### Multi Option

Represents multiple selected options which align with a pick list of predefined values. e.g. A checkbox list


```json
"fields": {
    "my_multioption_field": [
      {
        "label": "Option A",
        "value": "option_a"
      },
      {
        "label": "Option D",
        "value": "option_d"
      }
    ],
}
```

#### User

Represents a user account in LawVu.


```json
"fields": {
    "my_user_field": {
      "email": "api.developer@lawvu.com",
      "firstName": "Api",
      "id": "f0f1e06e-3005-4093-af7f-1934d55617e1",
      "lastName": "Developer",
      "organizationId": 8134
    }
}
```

## Managing option based fields

Option and Multi Option fields have a list of selectable values. The LawVu API provides endpoints for managing these options - allowing you to list, retrieve, create, update, and delete them.

> **Note:** Creating, updating, and deleting field options generally requires an **organization admin** role. Listing options is available to all authenticated users.


Each field option is returned with the following properties:

| Property | Description |
|  --- | --- |
| `label` | The human-readable display name of the option |
| `value` | A system-generated identifier used to reference the option when setting it on a Matter or Contract |
| `properties` | Additional metadata for certain field types - see [Property bags](#property-bags) below |


Refer to the [field types table](#field-types) for which field types support option management and what properties are available. Listing options supports OData query options for filtering, sorting, and pagination - see [Field Options](/docs/guides/odata#field-options) in the OData guide for details.

### Property bags

Some option field types return additional metadata alongside the standard `label` and `value` properties. This metadata is surfaced in the `properties` object on the field option. When creating or updating options for these field types, you can also supply `properties` in the request body. Refer to the [field types table](#field-types) for which field types support properties and what properties are available.


```json
{
  "label": "My Option",
  "value": "42",
  "properties": {
    "property1": 10,
    "property2": "sometext"
  }
}
```