Quickstart — Reconciliation

From scope ids to a first accepted money ingestion and a status read.

Documentation status

Last verified: 26 Sep 2026. Follow the status vocabulary.

Prerequisites

1. tenant_id, partner_id, and object-storage URLs for sample GL + bank files.
2. Base URL with /v1 prefix — Base URLs.
3. Environment auth as agreed with MasteryHive.

Steps

1. Mint a new session_id (UUID).
2. POST {recon_base}/ingestion/background:

{
  "session_id": "00000000-0000-0000-0000-000000000099",
  "tenant_id": "YOUR_TENANT_ID",
  "partner_id": "YOUR_PARTNER_ID",
  "gl_file_url": ["https://storage.googleapis.com/EXAMPLE_BUCKET/gl.csv"],
  "bank_file_url": ["https://storage.googleapis.com/EXAMPLE_BUCKET/bank.csv"],
  "on_existing_action": "overwrite"
}

1. Poll or query GET {recon_base}/loader/pipeline-status/{session_id} (when exposed in your environment).
2. Optional: exercise the manual testing / fallback route POST …/exceptions/resolve with a stable resolution_request_id after exceptions exist (deployed environments normally receive resolve requests over Pub/Sub) — exception contract.

Observable success

Signal	Meaning
Ingestion accepted (2xx) echoing session_id	Run started
Pipeline status shows progression / completion	Matching side finished or failed with a visible state
Exception resolve audit row for your resolution_request_id	Operator decision recorded

If it fails

Status	Likely cause
409	Period lock / active session — use new session or wait
422	Missing scope fields / invalid enum

Next: Recon examples · Semantics