Force match an exception

Use this endpoint to resolve an exception by forcing a match with an override reason. This is used when manual intervention determines the transaction should be considered matched despite discrepancies.

POST /v1/exceptions/{exceptionId}/force-match

Force match an exception

cURL

curl --request POST \
  --url https://matcher.sandbox.lerian.net/v1/exceptions/{exceptionId}/force-match \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "notes": "Approved by finance team after manual review",
  "overrideReason": "BUSINESS_DECISION"
}
'

200

Example

{
  "createdAt": "2025-01-15T10:30:00Z",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "severity": "HIGH",
  "status": "OPEN",
  "transactionId": "550e8400-e29b-41d4-a716-446655440001",
  "updatedAt": "2025-01-15T10:30:00Z",
  "amount": "1250.50",
  "assignedTo": "[e-mail]",
  "contextId": "550e8400-e29b-41d4-a716-446655440004",
  "currency": "USD",
  "dueAt": "2025-01-20T10:30:00Z",
  "externalIssueId": "RECON-1234",
  "externalSystem": "JIRA",
  "reason": "Amount mismatch detected",
  "resolutionNotes": "Resolved via force match",
  "resolutionReason": "BUSINESS_DECISION",
  "resolutionType": "FORCE_MATCH",
  "resolvedAt": "2025-01-15T12:00:00Z",
  "resolvedBy": "[e-mail]",
  "runId": "550e8400-e29b-41d4-a716-446655440002",
  "settlement": {
    "credited": "95.00",
    "currency": "BRL",
    "difference": "-2.00",
    "expected": "97.00"
  },
  "sourceId": "550e8400-e29b-41d4-a716-446655440003",
  "sourceName": "Bank feed",
  "transactionDate": "2025-01-14T00:00:00Z"
}

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.

Parámetros de ruta

exceptionId · string<uuid> · requerido

Exception ID Exception ID (UUID)

Ejemplo:

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

Cuerpo

application/json

Force match payload

notes · string · requerido

Additional notes explaining the force match decision

Required string length: 1 - 1000

Ejemplo:

"Approved by finance team after manual review"

overrideReason · string · requerido

Reason for overriding the normal matching process

Required string length: 1 - 255

Ejemplo:

"BUSINESS_DECISION"

Respuesta

200

application/json

Indicates that the request was successful and the response contains the expected data.

createdAt · string · requerido

Creation timestamp as an RFC 3339 timestamp

Ejemplo:

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

id · string · requerido

Unique identifier for the exception (UUID)

Ejemplo:

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

severity · enum<string> · requerido

Severity level: LOW and MEDIUM are informational, HIGH needs prompt review, CRITICAL requires immediate action

Opciones disponibles: LOW, MEDIUM, HIGH, CRITICAL

Ejemplo:

"HIGH"

status · enum<string> · requerido

Lifecycle status: OPEN (unhandled), ASSIGNED (owned by a user), PENDING_RESOLUTION (a resolution is in flight), RESOLVED (closed out)

Opciones disponibles: OPEN, ASSIGNED, PENDING_RESOLUTION, RESOLVED

Ejemplo:

"OPEN"

transactionId · string · requerido

Identifier of the transaction this exception was raised for (UUID)

Ejemplo:

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

updatedAt · string · requerido

Last update timestamp as an RFC 3339 timestamp

Ejemplo:

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

amount · string

Enrichment: the exception transaction's amount as a decimal string in the transaction's currency. Present on list rows and get-by-id when the transaction still exists.

Ejemplo:

"1250.50"

assignedTo · string

User the exception is currently assigned to

Ejemplo:

"[e-mail]"

contextId · string

Enrichment: id of the reconciliation context the exception's source belongs to (UUID). Present on list rows and get-by-id when the transaction and source still exist; powers the global triage queue's context attribution.

Ejemplo:

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

currency · string

Enrichment: ISO 4217 currency code of the exception transaction's amount. Present on list rows and get-by-id when the transaction still exists.

Ejemplo:

"USD"

dueAt · string

Resolution due date as an RFC 3339 timestamp

Ejemplo:

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

externalIssueId · string

Issue identifier in the external system, when dispatched

Ejemplo:

"RECON-1234"

externalSystem · string

External system the exception was dispatched to, when applicable

Ejemplo:

"JIRA"

reason · string

Reason the exception was originally raised

Ejemplo:

"Amount mismatch detected"

resolutionNotes · string

Free-text notes captured when the exception was resolved

Ejemplo:

"Resolved via force match"

resolutionReason · string

Reason code recorded for the resolution

Ejemplo:

"BUSINESS_DECISION"

resolutionType · enum<string>

How the exception was resolved: FORCE_MATCH (override match), ADJUST_ENTRY (monetary correction), MANUAL_MATCH (the manual match that paired it), AUTO_CONSUME (closed automatically when a run settled its transaction against a carried open item), AUTO_MATCH (closed automatically when a run or a manual match matched its transaction, for a break whose reason only said its counterpart was missing or unusable: UNMATCHED, FX_RATE_UNAVAILABLE, MISSING_BASE_AMOUNT, MISSING_BASE_CURRENCY or SPLIT_INCOMPLETE) or UNMATCH_WITHDRAWN (withdrawn by an un-match: the match that raised it, or the match that resolved it, was undone)

Opciones disponibles: FORCE_MATCH, ADJUST_ENTRY, MANUAL_MATCH, AUTO_CONSUME, AUTO_MATCH, UNMATCH_WITHDRAWN

Ejemplo:

"FORCE_MATCH"

resolvedAt · string

When the exception was resolved, as an RFC 3339 timestamp. Present only for RESOLVED exceptions.

Ejemplo:

"2025-01-15T12:00:00Z"

resolvedBy · string

Principal that resolved the exception (JWT sub, or 'system' for automated callback resolutions). Empty until resolved or when the resolving path is un-attributed.

Ejemplo:

"[e-mail]"

runId · string

Identifier of the match run that LATEST surfaced this exception (UUID). Refreshed on every re-run that re-surfaces the break, so it names the most recent run that touched it; powers the run-precise jump from a run to its exceptions. Absent for legacy rows written before run linkage and for ingestion-minted duplicate-transaction breaks (not produced by a match run).

Ejemplo:

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

settlement · object

Settlement figures for a fee break (expected vs credited and the signed difference), derived from the live fee-variance snapshot recorded for the exception's transaction. Present on get-by-id only, and only when the snapshot and the transaction amount are both available in the same currency.

Show child attributes

sourceId · string

Enrichment: id of the reconciliation source the exception transaction belongs to (UUID). Present on list rows and get-by-id when the transaction still exists.

Ejemplo:

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

sourceName · string

Enrichment: display name of the reconciliation source. Present on get-by-id when the transaction and its source still exist.

Ejemplo:

"Bank feed"

transactionDate · string

Enrichment: the exception transaction's value date as an RFC 3339 timestamp. Present on list rows and get-by-id when the transaction still exists.

Ejemplo:

"2025-01-14T00:00:00Z"