Skip to main content

​
Endpoint

POST /reconciliation/start-instant
Starts a reconciliation process using external transactions provided directly in the request body, without requiring a prior file upload. This is ideal for real-time reconciliation or when you have a small number of transactions.

​
Request Body

​
external_transactions
array
required
Array of external transaction objects to reconcile
​
strategy
string
required
The reconciliation strategy. Supported values:
  • one_to_one: Match one external transaction to one internal transaction
  • one_to_many: Match one external transaction to multiple internal transactions
  • many_to_one: Match multiple external transactions to one internal transaction
​
matching_rule_ids
array
required
Array of matching rule IDs to apply during reconciliation
​
grouping_criteria
string
Field to use for grouping transactions before matching
​
dry_run
boolean
default:"false"
If true, performs the reconciliation without saving results

​
Response

​
reconciliation_id
string
The unique identifier for this reconciliation process

​
Example Request

{
  "external_transactions": [
    {
      "id": "ext_stripe_001",
      "amount": 100.50,
      "reference": "ch_3abc123",
      "currency": "USD",
      "description": "Payment from customer A",
      "date": "2024-03-04T10:30:00Z",
      "source": "stripe"
    },
    {
      "id": "ext_stripe_002",
      "amount": 250.00,
      "reference": "ch_3abc456",
      "currency": "USD",
      "description": "Subscription payment",
      "date": "2024-03-04T11:00:00Z",
      "source": "stripe"
    }
  ],
  "strategy": "one_to_one",
  "matching_rule_ids": ["rule_xyz789"],
  "dry_run": false
}

​
Example Response

{
  "reconciliation_id": "rec_instant_789xyz"
}

​
Use Cases

​
Real-time Webhook Reconciliation

Reconcile transactions immediately when receiving webhook notifications: 
{
  "external_transactions": [
    {
      "id": "webhook_txn_001",
      "amount": 99.99,
      "reference": "ORDER-12345",
      "currency": "USD",
      "description": "Order payment",
      "date": "2024-03-04T15:30:00Z",
      "source": "payment_gateway"
    }
  ],
  "strategy": "one_to_one",
  "matching_rule_ids": ["rule_realtime"],
  "dry_run": false
}

​
API-based Transaction Reconciliation

Reconcile transactions fetched from external APIs: 
{
  "external_transactions": [
    {
      "id": "api_txn_001",
      "amount": 1500.00,
      "reference": "WIRE-2024-001",
      "currency": "USD",
      "description": "Wire transfer",
      "date": "2024-03-04T09:00:00Z",
      "source": "bank_api"
    }
  ],
  "strategy": "one_to_many",
  "matching_rule_ids": ["rule_wire_transfer"],
  "grouping_criteria": "date",
  "dry_run": true
}

​
Error Responses

​
error
string
Error message describing what went wrong

​
Common Errors

  • 400 Bad Request: Invalid request body, missing required fields, or invalid transaction format
  • 500 Internal Server Error: Failed to start instant reconciliation

​
Differences from Standard Reconciliation

FeatureStandard ReconciliationInstant Reconciliation
Data SourceFile upload requiredInline transactions
Upload IDRequiredNot used
Best ForBatch processingReal-time, small batches
File FormatsCSV, JSON filesJSON objects only
Transaction LimitUnlimitedRecommended < 1000

​
Best Practices

  1. Keep it small: Use instant reconciliation for fewer than 1000 transactions
  2. Validate data: Ensure all required fields are present before making the request
  3. Use dry runs: Test with dry_run: true before committing
  4. Handle webhooks: Ideal for reconciling webhook notifications in real-time
  5. Consider batching: For large volumes, use the standard upload-based reconciliation

Build docs developers (and LLMs) love

Get started for freeTalk to us