> For the complete documentation index, see [llms.txt](https://help.fairmarkit.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.fairmarkit.com/admin/data-fields.md).

# Data Fields

Create reusable datasets and use them in forms.

## Overview

Data Fields let your organization capture structured business information in Fairmarkit. Administrators can configure fields to standardize user input and support customer-specific processes.

Use Data Fields for business units, cost centers, regions, categories, requester details, project attributes, accounting information, and other organization-specific values.

Depending on your configuration, a Data Field value may be entered by a user. It may also come from an integration or other context. Fairmarkit stores it with the request or maps it into a sourcing event.

### Create and populate a dataset

Go to **Administration → Data Fields**, then select **Create field**.

{% hint style="info" %}
Creating a Data Field and integrating it are separate activities. A field can exist without an external-system connection. Integration mappings require additional configuration.
{% endhint %}

On the **General** tab, set:

* **Title** — the name shown to administrators. Up to 255 characters.
* **Slug** — the unique dataset identifier, such as `cost-centers`. Lowercase letters, numbers, and hyphens only (`^[a-z0-9-]*$`), up to 50 characters.
* **Active** — only active datasets appear when configuring a field.

You can change a slug later in Edit, and the dataset's route is rebuilt automatically. Schema references are not — any schema whose `datafieldSlug` points at the old value keeps pointing at it and stops loading options. If you rename a slug, update every schema that references it.

On the **Field Schema** tab, define each item's properties. A cost-centers dataset might include `code`, `name`, `owner`, and `region`.

A new dataset starts with a default schema of one required property, `title` (string). Replace or extend it to match the data you're loading.

Use the visual schema builder to build the schema. It validates definitions as you edit and rejects invalid schemas on save.

#### Add items

Add items in either of these ways:

* Select **Create item** on the dataset page to add an individual item.
* Use the Data Fields API to load items in bulk.

Every item is validated against the Field schema when created. Invalid items are rejected.

Items become available everywhere the dataset is referenced. You do not need to update templates.

### Where Data Fields are used

Active datasets are available in project templates, request schemas, and event schemas.

1. Add a custom field in the visual schema builder.
2. Set the field type to **Data Field**.
3. In **Data Field**, select the dataset from **Slug**.
4. Select the properties to show in **Preview**.

The field renders as a searchable dropdown. Selecting an option stores the full item as an object on the form.

### Configure Preview

Preview controls the text shown for each option and selected value.

* Selected properties are comma-separated.
* Properties appear in selection order.
* The same order controls option sorting when items are loaded from the API.

For example, previewing `code` then `name` displays `CC-1042, Facilities — EMEA`.

Use one or two properties where possible. Three or more properties can make options difficult to scan.

### Configure schemas directly

For direct schema editing, use a `fieldset` custom field with the `datafield` variant.

<table><thead><tr><th width="200.80859375">Property</th><th>Description</th></tr></thead><tbody><tr><td><code>inputType</code></td><td>Must be <code>fieldset</code>.</td></tr><tr><td><code>fieldsetVariant</code></td><td>Must be <code>datafield</code>.</td></tr><tr><td><code>datafieldSlug</code></td><td>Dataset slug used to load options.</td></tr><tr><td><code>datafieldPreview</code></td><td>Ordered property names used in the option label. Each name must be a nested property key.</td></tr><tr><td><code>fieldsetFilter</code></td><td>Optional static / schema / external rules that limit which items are shown. </td></tr><tr><td><code>properties</code></td><td>Stored-value shape. Include every property needed after selection.</td></tr><tr><td><code>priceBooksFilterKey</code></td><td>Optional. Filters the price book catalog by the selected item. Valid only on <code>fieldsetVariant: datafield</code> — setting it on a <code>select</code> fails validation.</td></tr></tbody></table>

```json
"cost_center": {
  "type": "object",
  "title": "Cost center",
  "properties": {
    "code": { "type": "string" },
    "name": { "type": "string" }
  },
  "x-jsf-presentation": {
    "inputType": "fieldset",
    "fieldsetVariant": "datafield",
    "datafieldSlug": "cost-centers",
    "datafieldPreview": ["code", "name"]
  }
}
```

{% hint style="warning" %}
Each `datafieldPreview` value must exist in `properties`. Properties absent from `properties` are not stored.
{% endhint %}

### Filter displayed items

Items include custom tags. Use tags to control which options users see.

Filters can use:

* Fixed values.
* Values from other form fields.
* External context, such as integration data or user-profile values.

Configure filters with `fieldsetFilter`. Work with your Fairmarkit Technical Architect when designing your first filters.

{% hint style="info" %}
Filters limit one field by tags or context. They do not create dependencies between data fields.
{% endhint %}

### Integrating Data Fields

Data Fields can use external-system data. Integration setup is not fully self-service.

Administrators can configure the field label, type, required status, options, and supported settings. Connecting a Data Field to an external system may require Fairmarkit configuration.

Common integration needs include:

* Prefilling a Data Field from an upstream system.
* Mapping source data into a Fairmarkit Data Field.
* Synchronizing users, accounting values, or organizational data.
* Mapping a Data Field from Intake into a sourcing event.
* Making a Data Field available to a downstream integration or API workflow.

A Fairmarkit Technical Architect or Services representative may need to configure the mapping. This work defines how external data matches the Fairmarkit schema. It may also require an external payload or integration logic.

If you only need to create or modify a field, your Fairmarkit administrator may manage it in schema configuration.

If a field exchanges data with another system, contact your Fairmarkit representative. They can confirm whether Technical Architect support is required.

### Load data at scale

Use the API for datasets with more than a few dozen items.

| Endpoint                                     | Method   | Purpose                               |
| -------------------------------------------- | -------- | ------------------------------------- |
| `/api/v1/data-fields/dataset`                | `POST`   | Create a dataset.                     |
| `/api/v1/data-fields/dataset`                | `GET`    | List or search datasets.              |
| `/api/v1/data-fields/dataset/{slug}`         | `GET`    | Retrieve a dataset.                   |
| `/api/v1/data-fields/{slug}/items`           | `GET`    | List, search, filter, and sort items. |
| `/api/v1/data-fields/{slug}/items`           | `POST`   | Add items in bulk.                    |
| `/api/v1/data-fields/{slug}/items/{item_id}` | `PATCH`  | Update one item.                      |
| `/api/v1/data-fields/{slug}/items/{item_id}` | `DELETE` | Remove one item.                      |

All endpoints are authenticated and organization-scoped. List endpoints support pagination, filtering, sorting, and search across item values and tags.

Integrated customers often sync data fields from their ERP. This keeps cost centers, GL codes, and entity lists current.

### Current limitations

* **Dependent fields:** One selection cannot narrow another data field. Combine related values in one dataset entry when accuracy matters.
* **Flat-file loading:** Use the UI or API. SFTP and flat-file loading are unavailable.
* **Very large datasets:** Datasets above roughly 100,000 items are not recommended. Contact your Technical Architect before planning at this scale.
* **Field-type changes:** Delete and recreate a field to convert it to or from a data field.

### Best practices

* Retire obsolete items. Dropdowns reflect the dataset exactly.
* Name a slug after the data, not its first form.
* Keep Preview short, but store all required properties.
* Use conditional logic to show fields only when relevant.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.fairmarkit.com/admin/data-fields.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.