Exports & disputes

This guide covers two operator workflows that both end in a downloadable or resolved artifact. With export jobs you queue a report, poll until it succeeds, and download the file. With disputes you open a dispute against an exception, attach evidence, then close it won or lost. Both are tenant-scoped from the JWT.

Export jobs

Exports are asynchronous. You create a job scoped to a context, poll its status by ID, and download the file once it reaches SUCCEEDED. Statuses are QUEUED, RUNNING, SUCCEEDED, FAILED, EXPIRED, and CANCELED.

Create an export job

POST to the context’s export-jobs collection. Responds 202 Accepted with the job ID and a poll URL.

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/export-jobs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reportType": "MATCHED",
    "format": "CSV",
    "dateFrom": "2025-01-01",
    "dateTo": "2025-01-31",
    "sourceId": "550e8400-e29b-41d4-a716-446655440000"
  }'

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "QUEUED",
  "statusUrl": "/v1/export-jobs/550e8400-e29b-41d4-a716-446655440000"
}

reportType: one of MATCHED, UNMATCHED, VARIANCE, EXCEPTIONS (the aliases MATCHES and UNMATCHED_TRANSACTIONS normalize to these values).
format: CSV, JSON, or XML, in uppercase.
dateFrom / dateTo: optional YYYY-MM-DD. dateFrom defaults to 30 days before dateTo, and dateTo defaults to tomorrow (UTC).
sourceId: optional source filter.

Async export jobs do not support SUMMARY (400) or PDF (422). The date window spans at most 365 days, and a longer window returns 400. Job creation returns 503 when asynchronous exports are not enabled for your environment.

Poll job status

Read the top-level job route (the statusUrl from creation).

curl -X GET "https://api.matcher.example.com/v1/export-jobs/{jobId}" \
  -H "Authorization: Bearer $TOKEN"

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
  "reportType": "MATCHED",
  "format": "CSV",
  "status": "SUCCEEDED",
  "recordsWritten": 4250,
  "bytesWritten": 524288,
  "fileName": "MATCHED_550e8400_20250101-20250131.csv",
  "createdAt": "2025-01-15T10:30:00Z",
  "startedAt": "2025-01-15T10:30:05Z",
  "finishedAt": "2025-01-15T10:35:00Z",
  "expiresAt": "2025-01-22T10:30:00Z",
  "downloadUrl": "/v1/export-jobs/550e8400-e29b-41d4-a716-446655440000/download"
}

contextId names the context the job exports. error carries the job’s last failure reason, when it has one. downloadUrl is the download route below, and it appears only once the job has SUCCEEDED and the file is still available. You can list a context’s jobs with GET /v1/contexts/{contextId}/export-jobs, list all jobs with GET /v1/export-jobs, and cancel a queued/running job with POST /v1/export-jobs/{jobId}/cancel.

Download the file

Returns a presigned URL, the original file name, a SHA-256 checksum, and the URL’s remaining lifetime in seconds.

curl -X GET "https://api.matcher.example.com/v1/export-jobs/{jobId}/download" \
  -H "Authorization: Bearer $TOKEN"

{
  "downloadUrl": "https://storage.example.com/exports/report.csv?token=abc",
  "fileName": "MATCHED_550e8400_20250101-20250131.csv",
  "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "expiresIn": 3600
}

Export files are purged after expiresAt, 7 days after the job was created. After that, the file is no longer downloadable. Re-run the export to regenerate it.

Disputes

You open a dispute against a specific exception when you need to contest a reconciliation discrepancy. A new dispute is OPEN. Closing it sets WON or LOST, and both outcomes are terminal.

Open a dispute

POST to the exception’s disputes collection. Responds 201 Created.

curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/disputes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "BANK_FEE_ERROR",
    "description": "Transaction amount differs from invoice"
  }'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "exceptionId": "550e8400-e29b-41d4-a716-446655440001",
  "category": "BANK_FEE_ERROR",
  "state": "OPEN",
  "description": "Transaction amount differs from invoice",
  "openedBy": "user@example.com",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

category is one of BANK_FEE_ERROR, UNRECOGNIZED_CHARGE, DUPLICATE_TRANSACTION, AMOUNT_MISMATCH, or OTHER. The response omits evidence until the dispute has some. The openedBy field records the opening principal. Matcher refuses to open a dispute with 409 (MTCH-0511) when the exception is RESOLVED or PENDING_RESOLUTION. It answers 409 (MTCH-0510) while a settlement is in progress on the exception. Retry that request after the settlement completes.

Submit evidence by URL

Attach a reference to an already-hosted evidence file plus a describing comment. fileUrl must be an https URL.

curl -X POST "https://api.matcher.example.com/v1/disputes/{disputeId}/evidence" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Attached bank statement showing correct amount",
    "fileUrl": "https://storage.example.com/evidence/doc123.pdf"
  }'

Upload an evidence file

Stream the raw file bytes directly to tenant-scoped object storage. The comment travels as a query parameter and the file as the request body. Responds 201 Created with the updated dispute. Allowed content types are application/pdf, image/png, image/jpeg, and text/csv. The body has a 10 MiB limit.

curl -X POST "https://api.matcher.example.com/v1/disputes/{disputeId}/evidence/upload?comment=Bank%20statement%20showing%20correct%20amount" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/pdf" \
  --data-binary @statement.pdf

The dispute’s evidence array lists each stored evidence item. For an uploaded file, fileUrl holds the object-storage key, not a download URL:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "disputeId": "550e8400-e29b-41d4-a716-446655440001",
  "comment": "Bank statement showing correct amount",
  "submittedBy": "user@example.com",
  "fileUrl": "<tenant-id>/dispute-evidence/550e8400-e29b-41d4-a716-446655440001/<object-id>.pdf",
  "submittedAt": "2025-01-15T10:30:00Z"
}

The upload endpoint returns 503 when evidence storage is unavailable. It rejects oversize bodies with 413 and content types outside the allowlist with 415. The tenant always comes from the JWT and the dispute from the path, never from the body.

Close a dispute

Record the outcome. won: true sets the state to WON and won: false sets it to LOST. A resolution note is required.

curl -X POST "https://api.matcher.example.com/v1/disputes/{disputeId}/close" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "won": true,
    "resolution": "Counterparty acknowledged the error and issued correction"
  }'

You can list disputes with GET /v1/disputes and fetch one with GET /v1/disputes/{disputeId}. The list endpoint filters by state, category, and date range, and it supports sorting and cursor pagination.

Response codes

Status	Meaning
`200`	Export/dispute data returned
`201`	Dispute opened or evidence file uploaded
`202`	Export job accepted
`400`	Invalid input (`SUMMARY` report type, bad date range, invalid category)
`404`	Context, export job, exception, or dispute not found
`409`	Export job not ready for download, or already in a terminal state when canceled. Exception not open to a new dispute, or a settlement in progress on it
`410`	Export file expired
`413`	Evidence file exceeds the 10 MiB cap
`415`	Evidence content type not in the allowlist
`422`	Malformed field (including a lowercase or unsupported `format`), or invalid dispute state transition
`429`	Rate limit exceeded
`503`	Asynchronous exports not enabled for your environment, or export or evidence storage unavailable

Overview

Guides

Console

MCP Server

Operations

Exports & disputes

Export jobs

Create an export job

Poll job status

Download the file

Disputes

Open a dispute

Submit evidence by URL

Upload an evidence file

Close a dispute

Response codes

​Export jobs

​Create an export job

​Poll job status

​Download the file

​Disputes

​Open a dispute

​Submit evidence by URL

​Upload an evidence file

​Close a dispute

​Response codes

Export jobs

Create an export job

Poll job status

Download the file

Disputes

Open a dispute

Submit evidence by URL

Upload an evidence file

Close a dispute

Response codes