Reconciliation API

The reconciliation cluster is the proof-of-correctness surface. Before flipping the cutover switch, you fire each endpoint against your Arcus entity and tie the numbers to the legacy ERP to the penny. After cutover, the same endpoints give you a permanent audit trail. All endpoints are read-only except POST .../compare, which is also non-destructive (it returns deltas, no writes).

Required scope

Endpoint	Scope
`GET trial-balance`	`accounting:read` OR `migration:read`
`GET ar-aging`	`accounting:read` OR `migration:read`
`GET ap-aging`	`accounting:read` OR `migration:read`
`GET inventory-valuation`	`accounting:read` OR `migration:read`
`GET cash-balance`	`accounting:read` OR `migration:read`
`GET counts`	`accounting:read` OR `migration:read`
`POST compare`	`migration:read` (narrower; migration-specific)

The scope table above is the authoritative one for these calls; the API reference lists migration:read alone on several of them. The dual scope on the GETs means a regular operator with accounting:read can run reconciliation reports during normal operations; a migration-specific key with migration:read (and nothing else) can do the same during a cutover window.

Trial balance

curl 'https://api.arcuserp.com/v1/entities/{ENTITY_ID}/reconciliation/trial-balance' \
  -H "Authorization: Bearer ark_live_..."

Optional query parameters:

as_of_date=YYYY-MM-DD (default: today). Snapshot date for the trial balance.
external_source=versa (default: all). Restrict to journal entries imported from a single source. Use this to verify that ONLY the migrated GL ties; subsequent native postings are excluded.

Response:

{
  "object": "reconciliation_trial_balance",
  "entity_id": "65dcd234-...",
  "as_of_date": "2026-07-12",
  "external_source": null,
  "rows": [
    { "account_id": "...", "account_number": "1000", "account_name": "Cash - Operating",
      "account_type": "asset", "system_account_key": null,
      "debit_balance": 125000.00, "credit_balance": 0.00, "net_balance": 125000.00,
      "net_debit": 125000.00, "net_credit": 0.00 },
    { "account_id": "...", "account_number": "1200", "account_name": "Accounts Receivable",
      "account_type": "asset", "system_account_key": "ar_account",
      "debit_balance": 127340.55, "credit_balance": 0.00, "net_balance": 127340.55,
      "net_debit": 127340.55, "net_credit": 0.00 },
    // ...
  ],
  "totals": { "debit": 1234567.89, "credit": 1234567.89,
              "net_debit": 1234567.89, "net_credit": 1234567.89,
              "in_balance": true, "imbalance": 0.00 }
}

A balanced trial balance has totals.in_balance equal to true and totals.imbalance equal to 0.00. Anything else is a data error and unfreeze will block.

AR aging

curl 'https://api.arcuserp.com/v1/entities/{ENTITY_ID}/reconciliation/ar-aging' \
  -H "Authorization: Bearer ark_live_..."

Optional query parameter: include_pii=false replaces each customer name with [REDACTED], for sharing a report outside your finance team. The aging buckets are measured against the entity’s current business day. Response:

{
  "object": "reconciliation_ar_aging",
  "entity_id": "65dcd234-...",
  "as_of_date": "2026-07-12",
  "rows": [
    {
      "account_id": "...",
      "display_name": "Acme Corp",
      "account_number": "C-12345",
      "current": 1200.00, "days_1_30": 0.00, "days_31_60": 540.00,
      "days_61_90": 0.00, "days_90_plus": 0.00, "total": 1740.00
    },
    // ...
  ],
  "totals": {
    "current": 50000.00, "days_1_30": 22000.00, "days_31_60": 15000.00,
    "days_61_90": 8000.00, "days_90_plus": 32340.55, "total": 127340.55
  }
}

Sum of totals.total must equal the AR control-account balance in the trial balance. That tie is the primary AR proof.

AP aging

Same idea as AR aging, vendor-keyed instead of customer-keyed. Each row carries vendor_id, display_name, the buckets current, days_1_30, days_31_60, days_61_90 and over_90, and total, with the same bucket names in totals. include_pii=false redacts the vendor names here too, and the object is reconciliation_ap_aging.

curl 'https://api.arcuserp.com/v1/entities/{ENTITY_ID}/reconciliation/ap-aging' \
  -H "Authorization: Bearer ark_live_..."

Inventory valuation

curl 'https://api.arcuserp.com/v1/entities/{ENTITY_ID}/reconciliation/inventory-valuation?as_of_date=2026-07-12&method=fifo' \
  -H "Authorization: Bearer ark_live_..."

Query parameters:

as_of_date=YYYY-MM-DD (default: today)
method (default: fifo) - fifo, avg, or lot_cost; the response names the basis it used
location_id (optional) - filter to one warehouse

Response:

{
  "object": "reconciliation_inventory_valuation",
  "entity_id": "65dcd234-...",
  "as_of_date": "2026-07-12",
  "method": "fifo",
  "by_location": [
    { "location_id": "...", "name": "Main Warehouse", "total_value": 187500.42 }
  ],
  "by_product": [
    { "product_id": "...", "sku": "WIDGET-100", "on_hand": 273, "unit_cost": 1.0092, "total_value": 275.51 }
  ],
  "total_value": 187500.42
}

total_value must equal the Inventory control-account balance in the trial balance.

Cash balance

curl 'https://api.arcuserp.com/v1/entities/{ENTITY_ID}/reconciliation/cash-balance' \
  -H "Authorization: Bearer ark_live_..."

Optional query parameters: as_of_date=YYYY-MM-DD (default: today) and bank_account_id to restrict the report to one bank account. Response:

{
  "object": "reconciliation_cash_balance",
  "entity_id": "65dcd234-...",
  "as_of_date": "2026-07-12",
  "total_cash_balance": 125000.00,
  "bank_accounts": [
    {
      "bank_account_id": "...",
      "bank_account_name": "Cash - Operating",
      "gl_account_id": "...",
      "gl_account_number": "1000",
      "balance": 125000.00,
      "unreconciled_bank_txn_count": 0,
      "unreconciled_gl_entry_count": 0
    }
  ]
}

balance is derived from the posted general ledger entries for that bank account as of the date, and equals the trial-balance value for its GL account. total_cash_balance is the entity-wide cash total. The two unreconciled counts show how many bank lines and GL entries are still waiting to be matched, so a non-zero count is a row to review before you certify the cash balance.

Resource counts

curl 'https://api.arcuserp.com/v1/entities/{ENTITY_ID}/reconciliation/counts?external_source=versa' \
  -H "Authorization: Bearer ark_live_..."

Response:

{
  "object": "reconciliation_counts",
  "entity_id": "65dcd234-...",
  "as_of": "2026-07-12T08:34:41.506Z",
  "external_source": "versa",
  "counts": {
    "accounts": 140071,
    "account_contacts": 142533,
    "account_addresses": 138991,
    "products": 1099,
    "orders": 265200,
    "order_items": 887423,
    "order_payments": 132784,
    "vendor_bills": 8791,
    "vendor_bill_items": 31273,
    "ap_payments": 7416,
    "journal_entries": 716569,
    "journal_entry_lines": 2641793
  }
}

The counts cover the entity’s major resource tables (accounts, products, orders, vendor bills, payments, journal entries, returns, packages, inventory adjustments and transfers, and documents), so the list above grows as new tables are covered. external_source filters to records imported from that source via the bulk endpoint. Omit it to see total counts across all sources, or pass by_source=true to break the journal entry counts down by source type instead.

Compare external records (the penny-match endpoint)

This is the workhorse. Submit external records (from the legacy ERP) and the API returns the per-record verdict against your Arcus data.

curl -X POST 'https://api.arcuserp.com/v1/entities/{ENTITY_ID}/reconciliation/compare' \
  -H "Authorization: Bearer ark_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_source": "versa",
    "external_resource": "ar_aging_by_customer",
    "tolerance_cents": 1,
    "external_records": [
      { "external_id": "ARCUS_ACCOUNT_ID_1", "current": 1200.00, "days_1_30": 0.00, "days_31_60": 540.00, "days_61_90": 0.00, "days_90_plus": 0.00, "total": 1740.00 },
      { "external_id": "ARCUS_ACCOUNT_ID_2", "current": 0.00,    "days_1_30": 320.00, "days_31_60": 0.00, "days_61_90": 0.00, "days_90_plus": 100.00, "total": 420.00 }
    ]
  }'

external_resource and external_records are required; external_source and tolerance_cents are optional. Each record names the thing it is compared to in a different field depending on the resource, and carries the figures to check: Supported external_resource values:

ar_aging_by_customer - per-customer AR aging buckets. external_id is matched to the customer’s Arcus account id; the figures are current, days_1_30, days_31_60, days_61_90, days_90_plus and total.
ap_aging_by_vendor - per-vendor AP aging buckets. external_id is matched to the vendor’s Arcus id; the figures are current, days_1_30, days_31_60, days_61_90, over_90 and total.
trial_balance_by_account - per-GL-account totals. The record is matched on account_number (or external_id); the figures are total_debit, total_credit and balance.
resource_counts - object-level counts. The record names the resource in resource_name and carries its count.

tolerance_cents is the per-record delta you accept (default: 1 cent). Set to 0 for exact ties. Response:

{
  "object": "reconciliation_compare_result",
  "external_source": "versa",
  "external_resource": "ar_aging_by_customer",
  "tolerance_cents": 1,
  "total_records": 2,
  "matched": 1,
  "mismatched": 1,
  "missing_in_arcus": 0,
  "extra_in_arcus": 0,
  "mismatches": [
    {
      "external_id": "ARCUS_ACCOUNT_ID_2",
      "arcus_id": "...",
      "field_deltas": {
        "days_1_30":  { "external": 320.00, "arcus": 318.50, "delta_cents": 150 }
      }
    }
  ],
  "missing_in_arcus_records": [],
  "extra_in_arcus_records": []
}

matched records balance to the penny. mismatched records have at least one field outside tolerance_cents. missing_in_arcus records exist in the external file but not in Arcus. extra_in_arcus records exist in Arcus but not in the external file. Hard cap: 5000 records per call; more returns 422 external_records_too_large with a hint to split the comparison into batches of 5000 or fewer. An empty or missing external_records returns 400 invalid_field. An external_resource outside the four above returns 422 unsupported_external_resource with the supported list.

Suggested cutover-day workflow

Pre-cutover (week of): run trial balance + counts daily. Confirm you can reproduce the same totals from the legacy ERP. Spot-check 5 to 10 named accounts via compare.
Cutover Friday EOD (T-0): freeze the entity. Run final reconciliation suite. Snapshot legacy source data alongside the Arcus database snapshot.
Cutover Saturday morning: run a top-up bulk-import sync for any data that changed between Thursday’s full load and Friday EOD freeze. Re-run reconciliation.
Cutover Saturday evening: swap traffic, then run POST .../cutover/verify which fires the full reconciliation suite. This is the gate that unblocks unfreeze.
Cutover Sunday: smoke-test critical user flows. Re-run individual reconciliation reports as needed.
Cutover Monday go-live: keep the reconciliation key live for a week so the operator can investigate any reported discrepancies.

Error envelope

Like the rest of the public API, every 4xx response follows the canonical envelope:

{
  "error": "missing_required_field",
  "code": "missing_required_field",
  "type": "validation_error",
  "param": "external_resource",
  "hint": "Provide one of: 'ar_aging_by_customer', 'ap_aging_by_vendor', 'trial_balance_by_account', 'resource_counts'."
}

See Errors.

Cutover orchestration - the freeze / snapshot / swap / verify / unfreeze sequence that consumes these reads.
Migrating Data into Arcus - the bulk-load step that populates the data these endpoints read.
Idempotency - request-level idempotency semantics.

Get Started

Concepts

Guides

SDKs

Collections

Required scope

Trial balance

AR aging

AP aging

Inventory valuation

Cash balance

Resource counts

Compare external records (the penny-match endpoint)

Suggested cutover-day workflow

Error envelope

​Required scope

​Trial balance

​AR aging

​AP aging

​Inventory valuation

​Cash balance

​Resource counts

​Compare external records (the penny-match endpoint)

​Suggested cutover-day workflow

​Error envelope

​Related

Required scope

Trial balance

AR aging

AP aging

Inventory valuation

Cash balance

Resource counts

Compare external records (the penny-match endpoint)

Suggested cutover-day workflow

Error envelope

Related