Docs

Developers/customers

Customers

PAN-keyed borrower profiles — KYC, businesses, climate classification and a deterministic profile score.

11 sections

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

MethodPathDescription
POST/v1/customersCreate a customer. Idempotent on PAN: an existing PAN returns the existing profile (200), a new one is created (201)
GET/v1/customersList/search customers (q, limit, offset) — q matches name / PAN / mobile / ref
GET/v1/customers/catalogThe 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}/attachAttach an analysis, credit check or AA consent to the timeline
GET/v1/customers/{id}/profileThe borrower's KYC profile (null if none set)
PUT/v1/customers/{id}/profileCreate or update the KYC profile (partial — only the fields sent are written; null clears a field)
GET/v1/customers/{id}/businessesThe borrower's businesses, each with its climate classification and any location intelligence
POST/v1/customers/{id}/businessesAdd 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.

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 (or null).
  • businesses — every business, each with its climate_classification and any location_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:

GroupFields
Personaldate_of_birth, gender, marital_status, dependents
Residenceaddress_line, city, state, pincode, region, residence_type (owned / rented / …), years_at_residence
Work & incomeemployment_type (salaried / business / self-employed professional / mixed / …), occupation, employer_name, declared_monthly_income
This loanloan_purpose, purpose_detail (why), loan_amount_requested, loan_tenure_months, spend_region
Existing debtexisting_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}/businesses adds one — name is required and category must 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; q matches name / PAN / mobile / ref
  • get_customer — one customer's full profile incl. timeline, signals, KYC, businesses and portfolio (by uuid or ref)
  • update_customer — update name / mobile / email / notes / status
  • attach_to_customer — attach an analysis / credit_check / aa_consent (pass kind + 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; null clears a field)
  • list_customer_businesses / add_customer_business / update_customer_business / remove_customer_business — the borrower's businesses (name required, category from the catalog)