API Reference

Complete reference for all Bank Statement Matcher API endpoints.

Jobs

Create a Job

POST/api/v1/jobs

Create a new matching job with a bank statement and expected references.

Parameters:

bankfilerequired

Bank statement file (PDF, CSV, or Excel format)

expectedfilerequired

Expected references file (CSV or Excel format)

envstring

Environment: sandbox or production

Response:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "created_at": "2024-01-17T10:30:00Z"
}

Example:

curl -X POST "http://localhost:8000/api/v1/jobs" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "bank=@statement.pdf" \
  -F "expected=@references.csv"

Get Job Status

GET/api/v1/jobs/{job_id}

Retrieve the status and metadata for a specific job.

Path Parameters:

job_idstringrequired

The unique job ID

Response:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "created_at": "2024-01-17T10:30:00Z",
  "completed_at": "2024-01-17T10:35:00Z",
  "bank_file": "statement.pdf",
  "expected_file": "references.csv"
}

Example:

curl -X GET "http://localhost:8000/api/v1/jobs/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN"

Results

Get Job Results

GET/api/v1/jobs/{job_id}/results

Retrieve the matching results for a completed job.

Path Parameters:

job_idstringrequired

The unique job ID

Response:

{
  "matched": [
    {
      "reference": "INV-001",
      "amount": 1500.00,
      "bank_entry": "Payment from ABC Corp - INV-001"
    }
  ],
  "partial": [
    {
      "reference": "INV-002",
      "expected_amount": 2000.00,
      "matched_amount": 1900.00,
      "reason": "amount_mismatch"
    }
  ],
  "unmatched": [
    {
      "reference": "INV-003",
      "amount": 500.00
    }
  ]
}

Example:

curl -X GET "http://localhost:8000/api/v1/jobs/550e8400-e29b-41d4-a716-446655440000/results" \
  -H "Authorization: Bearer YOUR_TOKEN"

Quotas & Limits

Check Quotas

GET/api/v1/limits

Check your remaining API quota and reset date.

Response:

{
  "plan": "starter",
  "jobs_limit": 100,
  "jobs_used": 47,
  "jobs_remaining": 53,
  "reset_date": "2024-02-17T00:00:00Z"
}

Example:

curl -X GET "http://localhost:8000/api/v1/limits" \
  -H "Authorization: Bearer YOUR_TOKEN"

Error Handling

All errors follow this format:

{
  "error": "ERROR_CODE",
  "detail": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Common Errors

Code	Status	Cause
`AUTH_INVALID`	401	Invalid credentials or expired token
`TOKEN_EXPIRED`	401	Access token has expired
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Job ID does not exist
`LIMIT_EXCEEDED`	429	API quota exceeded
`FILE_INVALID`	400	Invalid file format or corrupted
`SERVER_ERROR`	500	Internal server error

Retry Logic

API errors are retryable with exponential backoff:

# Pseudo-code
for attempt in 1..3:
  try:
    response = api_call()
    return response
  catch error:
    if error.status in [429, 500, 503]:
      wait(2 ^ attempt)
      continue
    else:
      throw error

Rate Limiting

The API enforces rate limits:

Standard Plan: 100 requests/minute
Pro Plan: 1000 requests/minute

Rate limit info is returned in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1705502400