Waafir
API Reference

API Reference

This section is the reference manual for the Waafir loan-domain API — the HTTP surface fintechs use to stream portfolio data into Waafir for investor monitoring. It documents every route under /api/v1/monitoring/loan/, the request and response schemas, every status code, the shared developer-experience contract, and the error envelopes you should expect.

The reference is exhaustive but not narrative. If you are integrating for the first time and want a guided end-to-end recipe — with side-by-side cURL, TypeScript, and Python — read the cookbook alongside this reference; the two are designed to be read together.

What the API covers

The loan-domain API exposes four ingestion shapes plus a reconciliation surface:

  • Single-record CRUD — one HTTP call per row. Use for low-volume operational writes: a single new loan, a single payment, a status transition.
  • Bulk NDJSON — up to ten thousand rows in one synchronous call. Use for end-of-day batches that fit in a single HTTP request.
  • Async imports — a presigned S3 upload followed by an asynchronous worker. Use for historical loads or any batch above ten thousand rows.
  • Reconciliation — read-back of submitted rows by your own caller IDs, and per-entity row counts. Use to verify that yesterday's submission landed cleanly before you submit today's.

Each shape is covered on its own page. The page order matches the order most integrators traverse them: read the overview, then the ingestion mode you plan to use first, then reconciliation, then the error reference.

The six loan-domain entities

Every route operates on one or more of the following silver entities. Their full schemas are documented per route — this list is the catalogue:

  • borrower — the natural or legal person taking the loan, with optional PII fields that mask on read.
  • loan — the loan agreement itself: principal, currency, APR, term, repayment frequency, status.
  • scheduled_repayment — the contractual repayment schedule, one row per due date.
  • actual_payment — the actual payments received, including write-offs and partial payments.
  • collateral — collateral pledged against a loan.
  • collateral_valuation — point-in-time valuations of a collateral row, supporting multiple methods.

The entities are tenancy-anchored on the (org_id, portfolio_id) pair. The portfolio_id is supplied with every write; the org_id is derived from your personal access token and never appears in a request body.

Authentication in one line

Every request carries Authorization: Bearer <PAT> where <PAT> is a personal access token issued by the Waafir control plane. Tokens are organisation-scoped — a token issued to organisation A cannot read or write organisation B's data, and cross-organisation reads return 404 Not Found rather than 403 Forbidden to avoid leaking the existence of another tenant's resources.

The full authentication and authorisation model is covered in the overview.

How to use this reference

Read the pages in order, or jump to the surface you need:

  • Overview — the shared contract every loan-domain route honours: authentication, the developer-experience bar (caller-supplied IDs, idempotency, dry runs), error envelopes, money and date conventions, soft-delete semantics, and the bronze-first archive invariant.
  • Single-record CRUD — every single-row POST, GET, PATCH, and cancel route.
  • Bulk NDJSON — synchronous bulk ingestion with per-row error reporting.
  • Async imports — the two-phase upload, status polling, and error paging lifecycle.
  • Reconciliation — read-back by caller ID and per-entity row counts.
  • Errors and status codes — the consolidated catalogue of every status code, error envelope, and named error code emitted by the loan-domain surface.

For task-oriented guides — onboarding a portfolio end-to-end, running a daily reconcile, recovering from a partially-failed import — see the cookbook (shipping alongside this reference). The cookbook walks each task in three languages; this reference is the source of truth for what each route accepts and returns.

What is not in this reference

  • Onboarding and tokens — how to register an organisation, create a portfolio, and issue a personal access token. Those workflows are covered in the platform administration docs and the cookbook's getting-started recipe.
  • Investor-facing analytics — chart packs, the tape export, and the loan-tape download surface. Those ship behind separate routes and have their own reference once they leave preview.
  • Architecture and design rationale — the medallion model, the bronze archive, the silver normalisation worker. These are explained briefly where they affect API behaviour; the full architectural story lives in the implementation notes under the platform's developer documentation.
  • Webhooks and scheduled tape delivery — neither ships in v1.