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

# Field mapping

> Translate source-specific transaction fields into Matcher's canonical schema so you can compare data consistently across systems.

Field mapping converts source-specific transaction data into Matcher's canonical schema.

This normalization is required to compare transactions across systems and apply matching rules consistently.

## Why field mapping?

***

External systems rarely share the same field names, formats, or sign conventions. For example:

| System | Amount field        | Date field         | Reference field |
| ------ | ------------------- | ------------------ | --------------- |
| Bank A | `transactionAmount` | `postDate`         | `checkNumber`   |
| Bank B | `amt`               | `transaction_date` | `ref_num`       |
| ERP    | `AMOUNT_USD`        | `GL_DATE`          | `DOC_NUM`       |

Field maps standardize these variations into a single schema that Matcher can validate, normalize, and match.

## Matcher's standard schema

***

### Required fields

Every transaction must provide these fields after mapping:

| Field            | Type    | Description                                 | Example          |
| ---------------- | ------- | ------------------------------------------- | ---------------- |
| `transaction_id` | String  | Unique identifier within the source         | `"TXN-2024-001"` |
| `amount`         | Decimal | Transaction amount (up to 4 decimal places) | `1234.56`        |
| `currency`       | String  | ISO 4217 currency code                      | `"USD"`          |
| `date`           | Date    | Transaction date (`YYYY-MM-DD`)             | `"2024-01-15"`   |

### Optional fields

| Field          | Type   | Description                       | Example                   |
| -------------- | ------ | --------------------------------- | ------------------------- |
| `reference`    | String | External reference or description | `"Invoice #1234"`         |
| `counterparty` | String | Other party in the transaction    | `"Acme Corp"`             |
| `type`         | String | Transaction direction/type        | `"credit"`, `"debit"`     |
| `category`     | String | Transaction category              | `"payment"`, `"fee"`      |
| `posting_date` | Date   | Posting date                      | `"2024-01-16"`            |
| `value_date`   | Date   | Value/settlement date             | `"2024-01-17"`            |
| `external_id`  | String | External system identifier        | `"BANK-REF-999"`          |
| `metadata`     | Object | Source-specific fields            | `{"department": "sales"}` |

## Creating field maps

***

### Basic field map

Field maps are created for a specific source within a context. The `mapping` object defines how source fields map to Matcher's schema.

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources/{sourceId}/field-maps" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mapping": {
     "Transaction ID": "transaction_id",
     "Amount": "amount",
     "Currency": "currency",
     "Post Date": "date",
     "Description": "reference"
   }
 }'
```

**Response**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
  "sourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "mapping": {
    "Transaction ID": "transaction_id",
    "Amount": "amount",
    "Currency": "currency",
    "Post Date": "date",
    "Description": "reference"
  },
  "version": 1,
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:00:00Z"
}
```

<Tip>API Reference: [Create field map](/en/reference/matcher/create-field-map)</Tip>

## Data transformations

***

Field maps can apply transformations to normalize formats and conventions before matching.

### Available transformations

| Transformation | Description                        | Example                         |
| -------------- | ---------------------------------- | ------------------------------- |
| `uppercase`    | Convert to uppercase               | `"abc"` → `"ABC"`               |
| `lowercase`    | Convert to lowercase               | `"ABC"` → `"abc"`               |
| `trim`         | Remove leading/trailing whitespace | `" abc "` → `"abc"`             |
| `parse_date`   | Parse date by format               | `"01/15/2024"` → `"2024-01-15"` |
| `parse_number` | Parse number with locale           | `"1,234.56"` → `1234.56`        |
| `abs`          | Absolute value                     | `-100` → `100`                  |
| `negate`       | Negate number                      | `100` → `-100`                  |
| `multiply`     | Multiply by factor                 | `100` × `0.01` → `1`            |
| `replace`      | String replacement                 | `"USD$"` → `"USD"`              |
| `extract`      | Regex extraction                   | Extract numbers from string     |
| `default`      | Default if empty                   | `null` → `"UNKNOWN"`            |
| `concat`       | Concatenate fields                 | `field1 + field2`               |

### Transformation examples

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources/{sourceId}/field-maps" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Legacy Bank Format with Transformations",
   "source_type": "csv",
   "mappings": [
     {
       "source_field": "TXN_NUM",
       "target_field": "transaction_id",
       "transformations": [
         {
           "type": "trim"
         },
         {
           "type": "uppercase"
         }
       ]
     },
     {
       "source_field": "AMOUNT",
       "target_field": "amount",
       "transformations": [
         {
           "type": "parse_number",
           "options": {
             "locale": "en-US"
           }
         },
         {
           "type": "multiply",
           "options": {
             "factor": 0.01
           }
         }
       ]
     },
     {
       "source_field": "TXN_DATE",
       "target_field": "date",
       "transformations": [
         {
           "type": "parse_date",
           "options": {
             "format": "MM/DD/YYYY"
           }
         }
       ]
     },
     {
       "source_field": "CURR",
       "target_field": "currency",
       "transformations": [
         {
           "type": "replace",
           "options": {
             "search": "$",
             "replace": ""
           }
         },
         {
           "type": "uppercase"
         },
         {
           "type": "default",
           "options": {
             "value": "USD"
           }
         }
       ]
     }
   ]
 }'
```

**Response**

```json theme={null}
{
  "id": "fmap_002",
  "name": "Legacy Bank Format with Transformations",
  "mappings": [
    {
      "source_field": "TXN_NUM",
      "target_field": "transaction_id",
      "transformations": [
        {
          "type": "trim"
        },
        {
          "type": "uppercase"
        }
      ]
    },
    {
      "source_field": "AMOUNT",
      "target_field": "amount",
      "transformations": [
        {
          "type": "parse_number",
          "options": {
            "locale": "en-US"
          }
        },
        {
          "type": "multiply",
          "options": {
            "factor": 0.01
          }
        }
      ]
    },
    {
      "source_field": "TXN_DATE",
      "target_field": "date",
      "transformations": [
        {
          "type": "parse_date",
          "options": {
            "format": "MM/DD/YYYY"
          }
        }
      ]
    },
    {
      "source_field": "CURR",
      "target_field": "currency",
      "transformations": [
        {
          "type": "replace",
          "options": {
            "search": "$",
            "replace": ""
          }
        },
        {
          "type": "uppercase"
        },
        {
          "type": "default",
          "options": {
            "value": "USD"
          }
        }
      ]
    }
  ]
}
```

### Date format patterns

Common `parse_date` patterns:

| Pattern                | Example input          | Output       |
| ---------------------- | ---------------------- | ------------ |
| `YYYY-MM-DD`           | `2024-01-15`           | `2024-01-15` |
| `MM/DD/YYYY`           | `01/15/2024`           | `2024-01-15` |
| `DD/MM/YYYY`           | `15/01/2024`           | `2024-01-15` |
| `YYYY-MM-DDTHH:mm:ssZ` | `2024-01-15T10:30:00Z` | `2024-01-15` |
| `MMM DD, YYYY`         | `Jan 15, 2024`         | `2024-01-15` |
| `DD-MMM-YYYY`          | `15-Jan-2024`          | `2024-01-15` |

## Computed fields

***

Use computed fields when values must be derived rather than copied from a single source field.

### Concatenation

```json theme={null}
{
  "target_field": "reference",
  "computed": true,
  "expression": {
    "type": "concat",
    "fields": [
      "DOC_TYPE",
      "DOC_NUM"
    ],
    "separator": "-"
  }
}
```

**Input:** `DOC_TYPE: "INV"`, `DOC_NUM: "12345"`
**Output:** `reference: "INV-12345"`

### Conditional mapping

```json theme={null}
{
  "target_field": "type",
  "computed": true,
  "expression": {
    "type": "conditional",
    "conditions": [
      {
        "if": {
          "field": "DR_CR",
          "equals": "D"
        },
        "then": "debit"
      },
      {
        "if": {
          "field": "DR_CR",
          "equals": "C"
        },
        "then": "credit"
      }
    ],
    "default": "unknown"
  }
}
```

### Amount sign based on type

```json theme={null}
{
  "target_field": "amount",
  "computed": true,
  "expression": {
    "type": "conditional",
    "conditions": [
      {
        "if": {
          "field": "TXN_TYPE",
          "equals": "DEBIT"
        },
        "then": {
          "type": "negate",
          "field": "AMOUNT"
        }
      }
    ],
    "default": {
      "field": "AMOUNT"
    }
  }
}
```

## Mapping examples by source type

***

### Bank statements (csv)

#### Source format

```csv theme={null}
Transaction ID,Post Date,Description,Amount,Balance
CHK001,01/15/2024,Check #1234,-500.00,10500.00
DEP001,01/15/2024,Mobile Deposit,1500.00,12000.00
FEE001,01/15/2024,Monthly Service Fee,-12.00,11988.00
```

#### Field map

```json theme={null}
{
  "name": "Bank Statement CSV",
  "source_type": "csv",
  "mappings": [
    {
      "source_field": "Transaction ID",
      "target_field": "transaction_id"
    },
    {
      "source_field": "Post Date",
      "target_field": "date",
      "transformations": [
        {
          "type": "parse_date",
          "options": {
            "format": "MM/DD/YYYY"
          }
        }
      ]
    },
    {
      "source_field": "Description",
      "target_field": "reference"
    },
    {
      "source_field": "Amount",
      "target_field": "amount",
      "transformations": [
        {
          "type": "parse_number",
          "options": {
            "locale": "en-US"
          }
        }
      ]
    },
    {
      "target_field": "currency",
      "computed": true,
      "expression": {
        "type": "constant",
        "value": "USD"
      }
    },
    {
      "target_field": "type",
      "computed": true,
      "expression": {
        "type": "conditional",
        "conditions": [
          {
            "if": {
              "field": "Amount",
              "less_than": 0
            },
            "then": "debit"
          }
        ],
        "default": "credit"
      }
    }
  ]
}
```

#### Result

```json theme={null}
[
  {
    "transaction_id": "CHK001",
    "date": "2024-01-15",
    "reference": "Check #1234",
    "amount": -500.0,
    "currency": "USD",
    "type": "debit"
  },
  {
    "transaction_id": "DEP001",
    "date": "2024-01-15",
    "reference": "Mobile Deposit",
    "amount": 1500.0,
    "currency": "USD",
    "type": "credit"
  }
]
```

### ERP systems (json)

#### Source format

```json theme={null}
{
  "entries": [
    {
      "DOC_ID": "JE-2024-001",
      "GL_DATE": "2024-01-15",
      "GL_ACCOUNT": "1000",
      "AMOUNT_USD": 150000,
      "DR_CR": "D",
      "DESCRIPTION": "Vendor Payment - Acme Corp"
    }
  ]
}
```

#### Field map

```json theme={null}
{
  "name": "ERP Journal Entry Format",
  "source_type": "json",
  "root_path": "entries",
  "mappings": [
    {
      "source_field": "DOC_ID",
      "target_field": "transaction_id"
    },
    {
      "source_field": "GL_DATE",
      "target_field": "date"
    },
    {
      "source_field": "AMOUNT_USD",
      "target_field": "amount",
      "transformations": [
        {
          "type": "multiply",
          "options": {
            "factor": 0.01
          }
        }
      ]
    },
    {
      "target_field": "currency",
      "computed": true,
      "expression": {
        "type": "constant",
        "value": "USD"
      }
    },
    {
      "source_field": "DESCRIPTION",
      "target_field": "reference"
    },
    {
      "target_field": "type",
      "computed": true,
      "expression": {
        "type": "conditional",
        "conditions": [
          {
            "if": {
              "field": "DR_CR",
              "equals": "D"
            },
            "then": "debit"
          },
          {
            "if": {
              "field": "DR_CR",
              "equals": "C"
            },
            "then": "credit"
          }
        ]
      }
    },
    {
      "source_field": "GL_ACCOUNT",
      "target_field": "metadata.gl_account"
    }
  ]
}
```

#### Result

```json theme={null}
{
  "transaction_id": "JE-2024-001",
  "date": "2024-01-15",
  "amount": 1500.0,
  "currency": "USD",
  "reference": "Vendor Payment - Acme Corp",
  "type": "debit",
  "metadata": {
    "gl_account": "1000"
  }
}
```

### Payment gateways (xml)

#### Source format

```xml theme={null}
<transactions>
 <transaction>
 <id>PAY-2024-001</id>
 <timestamp>2024-01-15T14:30:00Z</timestamp>
 <amount currency="USD">99.99</amount>
 <merchant>Store #123</merchant>
 <status>completed</status>
 </transaction>
</transactions>
```

#### Field map

```json theme={null}
{
  "name": "Payment Gateway XML Format",
  "source_type": "xml",
  "root_path": "transactions/transaction",
  "mappings": [
    {
      "source_field": "id",
      "target_field": "transaction_id"
    },
    {
      "source_field": "timestamp",
      "target_field": "date",
      "transformations": [
        {
          "type": "parse_date",
          "options": {
            "format": "ISO8601"
          }
        }
      ]
    },
    {
      "source_field": "amount",
      "target_field": "amount",
      "transformations": [
        {
          "type": "parse_number"
        }
      ]
    },
    {
      "source_field": "amount@currency",
      "target_field": "currency"
    },
    {
      "source_field": "merchant",
      "target_field": "reference"
    },
    {
      "target_field": "type",
      "computed": true,
      "expression": {
        "type": "constant",
        "value": "credit"
      }
    }
  ]
}
```

#### Result

```json theme={null}
{
  "transaction_id": "PAY-2024-001",
  "date": "2024-01-15",
  "amount": 99.99,
  "currency": "USD",
  "reference": "Store #123",
  "type": "credit"
}
```

## Best practices

***

<AccordionGroup>
  <Accordion title="Name field maps like versions">
    Make format changes explicit (for example, `Bank CSV v2.0`) to preserve reimport and auditability.
  </Accordion>

  <Accordion title="Explain non-obvious transformations">
    Add descriptions for transformations that change semantics (for example, "Amount in cents, divide by 100").
  </Accordion>

  <Accordion title="Default optional fields intentionally">
    Use `default` only for optional fields and choose values that make downstream behavior explicit.
  </Accordion>

  <Accordion title="Normalize sign conventions">
    Standardize debits and credits across sources before matching.
  </Accordion>

  <Accordion title="Version instead of editing in place">
    When source formats change, create a new field map rather than modifying an existing one.
  </Accordion>
</AccordionGroup>

## Next steps

***

<CardGroup cols={2}>
  <Card title="Match rules" icon="scale-balanced" href="/en/matcher/configuration/matcher-match-rules">
    Define how transactions are compared and grouped.
  </Card>

  <Card title="Uploading files" icon="upload" href="/en/matcher/daily-reconciliation/matcher-uploading-files">
    Import transactions using your field maps.
  </Card>
</CardGroup>