Lead API — Muthoot Gold Loan CRM

Create a lead

POST/leads

Creates a lead in the Muthoot CRM and starts the journey. Only the mobile number is required. A lead can be created without a branch: the Qualification agent, a pincode match, or the branch the customer walks into will assign one.

The same mobile number again does not create a second customer. It adds a touch to the existing one and returns duplicate: true.

Request

Authentication: send your partner key in the x-partner-key header. Keys are issued per partner and kept in the server's .env. The public website form is the one exception in demo mode.

From your website

The website is hosted on its own domain and calls this API over HTTPS. Everything is relative to the base URL shown at the top of this page. A machine-readable spec is at /openapi.json (OpenAPI 3.1).

Two ways to call it

From your server (recommended). Your backend posts the lead with the x-partner-key header. The key never reaches the browser.
From the browser. Allowed from the origins below. Send source: "WEBSITE" and no key. Use only while the API is in demo mode; in production use the server route.

Allowed browser origins: …. Preflight requests are answered automatically. The server setting is CORS_ORIGINS (comma separated; * in demo mode when unset).

What the form should send

`source`	`WEBSITE`. For the voice assistant on the site use `AI_AMITABH`.
`subSource`	Which form: `hero form`, `callback`, `calculator`, `web voice`.
`campaign`	The `utm_campaign` value, if present.
`pincode`	Whatever the visitor entered or the city picker set. Routes the lead to the nearest branch.
`language`	The language the visitor is reading the site in.
`callConsent`, `whatsappConsent`	Only `true` if the visitor saw the consent line next to the button.

Helper endpoints

GET`/branches?pincode=560034`	Branches for the "near you" panel. No key needed.
GET`/config/public`	Indicative gold and interest rates for the calculator. Never a quote.

e-KYC links. The WhatsApp link opens <your website>/ekyc/<token>. Set the server's PUBLIC_WEB_URL to your site's address and keep that page; it calls GET /ekyc/:token, POST /ekyc/:token/renew and POST /ekyc/:token/complete on this API.

Before you go live

Create a test lead with the Try it box below, then find it in the CRM.
Send the same mobile number twice: the second reply must say duplicate: true.
Send a lead with no pincode: it must be accepted and wait in the contact-centre queue.
Send a bad mobile number: expect a 400 with the field in issues[].path.

Branch assignment

No branch needed. A lead can be created without one. It waits in the contact-centre queue.
Pincode. If a pincode is sent and matches a branch, the lead is routed there.
Qualification agent. When the agent qualifies a lead that still has no branch, it assigns one from the confirmed pincode. An agent never moves a lead that already has a branch.
Walk-in always wins. When the customer is checked in at a branch, that branch becomes the lead's branch, even if an agent or a pincode had assigned a different one. The change is recorded as lead.branch_assigned.
Walk-ins with no earlier lead (no form, not a partner lead) are created at the branch they walk into, with source WALK_IN.

Fields

Field	Type	Notes
`phone` required	string	10-digit Indian mobile. `+91` and spaces are accepted.
`name`	string	Optional. Defaults to "New customer". A different name on a known phone is kept as an alias, never a new customer.
`source`	enum	`WEBSITE` `MARKETING_CAMPAIGN` `MARKETING_INBOUND` `PARTNER` `WALK_IN` `FIELD` `AI_AMITABH` `TOLL_FREE` `REFERRAL` `WHATSAPP`. Partner names `GPAY`, `PHONEPE`, `DIALABANK` are accepted and stored as `PARTNER` with a sub-source.
`subSource`	string	For example a campaign ad set, a QR code, a partner name or a call id.
`campaign`	string	Campaign name, kept with the first touch.
`pincode`	string	6 digits. Used to route to a branch.
`branchCode`	string	Optional. Sets the branch directly (for example from a branch system).
`language`	enum	`en` `hi` `mr` `bn` `kn` `ml` `te` `ta` (default `en`). Drives call and WhatsApp language.
`amountAsked`, `grams`	number	Rupees and grams of gold, as stated by the customer. Indicative only.
`callConsent`, `whatsappConsent`	boolean	Default `true`. Consent is recorded with the time and the source.
`contactWindow`	enum	`MORNING` `AFTERNOON` `EVENING` `ANYTIME`

Responses

Status	Meaning
`201`	New lead created.
`200`	The mobile number already exists: a touch was added, `duplicate: true`.
`400`	Validation failed: `{ "error": "invalid_request", "issues": [{ "path": "phone", "message": "…" }] }`
`401`	Missing or wrong `x-partner-key`.

{
  "journeyId": "…",
  "personId": "…",
  "duplicate": false,
  "stage": "LEAD"
}

Try it

Sends a real lead to this server with source WEBSITE (no key needed in demo mode). Use the Demo Console to see it appear.

Mobile number Name Pincode (optional) Language

Other endpoints

PATCH`/leads/:id`	Add detail later: `amountAsked`, `grams`, `useCase`.
GET`/journeys`	All journeys, newest first.
GET`/journeys/:id`	One journey with its interactions.
GET`/lms/loans/:loanNo`	Loan and quote from the loan system (needs `x-partner-key`).

All paths are relative to this server. Nothing here is tied to localhost.