v1.0

API Reference

Analysis (SmartScrub)

Bank statement analysis and transaction classification endpoints

Analyze bank statements and classify transactions using the SmartScrub pipeline. Supports two modes: PDF upload (always async) and JSON transactions (sync for ≤500 transactions, async for >500).

Analyze Bank Statements (PDF)

POST /api/public/v1/analysis/bank-statements

Upload one or more PDF bank statements for async analysis. Files are parsed, transactions extracted, classified, and MCA positions detected.

Content-Type: multipart/form-data

FieldTypeRequiredDescription
filesfile[]YesPDF files (max 10, each up to 50 MB)
merchantIdstringNoLink analysis to a merchant
dealIdstringNoLink analysis to a deal

Required Scope: analysis:trigger

Response 202 Accepted

{
  "data": {
    "id": "clx_abc123",
    "status": "pending",
    "mode": "pdf"
  }
}

PDF analysis is always asynchronous. Poll GET /analysis/{id} for results.

cURL

curl -X POST https://api.smartmca.com/api/public/v1/analysis/bank-statements \
  -H "Authorization: Bearer smca_live_..." \
  -F "files=@january-statement.pdf" \
  -F "files=@february-statement.pdf" \
  -F "merchantId=merch_123"

JavaScript

const form = new FormData();
form.append('files', fs.createReadStream('january-statement.pdf'));
form.append('files', fs.createReadStream('february-statement.pdf'));
form.append('merchantId', 'merch_123');

const res = await fetch('https://api.smartmca.com/api/public/v1/analysis/bank-statements', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer smca_live_...' },
  body: form,
});
const { data } = await res.json();
// data.id → use to poll for results

Python

import requests

files = [
    ('files', ('jan.pdf', open('january-statement.pdf', 'rb'), 'application/pdf')),
    ('files', ('feb.pdf', open('february-statement.pdf', 'rb'), 'application/pdf')),
]
resp = requests.post(
    'https://api.smartmca.com/api/public/v1/analysis/bank-statements',
    headers={'Authorization': 'Bearer smca_live_...'},
    files=files,
    data={'merchantId': 'merch_123'},
)
analysis_id = resp.json()['data']['id']

C#

using var form = new MultipartFormDataContent();
form.Add(new ByteArrayContent(File.ReadAllBytes("january-statement.pdf")),
    "files", "january-statement.pdf");
form.Add(new StringContent("merch_123"), "merchantId");

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "smca_live_...");
var resp = await client.PostAsync(
    "https://api.smartmca.com/api/public/v1/analysis/bank-statements", form);

Analyze Transactions (JSON)

POST /api/public/v1/analysis/transactions

Submit pre-parsed transactions as JSON. Transactions are classified inline.

  • ≤500 transactions → synchronous (200 OK with full results)
  • >500 transactions → asynchronous (202 Accepted, poll for results)

Required Scope: analysis:trigger

Request Body

{
  "merchantId": "merch_123",
  "dealId": "deal_456",
  "transactions": [
    {
      "date": "2026-01-05",
      "description": "DEPOSIT - Wire Transfer",
      "amount": 15000,
      "type": "credit"
    },
    {
      "date": "2026-01-06",
      "description": "ACH DEBIT - MCA Funding Co",
      "amount": 750,
      "type": "debit"
    }
  ]
}
FieldTypeRequiredDescription
transactionsarrayYesTransaction records
transactions[].datestringYesISO date (YYYY-MM-DD)
transactions[].descriptionstringYesTransaction description
transactions[].amountnumberYesAbsolute amount
transactions[].typestringYescredit or debit
merchantIdstringNoLink to a merchant
dealIdstringNoLink to a deal

Sync Response 200 OK (≤500 transactions)

{
  "data": {
    "id": "clx_abc123",
    "status": "completed",
    "mode": "transactions",
    "dealId": "deal_456",
    "merchantId": "merch_123",
    "startedAt": "2026-03-04T10:00:00Z",
    "completedAt": "2026-03-04T10:00:02Z",
    "error": null,
    "summary": {
      "totalTransactions": 120,
      "dateRange": { "start": "2026-01-01", "end": "2026-03-01" },
      "totalCredits": 450000,
      "totalDebits": 380000,
      "avgDailyBalance": 42500,
      "mcaPositionsDetected": 3,
      "revenueSourcesDetected": 45
    },
    "mcaPositions": [
      {
        "funderName": "MCA Funding Co",
        "frequency": "daily",
        "avgPayment": 750,
        "totalPayments": 15000,
        "transactionCount": 20,
        "confidence": 0.95
      }
    ],
    "classifications": {
      "revenue": { "total": 300000, "transactionCount": 45 },
      "mcaRepayment": { "total": 45000, "transactionCount": 60 },
      "loanPayment": { "total": 12000, "transactionCount": 6 },
      "operatingExpense": { "total": 180000, "transactionCount": 80 },
      "transfer": { "total": 50000, "transactionCount": 10 },
      "otherCredit": { "total": 25000, "transactionCount": 8 },
      "otherDebit": { "total": 8000, "transactionCount": 5 }
    },
    "transactions": [
      {
        "date": "2026-01-05",
        "description": "DEPOSIT - Wire Transfer",
        "amount": 15000,
        "type": "credit",
        "classification": "businessRevenue",
        "subClassification": null,
        "vendor": null,
        "confidence": 0.92,
        "classificationSource": "pattern"
      }
    ]
  }
}

Async Response 202 Accepted (>500 transactions)

{
  "data": {
    "id": "clx_abc123",
    "status": "pending",
    "mode": "transactions",
    "dealId": "deal_456",
    "merchantId": "merch_123",
    "startedAt": "2026-03-04T10:00:00Z",
    "completedAt": null,
    "error": null,
    "summary": null,
    "mcaPositions": null,
    "classifications": null,
    "transactions": null
  }
}

Get Analysis

GET /api/public/v1/analysis/{analysisId}

Returns the status and results for an analysis. When status is completed, the full response includes summary, mcaPositions, classifications, and transactions.

Required Scope: analysis:read

Analysis Statuses

StatusDescription
pendingQueued, not yet started
processingPipeline is running
completedAnalysis finished successfully
failedPipeline encountered an error

Classification Categories

CategoryDirectionDescription
businessRevenuecreditOperating revenue deposits
mcaFundingcreditMCA advance disbursements
loanDisbursementcreditLoan proceeds
transferIncreditInternal transfers in
refundcreditRefunds received
mcaRepaymentdebitMCA daily/weekly debits
loanPaymentdebitLoan repayments
businessExpensedebitOperating expenses
payrolldebitPayroll debits
taxPaymentdebitTax payments
nsfFeedebitInsufficient fund fees
bankFeedebitBank service fees
transferOutdebitInternal transfers out

Classification Sources

SourceDescription
vendor_rulesMatched a known vendor pattern
patternMatched keyword or behavioral rule
llmClassified by AI/LLM
funder_dbMatched known funder database
defaultDefault classification applied

List Analyses

GET /api/public/v1/analysis

Required Scope: analysis:read

ParameterTypeDefaultDescription
pagenumber1Page number
limitnumber20Items per page (max 100)
deal_idstring—Filter by deal
merchant_idstring—Filter by merchant
statusstring—Filter: pending, processing, completed, failed
created_afterstring—ISO datetime
created_beforestring—ISO datetime

Response:

{
  "data": [
    {
      "id": "clx_abc123",
      "mode": "transactions",
      "dealId": "deal_456",
      "merchantId": "merch_123",
      "status": "completed",
      "statementCount": 3,
      "createdAt": "2026-03-04T10:00:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 42,
      "totalPages": 3
    }
  }
}

Delete Analysis

DELETE /api/public/v1/analysis/{analysisId}

Deletes all analysis data for this ID (statements, transactions, detected positions). If the analysis is still running, it will be cancelled first.

Required Scope: analysis:trigger

Response 200 OK

{
  "deleted": true,
  "id": "clx_abc123"
}

Scopes

ActionScope
Read analysis status & resultsanalysis:read
Trigger analysis, deleteanalysis:trigger