Adjust entry for an exception

Use this endpoint to resolve an exception by creating an adjustment entry. This is used when a monetary correction is needed to reconcile the transaction.

POST /v1/exceptions/{exceptionId}/adjust-entry

Adjust entry for an exception

cURL

curl --request POST \
  --url https://matcher.sandbox.lerian.net/v1/exceptions/{exceptionId}/adjust-entry \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": "150.50",
  "currency": "USD",
  "effectiveAt": "2025-01-20T10:30:00Z",
  "notes": "Correcting processing fee discrepancy",
  "reasonCode": "FEE_ADJUSTMENT",
  "direction": "DEBIT"
}
'

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

Autorizações

Authorization · string · header · obrigatório

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

Cabeçalhos

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 caminho

exceptionId · string<uuid> · obrigatório

Exception ID Exception ID (UUID)

Exemplo:

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

Corpo

application/json

Adjust entry payload

amount · string · obrigatório

Adjustment amount as a decimal string in the field's currency; must be positive (enforced by the use case)

Exemplo:

"150.50"

currency · string · obrigatório

ISO 4217 currency code (3 letters) the adjustment amount is denominated in

Required string length: 3

Exemplo:

"USD"

effectiveAt · string<date-time> · obrigatório

When the adjustment takes effect, as an RFC 3339 timestamp

Exemplo:

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

notes · string · obrigatório

Additional notes explaining the adjustment

Required string length: 1 - 1000

Exemplo:

"Correcting processing fee discrepancy"

reasonCode · string · obrigatório

Reason code for the adjustment

Required string length: 1 - 255

Exemplo:

"FEE_ADJUSTMENT"

direction · enum<string>

Side of the adjustment entry, DEBIT or CREDIT. Optional; DEBIT when omitted. The amount stays positive either way

Opções disponíveis: DEBIT, CREDIT

Exemplo:

"DEBIT"

Resposta

200

application/json

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

createdAt · string · obrigatório

Creation timestamp as an RFC 3339 timestamp

Exemplo:

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

id · string · obrigatório

Unique identifier for the exception (UUID)

Exemplo:

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

severity · enum<string> · obrigatório

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

Opções disponíveis: LOW, MEDIUM, HIGH, CRITICAL

Exemplo:

"HIGH"

status · enum<string> · obrigatório

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

Opções disponíveis: OPEN, ASSIGNED, PENDING_RESOLUTION, RESOLVED

Exemplo:

"OPEN"

transactionId · string · obrigatório

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

Exemplo:

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

updatedAt · string · obrigatório

Last update timestamp as an RFC 3339 timestamp

Exemplo:

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

Exemplo:

"1250.50"

assignedTo · string

User the exception is currently assigned to

Exemplo:

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

Exemplo:

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

Exemplo:

"USD"

dueAt · string

Resolution due date as an RFC 3339 timestamp

Exemplo:

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

externalIssueId · string

Issue identifier in the external system, when dispatched

Exemplo:

"RECON-1234"

externalSystem · string

External system the exception was dispatched to, when applicable

Exemplo:

"JIRA"

reason · string

Reason the exception was originally raised

Exemplo:

"Amount mismatch detected"

resolutionNotes · string

Free-text notes captured when the exception was resolved

Exemplo:

"Resolved via force match"

resolutionReason · string

Reason code recorded for the resolution

Exemplo:

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

Opções disponíveis: FORCE_MATCH, ADJUST_ENTRY, MANUAL_MATCH, AUTO_CONSUME, AUTO_MATCH, UNMATCH_WITHDRAWN

Exemplo:

"FORCE_MATCH"

resolvedAt · string

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

Exemplo:

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

Exemplo:

"[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).

Exemplo:

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

Exemplo:

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

Exemplo:

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

Exemplo:

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