Create a reconciliation context

Use this endpoint to create a new reconciliation context. Contexts are used to scope matching rules and organize your reconciliation configuration.

POST /v1/contexts

Create a reconciliation context

cURL

curl --request POST \
  --url https://matcher.sandbox.lerian.net/v1/contexts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Bank Reconciliation Q1",
  "type": "1:1",
  "agedBreakCalendar": "BR_ANBIMA",
  "agedBreakThresholdDays": 30,
  "autoMatchOnUpload": false,
  "feeNormalization": "NET",
  "feeToleranceAbs": "0.01",
  "feeTolerancePct": "0.5",
  "rules": [
    {
      "config": {},
      "priority": 1,
      "type": "EXACT"
    }
  ],
  "signConvention": "SAME",
  "sources": [
    {
      "name": "Primary Bank Account",
      "side": "LEFT",
      "type": "BANK",
      "config": {
        "camt053": {},
        "dialect": {},
        "duplicate_key": [],
        "fail_on_error_rate_percent": 50
      },
      "mapping": {}
    }
  ]
}
'

201

Example

{
  "autoMatchOnUpload": false,
  "createdAt": "2025-01-15T10:30:00Z",
  "feeToleranceAbs": "0.50",
  "feeTolerancePct": "0.5",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Bank Reconciliation Q1",
  "signConvention": "SAME",
  "status": "ACTIVE",
  "tenantId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "1:1",
  "updatedAt": "2025-01-15T10:30:00Z",
  "agedBreakCalendar": "BR_ANBIMA",
  "agedBreakThresholdDays": 30,
  "feeNormalization": "NET"
}

Autorizaciones

Authorization · string · header · requerido

Bearer token authentication (format: "Bearer {token}")

Encabezados

X-Request-Id · string

A unique identifier for tracing the request across services.

X-Idempotency · string

Optional idempotency key for safe retries. Matcher reads the key only from this header, and only when you send one. A request that carries a key only in X-Idempotency-Key or Idempotency-Key is refused with 400 (MTCH-0015), and nothing is processed. If the same key is sent again and the original request was already processed, the stored response is returned with X-Idempotency-Replayed: true. A malformed key returns 400, a key whose first request is still in progress returns 409 (MTCH-0018), a key whose earlier attempt already ran but whose answer cannot be replayed returns 409 (MTCH-0022), and an idempotency storage failure returns 500. POST, PUT, PATCH and DELETE requests accept the header. These refusals are problem documents.

Cuerpo

application/json

Context creation payload

name · string · requerido

Human-readable name of the reconciliation context.

Required string length: 1 - 100

Ejemplo:

"Bank Reconciliation Q1"

type · enum<string> · requerido

Reconciliation topology. 1:1 matches one left transaction to one right transaction; 1:N matches one transaction against many on the other side; N:M matches groups on both sides.

Opciones disponibles: 1:1, 1:N, N:M

Ejemplo:

"1:1"

agedBreakCalendar · string

Business-day calendar the aging threshold is measured against (e.g. US_FED, BR_ANBIMA). Omit/empty measures the age in raw calendar days.

Ejemplo:

"BR_ANBIMA"

agedBreakThresholdDays · integer<int64>

Open-item aging SLA in business days. An open-item residual older than this surfaces as an AGED_BREAK exception during the match run. Omit to disable aging for the context.

Ejemplo:

30

autoMatchOnUpload · boolean

When true, a match run is triggered automatically after a file upload completes.

Ejemplo:

false

feeNormalization · enum<string>

Fee normalization mode. NET compares amounts after fees are deducted; GROSS compares amounts before fees.

Opciones disponibles: NET, GROSS

Ejemplo:

"NET"

feeToleranceAbs · string

Absolute fee tolerance as a decimal string in the context currency.

Ejemplo:

"0.01"

feeTolerancePct · string

Fee tolerance in percent, as a decimal string: 0.5 means 0.5%, not 50%.

Ejemplo:

"0.5"

rules · object[] | null

Match rules to create inline with the context.

Maximum array length: 50

Show child attributes

signConvention · enum<string>

How this context's data carries sign. SAME: a payment carries the same sign as what it settles, so a negative amount is a reversal. OPPOSITE: a payment carries the opposite sign of the invoice it settles. Defaults to SAME. In 1:N contexts only payments of the declared sign are allocated to an invoice, and in N:M contexts a short-paid invoice keeps an open balance only when it is positive under SAME, or when the rule's sign mode is opposite under OPPOSITE; any other short payment stays unmatched; a carried open balance settles on a payment of the declared sign or on a reversal from the invoice's own side, and a row from an archived source stays unmatched. It cannot change once the context has carried a partial balance, or while a match run is in progress.

Opciones disponibles: SAME, OPPOSITE

Ejemplo:

"SAME"

sources · object[] | null

Sources to create inline with the context.

Maximum array length: 10

Show child attributes

Respuesta

201

application/json

Successfully created context.

autoMatchOnUpload · boolean · requerido

When true, a match run is triggered automatically after a file upload completes.

Ejemplo:

false

createdAt · string · requerido

Creation timestamp in RFC 3339 format.

Ejemplo:

"2025-01-15T10:30:00Z"

feeToleranceAbs · string · requerido

Absolute fee tolerance as a decimal string in the context currency.

Ejemplo:

"0.50"

feeTolerancePct · string · requerido

Fee tolerance in percent, as a decimal string: 0.5 means 0.5%, not 50%.

Ejemplo:

"0.5"

id · string · requerido

Unique identifier of the context.

Ejemplo:

"550e8400-e29b-41d4-a716-446655440000"

name · string · requerido

Human-readable name of the reconciliation context.

Ejemplo:

"Bank Reconciliation Q1"

signConvention · enum<string> · requerido

How this context's data carries sign. SAME: a payment carries the same sign as what it settles, so a negative amount is a reversal. OPPOSITE: a payment carries the opposite sign of the invoice it settles. In 1:N contexts only payments of the declared sign are allocated to an invoice, and in N:M contexts a short-paid invoice keeps an open balance only when it is positive under SAME, or when the rule's sign mode is opposite under OPPOSITE; any other short payment stays unmatched; a carried open balance settles on a payment of the declared sign or on a reversal from the invoice's own side, and a row from an archived source stays unmatched. It cannot change once the context has carried a partial balance, or while a match run is in progress.

Opciones disponibles: SAME, OPPOSITE

Ejemplo:

"SAME"

status · enum<string> · requerido

Lifecycle status. DRAFT is being configured; ACTIVE runs; PAUSED is suspended; ARCHIVED is retired.

Opciones disponibles: DRAFT, ACTIVE, PAUSED, ARCHIVED

Ejemplo:

"ACTIVE"

tenantId · string · requerido

Identifier of the tenant that owns the context.

Ejemplo:

"550e8400-e29b-41d4-a716-446655440000"

type · enum<string> · requerido

Reconciliation topology. 1:1 matches one left transaction to one right transaction; 1:N matches one transaction against many on the other side; N:M matches groups on both sides.

Opciones disponibles: 1:1, 1:N, N:M

Ejemplo:

"1:1"

updatedAt · string · requerido

Last update timestamp in RFC 3339 format.

Ejemplo:

"2025-01-15T10:30:00Z"

agedBreakCalendar · string

Business-day calendar the aging threshold is measured against. Absent/empty means raw calendar days.

Ejemplo:

"BR_ANBIMA"

agedBreakThresholdDays · integer<int64>

Open-item aging SLA in business days. An open-item residual older than this surfaces as an AGED_BREAK exception. Absent when aging is disabled for the context.

Ejemplo:

30

feeNormalization · enum<string>

Fee normalization mode. NET compares amounts after fees are deducted; GROSS compares amounts before fees.

Opciones disponibles: NET, GROSS

Ejemplo:

"NET"