Choose your integration path
Two decisions define your integration. Both are recorded per organisation during onboarding (you state a preference on the application form; the technical configuration is entered by Fieldproof ops in the CRM). To change either later, contact your integration contact ([email protected]) — there is no self-serve configuration API.
Decision 1 — How do your cases reach us?
Direction matters here: with push, you call us; with pull, we call you.
| Push API (recommended) | Pull API | CSV | |
|---|---|---|---|
| Direction | You call us — POST /api/v1/partner/cases with batches of overdue loans | We call you — Fieldproof fetches GET <your pull URL>?cursor=&limit=500 | You send a file; Fieldproof ops imports it |
| Freshness | Immediate | Every 30 minutes (global schedule, not per-org) | Manual |
| Validation feedback | Per-row errors[] in the response; ?dryRun=1 validates without writing | Per-row errors are not surfaced back to you — check GET /cases/{loan} or the poll feed | Not returned programmatically — check GET /cases/{loan} or the poll feed |
fullSnapshot (flag cases missing from your open book) | Yes | Never applied on pull | — |
| You build | Outbound HTTPS client with request signing | One HTTPS, publicly reachable GET endpoint returning { rows, nextCursor, hasMore } (contract) | Nothing — a file with our exact column headers (format) |
| Best for | Teams with engineering capacity who want immediate ingest and validation | Systems that cannot make outbound calls | Getting started before any build |
Push and pull share the same row contract
(sourceLoanNumber, borrower.*, loan.*). CSV uses its own header names
(LoanNo, CustomerName, mobile, Pincode, Due Amount, …) — the dotted
JSON names are not accepted as CSV headers.
Decision 2 — How does money reach you?
Always directly. Fieldproof never holds or routes your borrowers' funds,
and cash is never accepted on your cases — the partner app blocks it and
the confirm endpoint rejects mode: "cash". You choose the rail:
Mode A: static QR / bank (manual) | Mode B: your gateway's links (org_gateway) | |
|---|---|---|
| Borrower pays via | Your static UPI QR / UPI ID / bank details, shown by the partner | A payment link minted by your gateway, requested from a mint endpoint you host |
| Confirmation | Partner uploads proof → Fieldproof ops verifies (OCR-assisted UTR/amount) → payment.collected with the operator-confirmed amount | You call POST /cases/{loan}/payments/confirm when your gateway captures — gateway captures never reach us on their own |
| Fallback if your side is down | Not applicable — you host nothing | None: if your mint endpoint does not answer 200, the agent sees "link unavailable" and retries later |
| You build | Nothing | A mint-link endpoint (HTTPS, public, answers within 10 s) + one confirm call from your gateway webhook handler or poller |
| Best for | Fastest start; no gateway required | Fully automatic, instant confirmation, borrower pays online |
Decision table
| If you… | Cases in | Money |
|---|---|---|
| Have engineers and want immediate ingest with per-row feedback | Push | — |
| Cannot make outbound HTTPS calls but can host a read endpoint | Pull | — |
| Want to start today with no build at all | CSV | Mode A |
| Already run a payment gateway that mints links and webhooks captures to you | — | Mode B |
| Have no gateway, or want zero payment code | — | Mode A |
Need fullSnapshot reconciliation of your open book | Push only | — |
The requirement matrix
You build / provide
- Application details (what exactly)
- Push: an API client that signs requests
- Pull: one cursor-paged, publicly reachable HTTPS
GETendpoint - CSV: a file with our exact column headers
- A webhook receiver (HTTPS, public IP, verifies signatures, dedupes on
eventId) — or use the poll API instead - Mode A: your static QR image / UPI ID / bank details
- Mode B: a mint-link endpoint + a
payments/confirmcall on capture - Your RBI regulatory disclosure text (shown to the borrower on the agent's payment/ID screens)
We provide
- Sandbox + production credentials and this documentation
- The entire field operation: partner network, visits, assignment
- Case management and per-row validation
- Signed webhooks with a retry ladder, a poll API, delivery log + self-serve replay
- Proof verification (Mode A) and the payment ledger either way
- The reference implementation of every contract you need to build, on request
Whichever you choose, the event stream is identical — switching paths later doesn't change your webhook receiver.