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 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 transactionAmountpostDatecheckNumberBank B amttransaction_dateref_numERP AMOUNT_USDGL_DATEDOC_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_idString Unique identifier within the source "TXN-2024-001"amountDecimal Transaction amount (up to 4 decimal places) 1234.56currencyString ISO 4217 currency code "USD"dateDate Transaction date (YYYY-MM-DD) "2024-01-15"
Optional fields Field Type Description Example referenceString External reference or description "Invoice #1234"counterpartyString Other party in the transaction "Acme Corp"typeString Transaction direction/type "credit", "debit"categoryString Transaction category "payment", "fee"posting_dateDate Posting date "2024-01-16"value_dateDate Value/settlement date "2024-01-17"external_idString External system identifier "BANK-REF-999"metadataObject 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.
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 { "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" }
Field maps can apply transformations to normalize formats and conventions before matching.
Transformation Description Example uppercaseConvert to uppercase "abc" → "ABC"lowercaseConvert to lowercase "ABC" → "abc"trimRemove leading/trailing whitespace " abc " → "abc"parse_dateParse date by format "01/15/2024" → "2024-01-15"parse_numberParse number with locale "1,234.56" → 1234.56absAbsolute value -100 → 100negateNegate number 100 → -100multiplyMultiply by factor 100 × 0.01 → 1replaceString replacement "USD$" → "USD"extractRegex extraction Extract numbers from string defaultDefault if empty null → "UNKNOWN"concatConcatenate fields field1 + field2
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 { "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" } } ] } ] }
Common parse_date patterns:
Pattern Example input Output YYYY-MM-DD2024-01-152024-01-15MM/DD/YYYY01/15/20242024-01-15DD/MM/YYYY15/01/20242024-01-15YYYY-MM-DDTHH:mm:ssZ2024-01-15T10:30:00Z2024-01-15MMM DD, YYYYJan 15, 20242024-01-15DD-MMM-YYYY15-Jan-20242024-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) 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) { "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) < 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" }
Best practices
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.
Next steps
Match rules Define how transactions are compared and grouped.
Uploading files Import transactions using your field maps.
