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 direct file upload followed by asynchronous processing. 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 entities. Their full schemas are documented per route — this list is the catalog:

  • 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.

Every entity belongs to a portfolio in your organization. The portfolio is supplied with every write; the organization comes 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 organization-scoped — a token issued to organization A cannot read or write organization B's data, and cross-organization reads return 404 Not Found rather than 403 Forbidden to avoid leaking the existence of another tenant's resources.

The full authentication and authorization 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 honors: authentication, the integration guarantees (caller-supplied IDs, idempotency, dry runs), error envelopes, money and date conventions, cancellation semantics, and how every submission is recorded.
  • 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 catalog 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 organization, 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 are not covered here.
  • Webhooks and scheduled tape delivery — not covered here.