Finance Operations Batch Review
API Access
The task environment exposes a shared ERP/compliance API at the base URL the runner provides as <TASK_ENV_BASE_URL>. All endpoints return JSON arrays wrapped in {"count": N, "data": [...]}. Use exact-match query parameters by field name; paginate with limit and offset.
Available Endpoints
| Endpoint |
Purpose |
GET /api/claims |
Employee expense claims |
GET /api/ap/bills |
AP bills (may link to claims via claim_id) |
GET /api/ap/payments |
Payment records linked to bills via bill_id |
GET /api/ap/aging |
AP aging with balance, paid_amount per bill |
GET /api/vendors |
Vendor master with bank, tax, status |
GET /api/compliance/objects |
Consolidated compliance records per business_id |
GET /api/compliance/ownership/{business_id} |
UBO list with ownership_pct and shell_company flag |
GET /api/compliance/registry/{business_id} |
Jurisdiction, license_expiry, tax_id, registration |
GET /api/compliance/screening/{business_id} |
PEP status, sanctions check |
GET /api/compliance/bank/{business_id} |
Bank account verification status |
GET /api/prepaids/invoices |
Prepaid invoice schedules with monthly_amortization |
GET /api/prepaids/gl-balances or GET /api/gl/balances |
GL ending balances per account/period/entity |
GET /api/close/logs |
Period-close log entries with area, status, message |
Both /api/prepaids/gl-balances and /api/gl/balances return the same data; use whichever is available. Similarly, /claims is an alias for /api/claims, /bills for /api/ap/bills, etc.
Cross-Reference Patterns
Claims to AP Bills to Payments
Link claims to AP using claim_id on bills. Link bills to payments using bill_id on payments.
Claim status values: approved, paid, rejected, submitted, needs_receipt, in_review, denied.
Bill status values: approved, scheduled, paid, void, pending, rejected.
Payment status values: cleared, processing, scheduled, failed.
Key rules:
- A claim is paid (settled) only when: a bill with matching
claim_id exists, the bill status is paid, and at least one cleared payment exists for that bill covering the full bill amount. Do not rely on claim.status === "paid" alone; verify the bill and payment chain.
- A claim is blocked (not ready for AP release) when: the claim status is not
approved (e.g., rejected, denied, needs_receipt, submitted), or the linked bill has a blocking status (void, rejected), or no bill exists at all, or there is a vendor mismatch between the claim's vendor_id (if present) and the bill's vendor_id, or there is a material amount mismatch between claim and bill.
- A claim is payable when: the claim is
approved, a valid linked bill exists and is not paid or void, and no blocking conditions apply.
- AP open balance for a payable claim = bill.amount minus the sum of all cleared payments for that bill. Use the
balance field from /api/ap/aging when available; otherwise compute from bills and payments.
- A scheduled payment is not a cleared payment. Only
cleared payments close out a bill balance.
Business IDs to Compliance Records
Cross-reference each business ID across four compliance dimensions:
- Ownership (
/api/compliance/ownership/{business_id}): Count unique beneficial owner names (not entries) with ownership_pct >= 25 as reportable UBOs. A person appearing twice with different percentages counts as one UBO. shell_company_suspected: true is a hard stop.
- Screening (
/api/compliance/screening/{business_id}): pep_status: "confirmed_pep" is a hard stop. sanctions_check_status: "confirmed_match" is a hard stop.
- Registry (
/api/compliance/registry/{business_id}): license_expiry before the as-of/review date is a hard stop. Missing or invalid tax_id is a concern.
- Bank (
/api/compliance/bank/{business_id}): bank_account_status: "closed" is a hard stop. bank_account_status: "name_mismatch" means the bank account name does not match the business name.
The consolidated endpoint /api/compliance/objects provides review_status, missing_fields, risk_score, pep_status, sanctions_check_status, bank_account_status, license_expiry, ubo_list, shell_company_suspected, and vendor_id. Use it as the primary source, then drill into sub-endpoints for deeper detail when needed.
Decision logic for per-business decisions:
- escalate — any hard-stop flag applies:
confirmed_pep, sanctions_confirmed, expired_license, bank_closed, shell_company_suspected, vendor_on_hold, or screening_not_run combined with other red flags.
- awaiting_information — non-blocking issues exist:
missing_required_documents, isolated screening_not_run (no other red flags), bank_name_mismatch (needs verification), or incomplete review status.
- approve — zero hard-stop flags and zero follow-up concerns. The business is clean.
Hard-stop flags (derive from compliance data, list alphabetically):
| Flag |
Condition |
bank_closed |
bank_account_status is closed |
bank_name_mismatch |
bank_account_status is name_mismatch |
confirmed_pep |
pep_status is confirmed_pep |
expired_license |
license_expiry date is before the review/as_of date |
missing_required_documents |
missing_fields is non-empty |
sanctions_confirmed |
sanctions_check_status is confirmed_match |
screening_not_run |
pep_status or sanctions_check_status is missing, null, or not_run |
shell_company_suspected |
shell_company_suspected is true |
vendor_on_hold |
vendor/business status is inactive or suspended |
follow_up_business_ids includes every business_id whose decision is not approve.
overall_release_ready is true only when every listed business decision is approve.
Business IDs to Vendor Records (Account-Change Payment Release)
When reviewing payment release after account-change events, cross-reference the batch business IDs against vendor and compliance data:
- Check
requested_bank_last4 from the change ticket against bank_account_last4 from /api/vendors (filter by vendor_id). Mismatch is a blocking concern.
- Check
tax_id consistency between /api/compliance/registry/{business_id} and /api/vendors. Mismatch = invalid_tax_ids.
- Check
license_expiry against the review date. Expired = expired_license_ids.
- Check
risk_score >= 70 from compliance = risk_score_override_flags.
- Decision:
release when zero issues; hold when non-critical issues (bank mismatch, expired license, missing docs, no sanctions/PEP risk); escalate when critical flags (confirmed PEP, sanctions match, shell company, multiple red flags, or vendor_on_hold).
review_queue_ids contains every business_id that is not release.
Prepaid Invoices to GL Balances
All prepaid invoices use straight-line monthly amortization.
Per-invoice computations:
monthly_amortization — the value from the invoice record.
cumulative_amortization_through_period — count full calendar months from service_start month through the close period month, inclusive (e.g., Jan 1 through March = 3 months), capped at service_end. Multiply by monthly_amortization.
ending_balance = original_amount - cumulative_amortization_through_period. Floor at 0.00.
default_missing_term_flag — true when data_quality_flags includes missing_contract_dates or rounded_amount, or when monthly_amortization is 0/null and a default was assumed.
exception_flag — true when (a) ending_balance is 0.00 (fully amortized, possibly stale), or (b) data_quality_flags is non-empty, or (c) there is an amortization anomaly (e.g., original_amount does not align with expected term).
Account-level rollup (account_rollup):
account_name — from GL balance record.
selected_invoice_count — count of scoped invoices for that account.
original_amount_total — sum of all scoped invoice original_amount values.
march_amortization_total (or period equivalent) — sum of all scoped invoice monthly_amortization values.
cumulative_amortization_through_period — sum of per-invoice cumulative values.
schedule_ending_balance — sum of per-invoice ending_balance values.
gl_ending_balance — from /api/prepaids/gl-balances filtered by period, account, entity.
variance_amount = schedule_ending_balance - gl_ending_balance.
variance_flag — true when |variance_amount| > variance_threshold_abs.
has_default_missing_term_flag — true when any scoped invoice has that flag.
account_status — reconciled when variance_flag is false and has_default_missing_term_flag is false; variance_review when variance_flag is true but the variance is modest; requires_reconciliation when variance_flag is true and has_default_missing_term_flag is also true, or when variance is very large.
GL balance lookup: filter /api/prepaids/gl-balances by period, account, and entity. Use the ending_balance field for the close period.
Stale Snapshot Reconciliation
When a task provides a local CSV/JSON snapshot of AP data and directs you to reconcile against the live API:
- Fetch current claim, bill, and payment records for each candidate
claim_id from the live API.
- For each claim, compare the snapshot row against current state and assign a correction code:
current_snapshot_ok — snapshot matches current live state.
mark_in_flight_payment — a payment exists but has not cleared yet; the snapshot shows none/0.00 for payment.
replace_with_matched_paid_bill — snapshot bill_id is stale/wrong; the live system has a different bill that is paid.
exclude_amount_or_vendor_mismatch — claim amount or vendor does not match the linked bill.
ignore_void_bill — snapshot bill_id now has status void in the live system.
block_unapproved_claim — current claim status in the live API is not approved (e.g., rejected, denied, submitted).
- Compute
ap_balance_by_claim: for each claim, the open AP balance from current bill/payment data (bill amount minus cleared payments). Paid/settled claims = 0.00.
eligible_claim_ids — claims where live data supports keeping them in the batch (approved claims with valid unpaid or in-flight bills).
not_ready_claim_ids — blocked or already settled claims.
close_log_required — check /api/close/logs for relevant period entries with status: "open" or status: "ready_for_review" related to AP or Expense area. Include those log IDs.
batch_status — ready_to_send when all claims are eligible and no close log blocks; needs_ap_refresh when corrections are needed or close logs remain open; blocked when any claim is blocked.
General Output Conventions
- Sorting: All ID lists sorted ascending by ID (lexicographic for claim IDs, business IDs, invoice IDs, close log IDs).
- Currency: All amounts in USD, reported to 2 decimal places as numbers (not strings). Use
0.00 not 0 when the template expects decimal precision.
- JSON only: Return only the JSON object conforming to the answer template. No explanatory text or markdown outside the JSON.
- Template fidelity: Match every required key exactly. Preserve the key ordering shown in the template. Use only the allowed enum values.
- Zero vs. empty: Empty lists use
[]. Zero amounts use 0 or 0.00 as appropriate. Never use null for a required field.
- Counts match: The sum of IDs across categories (payable + blocked + paid, or eligible + not_ready) must equal the total reviewed claim count.
General Workflow
- Read the prompt to identify the task type and target batch of IDs.
- Locate the answer template in
input/payloads/ and understand every required field, enum, and ordering constraint.
- Fetch data from the live API for all relevant IDs. Make parallel requests when endpoints are independent (claims, bills, payments, vendors, compliance, prepaids, GL, close logs).
- Cross-reference data following the patterns in this document.
- Apply the business rules to classify each ID and detect exceptions.
- Compute summary totals (balances, counts, flags) at both item and aggregate levels.
- Assemble the JSON output conforming exactly to the template structure.
- Validate sorting, precision, enum values, and that every required key is present before finalizing.
Common Pitfalls
- Do not trust
claim.status === "paid" without verifying a bill and cleared payment exist. The claim status may be stale.
- A scheduled payment is not a cleared payment. Only
cleared payments reduce an AP balance.
- UBO counts: Count unique owner names, not list entries. A single person with two ownership percentage entries counts as one UBO. Only include those with
ownership_pct >= 25.
- Period boundaries: When computing cumulative amortization, count full calendar months inclusive. A March 1 start with a March close period = 1 month of amortization. A January 1 start with a March close period = 3 months.
- Close log relevance: Filter by period and area (AP, Expense, Prepaids, Compliance). An open or ready_for_review log in a related area means the close cycle is not complete and blocks finalization.
- License expiry comparison: Compare the expiry date string against the review/as_of date string. If expiry is strictly before (less than) the review date, the license is expired.
- Amount matching precision: When comparing claim.amount to bill.amount, tolerate small rounding differences (under $1) but flag material mismatches.
- Vendor_id on claims: A claim may have
vendor_id: null. That is not a mismatch; only compare when both claim and bill have non-null vendor_ids and they differ.
1---2name: finance-operations-review3description: Reconcile finance and compliance review batches against a shared ERP/compliance API. Covers claim-to-AP matching, vendor onboarding risk review, prepaid close reconciliations, stale AP snapshot corrections, and account-change payment-release decisions. Use when a task provides a batch of IDs to review against the task_env API and expects a structured JSON decision output.4metadata:5 source: https://skillmd.com/skills/prism-shadow/finance-operations-review6---78# Finance Operations Batch Review910## API Access1112The task environment exposes a shared ERP/compliance API at the base URL the runner provides as `<TASK_ENV_BASE_URL>`. All endpoints return JSON arrays wrapped in `{"count": N, "data": [...]}`. Use exact-match query parameters by field name; paginate with `limit` and `offset`.1314### Available Endpoints1516| Endpoint | Purpose |17|---|---|18| `GET /api/claims` | Employee expense claims |19| `GET /api/ap/bills` | AP bills (may link to claims via `claim_id`) |20| `GET /api/ap/payments` | Payment records linked to bills via `bill_id` |21| `GET /api/ap/aging` | AP aging with `balance`, `paid_amount` per bill |22| `GET /api/vendors` | Vendor master with bank, tax, status |23| `GET /api/compliance/objects` | Consolidated compliance records per business_id |24| `GET /api/compliance/ownership/{business_id}` | UBO list with ownership_pct and shell_company flag |25| `GET /api/compliance/registry/{business_id}` | Jurisdiction, license_expiry, tax_id, registration |26| `GET /api/compliance/screening/{business_id}` | PEP status, sanctions check |27| `GET /api/compliance/bank/{business_id}` | Bank account verification status |28| `GET /api/prepaids/invoices` | Prepaid invoice schedules with monthly_amortization |29| `GET /api/prepaids/gl-balances` or `GET /api/gl/balances` | GL ending balances per account/period/entity |30| `GET /api/close/logs` | Period-close log entries with area, status, message |3132Both `/api/prepaids/gl-balances` and `/api/gl/balances` return the same data; use whichever is available. Similarly, `/claims` is an alias for `/api/claims`, `/bills` for `/api/ap/bills`, etc.3334---3536## Cross-Reference Patterns3738### Claims to AP Bills to Payments3940Link claims to AP using `claim_id` on bills. Link bills to payments using `bill_id` on payments.4142**Claim status values**: `approved`, `paid`, `rejected`, `submitted`, `needs_receipt`, `in_review`, `denied`.4344**Bill status values**: `approved`, `scheduled`, `paid`, `void`, `pending`, `rejected`.4546**Payment status values**: `cleared`, `processing`, `scheduled`, `failed`.4748**Key rules**:4950- A claim is **paid** (settled) only when: a bill with matching `claim_id` exists, the bill status is `paid`, and at least one `cleared` payment exists for that bill covering the full bill amount. Do not rely on `claim.status === "paid"` alone; verify the bill and payment chain.51- A claim is **blocked** (not ready for AP release) when: the claim status is not `approved` (e.g., `rejected`, `denied`, `needs_receipt`, `submitted`), or the linked bill has a blocking status (`void`, `rejected`), or no bill exists at all, or there is a vendor mismatch between the claim's vendor_id (if present) and the bill's vendor_id, or there is a material amount mismatch between claim and bill.52- A claim is **payable** when: the claim is `approved`, a valid linked bill exists and is not `paid` or `void`, and no blocking conditions apply.53- **AP open balance** for a payable claim = bill.amount minus the sum of all cleared payments for that bill. Use the `balance` field from `/api/ap/aging` when available; otherwise compute from bills and payments.54- A **scheduled** payment is not a cleared payment. Only `cleared` payments close out a bill balance.5556### Business IDs to Compliance Records5758Cross-reference each business ID across four compliance dimensions:59601. **Ownership** (`/api/compliance/ownership/{business_id}`): Count unique beneficial owner **names** (not entries) with `ownership_pct >= 25` as reportable UBOs. A person appearing twice with different percentages counts as one UBO. `shell_company_suspected: true` is a hard stop.612. **Screening** (`/api/compliance/screening/{business_id}`): `pep_status: "confirmed_pep"` is a hard stop. `sanctions_check_status: "confirmed_match"` is a hard stop.623. **Registry** (`/api/compliance/registry/{business_id}`): `license_expiry` before the as-of/review date is a hard stop. Missing or invalid `tax_id` is a concern.634. **Bank** (`/api/compliance/bank/{business_id}`): `bank_account_status: "closed"` is a hard stop. `bank_account_status: "name_mismatch"` means the bank account name does not match the business name.6465The consolidated endpoint `/api/compliance/objects` provides `review_status`, `missing_fields`, `risk_score`, `pep_status`, `sanctions_check_status`, `bank_account_status`, `license_expiry`, `ubo_list`, `shell_company_suspected`, and `vendor_id`. Use it as the primary source, then drill into sub-endpoints for deeper detail when needed.6667**Decision logic** for per-business decisions:6869- **escalate** — any hard-stop flag applies: `confirmed_pep`, `sanctions_confirmed`, `expired_license`, `bank_closed`, `shell_company_suspected`, `vendor_on_hold`, or `screening_not_run` combined with other red flags.70- **awaiting_information** — non-blocking issues exist: `missing_required_documents`, isolated `screening_not_run` (no other red flags), `bank_name_mismatch` (needs verification), or incomplete review status.71- **approve** — zero hard-stop flags and zero follow-up concerns. The business is clean.7273**Hard-stop flags** (derive from compliance data, list alphabetically):7475| Flag | Condition |76|---|---|77| `bank_closed` | bank_account_status is `closed` |78| `bank_name_mismatch` | bank_account_status is `name_mismatch` |79| `confirmed_pep` | pep_status is `confirmed_pep` |80| `expired_license` | license_expiry date is before the review/as_of date |81| `missing_required_documents` | missing_fields is non-empty |82| `sanctions_confirmed` | sanctions_check_status is `confirmed_match` |83| `screening_not_run` | pep_status or sanctions_check_status is missing, null, or `not_run` |84| `shell_company_suspected` | shell_company_suspected is true |85| `vendor_on_hold` | vendor/business status is inactive or suspended |8687**`follow_up_business_ids`** includes every business_id whose decision is not `approve`.8889**`overall_release_ready`** is `true` only when every listed business decision is `approve`.9091### Business IDs to Vendor Records (Account-Change Payment Release)9293When reviewing payment release after account-change events, cross-reference the batch business IDs against vendor and compliance data:9495- Check `requested_bank_last4` from the change ticket against `bank_account_last4` from `/api/vendors` (filter by `vendor_id`). Mismatch is a blocking concern.96- Check `tax_id` consistency between `/api/compliance/registry/{business_id}` and `/api/vendors`. Mismatch = `invalid_tax_ids`.97- Check `license_expiry` against the review date. Expired = `expired_license_ids`.98- Check `risk_score >= 70` from compliance = `risk_score_override_flags`.99- Decision: `release` when zero issues; `hold` when non-critical issues (bank mismatch, expired license, missing docs, no sanctions/PEP risk); `escalate` when critical flags (confirmed PEP, sanctions match, shell company, multiple red flags, or vendor_on_hold).100- `review_queue_ids` contains every business_id that is not `release`.101102### Prepaid Invoices to GL Balances103104All prepaid invoices use **straight-line monthly amortization**.105106**Per-invoice computations**:107108- `monthly_amortization` — the value from the invoice record.109- `cumulative_amortization_through_period` — count full calendar months from `service_start` month through the close period month, inclusive (e.g., Jan 1 through March = 3 months), capped at `service_end`. Multiply by `monthly_amortization`.110- `ending_balance` = `original_amount` - `cumulative_amortization_through_period`. Floor at 0.00.111- `default_missing_term_flag` — true when `data_quality_flags` includes `missing_contract_dates` or `rounded_amount`, or when `monthly_amortization` is 0/null and a default was assumed.112- `exception_flag` — true when (a) `ending_balance` is 0.00 (fully amortized, possibly stale), or (b) `data_quality_flags` is non-empty, or (c) there is an amortization anomaly (e.g., original_amount does not align with expected term).113114**Account-level rollup** (`account_rollup`):115116- `account_name` — from GL balance record.117- `selected_invoice_count` — count of scoped invoices for that account.118- `original_amount_total` — sum of all scoped invoice `original_amount` values.119- `march_amortization_total` (or period equivalent) — sum of all scoped invoice `monthly_amortization` values.120- `cumulative_amortization_through_period` — sum of per-invoice cumulative values.121- `schedule_ending_balance` — sum of per-invoice `ending_balance` values.122- `gl_ending_balance` — from `/api/prepaids/gl-balances` filtered by period, account, entity.123- `variance_amount` = `schedule_ending_balance` - `gl_ending_balance`.124- `variance_flag` — true when `|variance_amount| > variance_threshold_abs`.125- `has_default_missing_term_flag` — true when any scoped invoice has that flag.126- `account_status` — `reconciled` when variance_flag is false and has_default_missing_term_flag is false; `variance_review` when variance_flag is true but the variance is modest; `requires_reconciliation` when variance_flag is true and has_default_missing_term_flag is also true, or when variance is very large.127128**GL balance lookup**: filter `/api/prepaids/gl-balances` by `period`, `account`, and `entity`. Use the `ending_balance` field for the close period.129130---131132## Stale Snapshot Reconciliation133134When a task provides a local CSV/JSON snapshot of AP data and directs you to reconcile against the live API:1351361. Fetch current claim, bill, and payment records for each candidate `claim_id` from the live API.1372. For each claim, compare the snapshot row against current state and assign a correction code:138 - `current_snapshot_ok` — snapshot matches current live state.139 - `mark_in_flight_payment` — a payment exists but has not cleared yet; the snapshot shows `none`/`0.00` for payment.140 - `replace_with_matched_paid_bill` — snapshot `bill_id` is stale/wrong; the live system has a different bill that is paid.141 - `exclude_amount_or_vendor_mismatch` — claim amount or vendor does not match the linked bill.142 - `ignore_void_bill` — snapshot `bill_id` now has status `void` in the live system.143 - `block_unapproved_claim` — current claim status in the live API is not `approved` (e.g., `rejected`, `denied`, `submitted`).1443. Compute `ap_balance_by_claim`: for each claim, the open AP balance from current bill/payment data (bill amount minus cleared payments). Paid/settled claims = `0.00`.1454. `eligible_claim_ids` — claims where live data supports keeping them in the batch (approved claims with valid unpaid or in-flight bills).1465. `not_ready_claim_ids` — blocked or already settled claims.1476. `close_log_required` — check `/api/close/logs` for relevant period entries with `status: "open"` or `status: "ready_for_review"` related to AP or Expense area. Include those log IDs.1487. `batch_status` — `ready_to_send` when all claims are eligible and no close log blocks; `needs_ap_refresh` when corrections are needed or close logs remain open; `blocked` when any claim is blocked.149150---151152## General Output Conventions153154- **Sorting**: All ID lists sorted ascending by ID (lexicographic for claim IDs, business IDs, invoice IDs, close log IDs).155- **Currency**: All amounts in USD, reported to 2 decimal places as numbers (not strings). Use `0.00` not `0` when the template expects decimal precision.156- **JSON only**: Return only the JSON object conforming to the answer template. No explanatory text or markdown outside the JSON.157- **Template fidelity**: Match every required key exactly. Preserve the key ordering shown in the template. Use only the allowed enum values.158- **Zero vs. empty**: Empty lists use `[]`. Zero amounts use `0` or `0.00` as appropriate. Never use `null` for a required field.159- **Counts match**: The sum of IDs across categories (payable + blocked + paid, or eligible + not_ready) must equal the total reviewed claim count.160161---162163## General Workflow1641651. Read the prompt to identify the task type and target batch of IDs.1662. Locate the answer template in `input/payloads/` and understand every required field, enum, and ordering constraint.1673. Fetch data from the live API for all relevant IDs. Make parallel requests when endpoints are independent (claims, bills, payments, vendors, compliance, prepaids, GL, close logs).1684. Cross-reference data following the patterns in this document.1695. Apply the business rules to classify each ID and detect exceptions.1706. Compute summary totals (balances, counts, flags) at both item and aggregate levels.1717. Assemble the JSON output conforming exactly to the template structure.1728. Validate sorting, precision, enum values, and that every required key is present before finalizing.173174---175176## Common Pitfalls177178- **Do not trust `claim.status === "paid"`** without verifying a bill and cleared payment exist. The claim status may be stale.179- **A scheduled payment is not a cleared payment.** Only `cleared` payments reduce an AP balance.180- **UBO counts**: Count unique owner names, not list entries. A single person with two ownership percentage entries counts as one UBO. Only include those with `ownership_pct >= 25`.181- **Period boundaries**: When computing cumulative amortization, count full calendar months inclusive. A March 1 start with a March close period = 1 month of amortization. A January 1 start with a March close period = 3 months.182- **Close log relevance**: Filter by period and area (AP, Expense, Prepaids, Compliance). An open or ready_for_review log in a related area means the close cycle is not complete and blocks finalization.183- **License expiry comparison**: Compare the expiry date string against the review/as_of date string. If expiry is strictly before (less than) the review date, the license is expired.184- **Amount matching precision**: When comparing claim.amount to bill.amount, tolerate small rounding differences (under $1) but flag material mismatches.185- **Vendor_id on claims**: A claim may have `vendor_id: null`. That is not a mismatch; only compare when both claim and bill have non-null vendor_ids and they differ.