Developers//customers
Customers
PAN-keyed borrower profiles — KYC, businesses, climate classification and a deterministic profile score.
Customers
A customer is a PAN-keyed borrower profile: one person, with their whole history — statement analyses, credit checks and Account Aggregator syncs — on a single timeline. On top of that history a customer now carries a KYC profile, the borrower's businesses (a person may run several, each with a climate classification), and a deterministic profile score. Customers are scoped to your team and reachable over the REST API, the SDK and the MCP server.
Endpoints
| Method | Path | Description |
|---|---|---|
POST | /v1/customers | Create a customer. Idempotent on PAN: an existing PAN returns the existing profile (200), a new one is created (201) |
GET | /v1/customers | List/search customers (q, limit, offset) — q matches name / PAN / mobile / ref |
GET | /v1/customers/catalog | The KYC vocabulary (employment types, loan purposes, business categories, …) the profile and business bodies validate against |
GET | /v1/customers/{id} | One customer's full profile incl. timeline, signals, profile, businesses, portfolio and profile_intelligence — id is the uuid or the ref (CUS-000001) |
PATCH | /v1/customers/{id} | Update name, mobile, email, notes or status |
POST | /v1/customers/{id}/attach | Attach an analysis, credit check or AA consent to the timeline |
GET | /v1/customers/{id}/profile | The borrower's KYC profile (null if none set) |
PUT | /v1/customers/{id}/profile | Create or update the KYC profile (partial — only the fields sent are written; null clears a field) |
GET | /v1/customers/{id}/businesses | The borrower's businesses, each with its climate classification and any location intelligence |
POST | /v1/customers/{id}/businesses | Add a business (name required, category from the catalog) |
PATCH | /v1/customers/{id}/businesses/{businessId} | Update one business (partial) |
DELETE | /v1/customers/{id}/businesses/{businessId} | Delete one business |
All endpoints authenticate with a Bearer token and are team-scoped, exactly like the app.
Create a customer
POST /v1/customers is JSON { pan, name, mobile, email? }. It is idempotent on the PAN: if a customer
with that PAN already exists it is returned as-is (HTTP 200); otherwise a new one is created (HTTP 201).
curl -X POST https://api.ippo.one/v1/customers \
-H "Authorization: Bearer $LOANPILOT_API_KEY" \
-H "content-type: application/json" \
-d '{"pan":"ABCDE1234F","name":"Asha Rao","mobile":"9876543210","email":"asha@example.com"}'Returns a Customer with the PAN masked, a readable ref (CUS-000001) and an (initially empty) timeline.
List / search
GET /v1/customers?q=&limit=&offset= returns { items: CustomerSummary[], total }. q searches the name,
PAN, mobile and ref.
curl "https://api.ippo.one/v1/customers?q=asha&limit=20" \
-H "Authorization: Bearer $LOANPILOT_API_KEY"Read one
GET /v1/customers/{id} takes the uuid or the readable ref (CUS-000001) and returns the full Customer.
Alongside the timeline (every event) and signals (the latest monitoring state) it now carries:
profile— the borrower's KYC (ornull).businesses— every business, each with itsclimate_classificationand anylocation_intel.portfolio— a cross-business aggregate for a borrower who runs more than one.profile_intelligence— a deterministic, rule-based profile score (always present, no AI needed).
Update
PATCH /v1/customers/{id} with any of { name?, mobile?, email?, notes?, status? } (status is
active or archived).
Attach history
POST /v1/customers/{id}/attach with { kind, id } links an existing record to the customer's timeline.
kind is analysis, credit_check or aa_consent; id is that record's id.
curl -X POST https://api.ippo.one/v1/customers/CUS-000001/attach \
-H "Authorization: Bearer $LOANPILOT_API_KEY" \
-H "content-type: application/json" \
-d '{"kind":"analysis","id":"..."}'The KYC vocabulary
GET /v1/customers/catalog returns the controlled vocabulary the profile and business bodies validate against —
employment_types, loan_purposes, legal_types, residence_types, premises_types, marital_status,
genders, category_groups, and business_categories (a 76-category India vocabulary in 14 groups, each tagged
with whether the trade is climate-sensitive). It is static per deploy — fetch it once and cache it. Send the
keys from this catalog in profile and business bodies; an unknown value is rejected rather than stored.
KYC profile
GET /v1/customers/{id}/profile returns the borrower's KYC (or null). PUT /v1/customers/{id}/profile is an
upsert: only the fields you send are written, so an officer can fill it in stages; an explicit null clears a
field. It is refreshed on repeat lending. Every field is optional:
| Group | Fields |
|---|---|
| Personal | date_of_birth, gender, marital_status, dependents |
| Residence | address_line, city, state, pincode, region, residence_type (owned / rented / …), years_at_residence |
| Work & income | employment_type (salaried / business / self-employed professional / mixed / …), occupation, employer_name, declared_monthly_income |
| This loan | loan_purpose, purpose_detail (why), loan_amount_requested, loan_tenure_months, spend_region |
| Existing debt | existing_loans — a list of { lender, kind, emi, outstanding, closes_on } the borrower declares |
Enum fields (gender, marital_status, residence_type, employment_type, loan_purpose) take keys from the
catalog.
curl -X PUT https://api.ippo.one/v1/customers/CUS-000001/profile \
-H "Authorization: Bearer $LOANPILOT_API_KEY" \
-H "content-type: application/json" \
-d '{"employment_type":"business","declared_monthly_income":120000,"loan_purpose":"working_capital","dependents":2}'Businesses
A borrower can run several businesses, each read and written on its own.
GET /v1/customers/{id}/businesses→{ items: Business[] }.POST /v1/customers/{id}/businessesadds one —nameis required andcategorymust be a key from the catalog.PATCH /v1/customers/{id}/businesses/{businessId}updates one (partial — only the fields sent are written).DELETE /v1/customers/{id}/businesses/{businessId}removes one.
A business carries: name, category + sub_category, legal_type, gstin, vintage_years,
monthly_turnover, employees, is_primary, premises_type, the shop location (address_line, city,
state, pincode, lat, lng), and notes. Each one is returned with a derived climate_classification —
{ level: "none" | "low" | "medium" | "high", drivers: [...] }. Climate is classified, not asked: it is
seeded from whether the category is weather/season-sensitive and refined from the location intelligence. The
cross-business portfolio aggregate on the customer detail sums turnover and employees and flags whether the
businesses share a location or climate exposure.
curl -X POST https://api.ippo.one/v1/customers/CUS-000001/businesses \
-H "Authorization: Bearer $LOANPILOT_API_KEY" \
-H "content-type: application/json" \
-d '{"name":"Rao Provision Store","category":"grocery_kirana","city":"Nashik","pincode":"422001","monthly_turnover":450000}'SDK
import { LoanPilot } from '@ippopone/loanpilot'
const lp = new LoanPilot({ apiKey: process.env.LOANPILOT_API_KEY! })
// idempotent on PAN
const customer = await lp.customers.create({
pan: 'ABCDE1234F',
name: 'Asha Rao',
mobile: '9876543210',
email: 'asha@example.com',
})
await lp.customers.list({ q: 'asha', limit: 20, offset: 0 })
const full = await lp.customers.get(customer.ref) // uuid or CUS-000001
await lp.customers.update(customer.id, { notes: 'Repeat borrower', status: 'active' })
await lp.customers.attach(customer.id, { kind: 'analysis', id: analysisId })
// KYC profile + businesses
const catalog = await lp.customers.catalog() // the controlled vocabulary
await lp.customers.putProfile(customer.id, { employment_type: 'business', declared_monthly_income: 120000 })
const profile = await lp.customers.getProfile(customer.id)
const biz = await lp.customers.addBusiness(customer.id, { name: 'Rao Provision Store', category: 'grocery_kirana', city: 'Nashik' })
await lp.customers.businesses(customer.id)
await lp.customers.updateBusiness(customer.id, biz.id, { monthly_turnover: 450000 })
await lp.customers.removeBusiness(customer.id, biz.id)
console.log(full.pan_masked, full.portfolio, full.profile_intelligence)MCP tools
create_customer— create a customer (idempotent on PAN):pan,name,mobile,email?list_customers— search/list customers;qmatches name / PAN / mobile / refget_customer— one customer's full profile incl. timeline, signals, KYC, businesses and portfolio (by uuid or ref)update_customer— updatename/mobile/email/notes/statusattach_to_customer— attach ananalysis/credit_check/aa_consent(passkind+attach_id)get_customer_catalog— the KYC vocabulary (employment types, loan purposes, business categories, …)get_customer_profile/update_customer_profile— read and upsert the borrower's KYC (partial;nullclears a field)list_customer_businesses/add_customer_business/update_customer_business/remove_customer_business— the borrower's businesses (namerequired,categoryfrom the catalog)