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

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.affinda.com/feedback

```json
{
  "path": "/configuration/picklists",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Picklist Fields

> Configure picklist fields in Affinda to constrain extracted values to a fixed list of options, including hard-coded, dynamic, and API-driven picklists.

## Overview

Affinda’s data-mapping capability lets you normalise extracted values against your own lists, giving you cleaner data and fewer downstream corrections.

## When to choose each type

| Data Type   | Data format                                                 | Value prediction mechanism                              |
| ----------- | ----------------------------------------------------------- | ------------------------------------------------------- |
| Options     | Short, fixed list (≈ 50 values or fewer)                    | Model predicts the value directly                       |
| Data Source | Larger, often two-dimensional list from a downstream system | Raw data from the document matched by string comparison |

## Options

A field whose **Data Type** is set to **Options** stores a single column of permitted values. Enter the items directly in the field editor. Any value outside this list is flagged during validation.

<img className="block dark:hidden border-2 border-gray-300 rounded-lg" src="https://mintcdn.com/affinda-44/8O48gu_z8QeuNsDM/images/options-light.png?fit=max&auto=format&n=8O48gu_z8QeuNsDM&q=85&s=d59fc1881a4238580905e0a35d1244c8" alt="Options field configuration" width="2068" height="1855" data-path="images/options-light.png" />

<img className="hidden dark:block border-2 border-gray-300 rounded-lg" src="https://mintcdn.com/affinda-44/8O48gu_z8QeuNsDM/images/options-dark.png?fit=max&auto=format&n=8O48gu_z8QeuNsDM&q=85&s=2f4edd065e77811255203030e0bc2320" alt="Options field configuration" width="2078" height="1857" data-path="images/options-dark.png" />

**Best practice tips**

* Keep the list concise.
* Use consistent casing.
* Review periodically to remove unused terms.

## Data Sources

Data Sources serve as lightweight master data tables that you can manage directly within Affinda. Affinda supports CSV, XLSX or JSON files as Data Sources, meaning you can upload anything from supplier registers to nested product catalogues.

<img className="block dark:hidden border-2 border-gray-300 rounded-lg" src="https://mintcdn.com/affinda-44/X0_dfJGu-kAY4WOy/images/datasource-light.png?fit=max&auto=format&n=X0_dfJGu-kAY4WOy&q=85&s=97e3b9c1887fd90cee2861c92c47b142" alt="Edit Data Source dialog" width="3383" height="2645" data-path="images/datasource-light.png" />

<img className="hidden dark:block border-2 border-gray-300 rounded-lg" src="https://mintcdn.com/affinda-44/X0_dfJGu-kAY4WOy/images/datasource-dark.png?fit=max&auto=format&n=X0_dfJGu-kAY4WOy&q=85&s=07dc33665b6983eb571c9cd43e39655c" alt="Edit Data Source dialog" width="3486" height="2663" data-path="images/datasource-dark.png" />

### Creating a Data Source

<Steps>
  <Step title="Upload a CSV, XLSX or JSON file." />

  <Step title="Pick the Key Column">
    A *key column* is the single field in your source table whose values are guaranteed to be unique; it is used by Affinda to reliably identify each record unambiguously.
  </Step>

  <Step title="Pick the Label Column">
    The *label* is the human-readable name stored for each record in a Mapping Data Source; it's what users will see in the validation UI and drop-downs.
  </Step>

  <Step title="Click Save. The system assigns a Data Source ID you can reference in API calls." />

  <Step title="Use Replace Data to overwrite rows later without changing the ID." />
</Steps>

### Learn from user feedback

Under Data Source options, users can enable **Remember selections**. When enabled, the platform records the confirmed value for a given raw-text extraction and automatically reuses that value the next time the same text appears in a new document. This helps speed up future searches, improve suggestions, and ensures user validations contribute to ongoing performance gains.

<Note>
  This option is **enabled by default** for every new Data Source field.
</Note>

### Automating updates

Call `PUT /data-sources/{id}` for full replacement or `PATCH /data-sources/{id}` for incremental updates. Schedule these calls from your integration.

### Mapping document fields

<img className="block dark:hidden border-2 border-gray-300 rounded-lg" src="https://mintcdn.com/affinda-44/8O48gu_z8QeuNsDM/images/mapping-light.png?fit=max&auto=format&n=8O48gu_z8QeuNsDM&q=85&s=8cd8e7ff9309b631070379df3094f282" alt="Matching Criteria dialog" width="3311" height="1226" data-path="images/mapping-light.png" />

<img className="hidden dark:block border-2 border-gray-300 rounded-lg" src="https://mintcdn.com/affinda-44/8O48gu_z8QeuNsDM/images/mapping-dark.png?fit=max&auto=format&n=8O48gu_z8QeuNsDM&q=85&s=d85af92a0642a62a7c92f230cb68fdef" alt="Matching Criteria dialog" width="3300" height="1219" data-path="images/mapping-dark.png" />

<Steps>
  <Step title="Open the field, then Data Source → Configure Matching Criteria." />

  <Step title="Choose the Document Field to match (e.g. Employer Name)." />

  <Step title="Pick the Data Source Property (e.g. Employer Name)." />

  <Step title="Select a Match Type:">
    * **Exact** – strings must be identical.
    * **Partial** – succeeds when the extracted string appears anywhere in the candidate.
    * **Fuzzy** – edit-distance logic allows minor typos.
  </Step>

  <Step title="Tick Required if validation should fail when nothing matches for this criterion." />
</Steps>

<Tip>
  ### Tips for reliable matching

  * Trim whitespace and normalise case in your source files.
  * Ensure the key column is unique.
  * Keep label strings short so they fit comfortably in the UI.
</Tip>

### API reference

```http theme={null}
GET    /data-sources                # List
POST   /data-sources                # Create
PUT    /data-sources/{id}           # Replace all rows
PATCH  /data-sources/{id}           # Update selected rows
DELETE /data-sources/{id}           # Delete
```