Field mapping - Lerian

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

cURL

curl -X POST "https://api.matcher.example.com/v1/field-maps" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Chase Bank Statement Format",
   "description": "Maps Chase bank CSV exports to Matcher schema",
   "source_type": "csv",
   "mappings": [
     {
       "source_field": "Transaction ID",
       "target_field": "transaction_id"
     },
     {
       "source_field": "Amount",
       "target_field": "amount"
     },
     {
       "source_field": "Currency",
       "target_field": "currency"
     },
     {
       "source_field": "Post Date",
       "target_field": "date"
     },
     {
       "source_field": "Description",
       "target_field": "reference"
     }
   ]
 }'

Response

{
  "id": "fmap_001",
  "name": "Chase Bank Statement Format",
  "description": "Maps Chase bank CSV exports to Matcher schema",
  "source_type": "csv",
  "mappings": [
    {
      "source_field": "Transaction ID",
      "target_field": "transaction_id"
    },
    {
      "source_field": "Amount",
      "target_field": "amount"
    },
    {
      "source_field": "Currency",
      "target_field": "currency"
    },
    {
      "source_field": "Post Date",
      "target_field": "date"
    },
    {
      "source_field": "Description",
      "target_field": "reference"
    }
  ],
  "created_at": "2024-01-15T10:00:00Z"
}

Assign a field map to a source

curl -X PATCH "https://api.matcher.example.com/v1/sources/src_bank456" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "field_map_id": "fmap_001"
 }'

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

cURL

curl -X POST "https://api.matcher.example.com/v1/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

{
  "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

{
  "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

{
  "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

{
  "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

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

{
  "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

[
  {
    "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

{
  "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

{
  "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

{
  "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

<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

{
  "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

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

Validating field maps

Validate field maps using representative sample data before enabling them in production.

Validate field map

cURL

curl -X POST "https://api.matcher.example.com/v1/field-maps/fmap_001/validate" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "sample_data": [
     {
       "Transaction ID": "TXN001",
       "Amount": "1,234.56",
       "Post Date": "01/15/2024",
       "Currency": "USD",
       "Description": "Test transaction"
     }
   ]
 }'

Best practices

Validate with representative data

Use real samples from the source system to catch parsing and transformation issues early.

Name field maps like versions

Make format changes explicit (for example, Bank CSV v2.0) to preserve reimport and auditability.

Explain non-obvious transformations

Add descriptions for transformations that change semantics (for example, “Amount in cents, divide by 100”).

Default optional fields intentionally

Use default only for optional fields and choose values that make downstream behavior explicit.

Normalize sign conventions

Standardize debits and credits across sources before matching.

Version instead of editing in place

When source formats change, create a new field map rather than modifying an existing one.

Introduction

Getting started

Configuration

Daily reconciliation

Integrations

Reference

​Why field mapping?

​Matcher’s standard schema

​Required fields

​Optional fields

​Creating field maps

​Basic field map

​Assign a field map to a source

​Data transformations

​Available transformations

​Transformation examples

​Date format patterns

​Computed fields

​Concatenation

​Conditional mapping

​Amount sign based on type

​Mapping examples by source type

​Bank statements (csv)

​Source format

​Field map

​Result

​ERP systems (json)

​Source format

​Field map

​Result

​Payment gateways (xml)

​Source format

​Field map

​Result

​Validating field maps

​Validate field map

​Best practices

​Next steps

Match rules

Uploading files

Why field mapping?

Matcher’s standard schema

Required fields

Optional fields

Creating field maps

Basic field map

Assign a field map to a source

Data transformations

Available transformations

Transformation examples

Date format patterns

Computed fields

Concatenation

Conditional mapping

Amount sign based on type

Mapping examples by source type

Bank statements (csv)

Source format

Field map

Result

ERP systems (json)

Source format

Field map

Result

Payment gateways (xml)

Source format

Field map

Result

Validating field maps

Validate field map

Best practices

Next steps