> ## 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. # Search transactions > Use this endpoint to search transactions within a reconciliation context. Supports free-text search, amount range filters, date filters, and status filters with offset-based pagination. ## OpenAPI ````yaml /pt/openapi/v3-current/matcher.yaml get /v1/imports/contexts/{contextId}/transactions/search openapi: 3.1.0 info: title: Matcher APIs description: >- Complete API reference for the Matcher reconciliation engine, providing automated transaction matching between Midaz Ledger and external systems. version: 5.0.4 license: name: Lerian Studio General License servers: - url: https://matcher.sandbox.lerian.net security: [] paths: /v1/imports/contexts/{contextId}/transactions/search: get: tags: - Ingestion summary: Search transactions description: >- Use this endpoint to search transactions within a reconciliation context. Supports free-text search, amount range filters, date filters, and status filters with offset-based pagination. operationId: searchTransactions parameters: - description: A unique identifier for tracing the request across services. in: header name: X-Request-Id schema: type: string - description: The unique identifier of the reconciliation context. in: path name: contextId required: true schema: description: Context ID format: uuid type: string - description: Free-text search query explode: false in: query name: q schema: description: Free text search across external ID and description type: string - description: Minimum transaction amount explode: false in: query name: amount_min schema: description: Minimum transaction amount type: string - description: Maximum transaction amount explode: false in: query name: amount_max schema: description: Maximum transaction amount type: string - description: Start date filter (RFC 3339 format) explode: false in: query name: date_from schema: description: Start date filter (RFC3339) format: date-time type: string - description: End date filter (RFC 3339 format) explode: false in: query name: date_to schema: description: End date filter (RFC3339) format: date-time type: string - description: Transaction reference (exact match) explode: false in: query name: reference schema: description: Exact external ID match type: string - description: Currency code filter explode: false in: query name: currency schema: description: Currency code filter type: string - description: Source ID filter explode: false in: query name: source_id schema: description: Source ID filter (UUID) type: string - description: Transaction status filter explode: false in: query name: status schema: description: Transaction status filter enum: - UNMATCHED - MATCHED - IGNORED - PENDING_REVIEW type: string - description: The maximum number of items to include in the response. explode: false in: query name: limit schema: default: 20 description: Maximum number of records to return format: int64 maximum: 50 minimum: 1 type: integer - description: The number of items to skip before returning results. explode: false in: query name: offset schema: default: 0 description: Number of records to skip format: int64 minimum: 0 type: integer responses: '200': description: Search results with offset pagination content: application/json: schema: $ref: '#/components/schemas/SearchTransactionsResponse' '400': description: The request contains invalid parameters or payload. content: application/problem+json: schema: $ref: '#/components/schemas/Detail' examples: 400-invalid-search-parameters: $ref: '#/components/examples/400-invalid-search-parameters' '401': $ref: '#/components/responses/Unauthorized' '403': description: >- You do not have permission to access this resource, or the context is not active. content: text/plain: schema: type: string example: Forbidden application/json: schema: $ref: '#/components/schemas/ErrorResponse' application/problem+json: schema: $ref: '#/components/schemas/Detail' examples: TenantClaimRequired: summary: Tenant claim missing value: type: https://errors.lerian.studio/v1/MTCH-0004 title: Forbidden status: 403 detail: tenant claim required code: MTCH-0004 mtch-0012-context-is-not-active: $ref: '#/components/examples/mtch-0012-context-is-not-active' '404': description: The requested resource was not found. content: application/problem+json: schema: $ref: '#/components/schemas/Detail' examples: mtch-0005-context-not-found: $ref: '#/components/examples/mtch-0005-context-not-found' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' security: - BearerAuth: [] components: schemas: SearchTransactionsResponse: additionalProperties: false properties: items: description: Matching transactions on this page items: $ref: '#/components/schemas/TransactionResponse' type: - array - 'null' limit: description: Maximum results per page examples: - 20 format: int64 type: integer offset: description: Current offset into the result set examples: - 0 format: int64 type: integer total: description: Total number of matching transactions across all pages examples: - 42 format: int64 type: integer required: - items - total - limit - offset type: object Detail: additionalProperties: false properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). examples: - ERR-0001 type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object ErrorResponse: description: >- Flat error body that Matcher returns when it refuses a request before the operation runs. type: object required: - code - title - message properties: code: type: string description: Stable error code. example: MTCH-0003 title: type: string description: HTTP status text. example: Unauthorized message: type: string description: Human-readable error message. example: missing authorization token TransactionResponse: additionalProperties: false properties: amount: description: >- Transaction amount as a decimal string in the transaction currency (precision preserved verbatim; never a float) examples: - '1000.50' type: string contextId: description: Reconciliation context this transaction belongs to examples: - 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string createdAt: description: Creation timestamp (RFC 3339) examples: - '2025-01-15T10:30:00Z' format: date-time type: string currency: description: ISO 4217 currency code of the amount examples: - USD type: string date: description: Transaction value date (RFC 3339) examples: - '2025-01-15T00:00:00Z' format: date-time type: string dedupeKey: description: >- Read-only: the duplicate-key value this row was imported under, derived from the source's duplicate key declaration at import time. A source can change that declaration later, so this is the only place that says which identity THIS row carries. Prefixed v1 when the key spells out the fields it was derived from, v1h when those fields were hashed because the spelled-out key was too long to index. examples: - v1|external_id=9:TXN-12345 type: string description: description: Free-text description carried from the source examples: - Wire transfer from ABC Corp type: string externalId: description: External identifier carried from the source system examples: - TXN-12345 type: string extractionStatus: description: >- Field-extraction status: PENDING (queued), COMPLETE (fields parsed), FAILED (extraction error) enum: - PENDING - COMPLETE - FAILED examples: - COMPLETE type: string id: description: Unique identifier for the transaction examples: - 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string jobId: description: Ingestion job that produced this transaction examples: - 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string metadata: additionalProperties: {} description: >- Normalized source metadata: unmapped source columns the engine projects into composite match keys and FX-conversion inputs (e.g. counterparty, bank_transaction_code, fx_rate). Arbitrary key/value, tenant-scoped to the caller's own data. type: object sourceId: description: Source this transaction belongs to examples: - 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string status: description: >- Matching status: UNMATCHED (no match found), MATCHED (reconciled), IGNORED (excluded from reconciliation by an operator), PENDING_REVIEW (imported under the blank-external-id review policy and awaiting an operator decision) enum: - UNMATCHED - MATCHED - IGNORED - PENDING_REVIEW examples: - UNMATCHED type: string required: - id - jobId - sourceId - contextId - externalId - dedupeKey - amount - currency - date - status - extractionStatus - createdAt type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object RateLimitErrorResponse: description: >- Flat body that the rate limiter returns. `code` is the HTTP status as a number. type: object required: - code - title - message properties: code: type: integer description: HTTP status code. example: 429 title: type: string description: Error type. example: rate_limit_exceeded message: type: string description: Human-readable error message. example: rate limit exceeded examples: 400-invalid-search-parameters: summary: Invalid search parameters value: title: Bad Request status: 400 detail: >- One or more search filters are invalid. Check the amount range, date range, and source id, then try again. mtch-0012-context-is-not-active: summary: Context is not active value: type: https://errors.lerian.studio/v1/MTCH-0012 title: Forbidden status: 403 detail: context is not active code: MTCH-0012 mtch-0005-context-not-found: summary: Context not found value: type: https://errors.lerian.studio/v1/MTCH-0005 title: Not Found status: 404 detail: >- No reconciliation context matches this id; check the context id and try again. code: MTCH-0005 responses: Unauthorized: description: The request lacks valid authentication credentials. content: application/problem+json: schema: $ref: '#/components/schemas/Detail' examples: MissingToken: summary: Missing token value: type: https://errors.lerian.studio/v1/MTCH-0003 title: Unauthorized status: 401 detail: missing authorization token code: MTCH-0003 InvalidToken: summary: Invalid token value: type: https://errors.lerian.studio/v1/MTCH-0003 title: Unauthorized status: 401 detail: invalid authorization token code: MTCH-0003 application/json: schema: $ref: '#/components/schemas/ErrorResponse' text/plain: schema: type: string example: Unauthorized ValidationFailed: description: >- The request failed validation. The `errors` list names each value that failed. content: application/problem+json: schema: $ref: '#/components/schemas/Detail' example: title: Unprocessable Entity status: 422 detail: validation failed errors: - message: expected required property name to be present location: body TooManyRequests: description: >- The request exceeded the rate limit. Wait the number of seconds in `Retry-After`, then retry. headers: Retry-After: $ref: '#/components/headers/RetryAfter' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' content: application/json: schema: $ref: '#/components/schemas/RateLimitErrorResponse' example: code: 429 title: rate_limit_exceeded message: rate limit exceeded InternalServerError: description: An unexpected error occurred on the server. content: application/problem+json: schema: $ref: '#/components/schemas/Detail' example: type: https://errors.lerian.studio/v1/MTCH-0002 title: Internal Server Error status: 500 detail: internal error code: MTCH-0002 text/plain: schema: type: string example: Internal Server Error headers: RetryAfter: description: Seconds to wait before you retry. schema: type: integer example: 30 XRateLimitLimit: description: Requests allowed in the current window. schema: type: integer example: 100 XRateLimitRemaining: description: Requests left in the current window. Always `0` on a `429`. schema: type: integer example: 0 XRateLimitReset: description: Unix time, in seconds, when the current window resets. schema: type: integer example: 1767225600 securitySchemes: BearerAuth: bearerFormat: JWT description: 'Bearer token authentication (format: "Bearer {token}")' scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.