# Liquify_Journey_V1 — Hosted Mutual-Fund Pledge Journey Link

**Liquify_Journey_V1** · version `v1` · status `live`

## Authentication

Every request must carry your API key in the `X-API-Key` header. Your key is
issued to you separately by ops and is never shown in this document.

```
X-API-Key: <your-key>
```

## Base URL

All endpoints are served through the gateway:

```
https://api.pehchaantech.com
```

## Endpoints

| Method | Path | Full URL | Timeout |
| --- | --- | --- | --- |
| `POST` | `/liquify-journey/v1/link` | `https://api.pehchaantech.com/liquify-journey/v1/link` | 35000 ms |

Rate limit: **60 requests/minute** · **100000 requests/day**, counted per API key.

## Overview

One call returns one branded URL that runs the WHOLE mutual-fund pledge journey: the customer enters their own mobile and PAN, authenticates with MF Central, picks their AMCs, sees their portfolio, and — if you ask for it — the loan offers against it. You build no screens and you handle no customer details.

EVERY 201 COSTS MONEY, AND EVERY LINK IS GOOD FOR EXACTLY ONE CUSTOMER INTERACTION. Those are the same rule seen from both ends: a link cannot be re-used, so you must mint a fresh one each time — and each mint is metered, which makes this the one call in our catalogue where a careless integration can genuinely overspend. Call it at the moment a specific customer is about to open the journey. Never cache a link, never store one against a user record, never re-share one between customers, and never pre-generate or batch them. Requests we reject ourselves return 422 without ever reaching the provider and are free.

THERE IS NO STATUS ENDPOINT, AND THERE WILL NOT BE ONE. Once you have the URL we cannot tell you whether the customer completed the journey, abandoned it, or ever opened it. This is not a roadmap gap: the upstream call that mints the link accepts no customer identity and no return URL, and the provider never calls us back, so there is no identifier a completion could be reported against and no channel to report it on. Any status endpoint we shipped could only answer "we don’t know", dressed up as data. What internal_customer_id buys you is reconciliation on OUR side — "which of my users did I mint a link for, and when" — and nothing about what the customer did next.

TREAT link_url AS OPAQUE. The host and every query parameter belong to the provider and can change without a version bump on our side. Redirect to the value exactly as returned: do not parse it, rewrite it, strip or append parameters, extract a token from it, or match on the host. It is also credential-bearing and single-use — do not log it, email it, or store it.

invalid_input CAN ARRIVE AS HTTP 200. Always branch on `status`, never on the HTTP code alone: a client that treats 2xx as success will hand its customers a link that does not exist.

NO CUSTOMER PII IS SENT OR STORED. There is no mobile, PAN, date of birth, name or email in the request — the hosted journey collects those from the customer directly. That is the main reason to choose this product over MF_Pledge_V1. Pick this one for zero UI work and no PII in your systems; pick MF_Pledge_V1 when you need the holdings themselves as structured data and can supply the customer’s mobile and PAN, own a return leg, and read a portfolio back. Neither supersedes the other.

Only internal_customer_id is required — everything else overrides a default we already hold for your account. The referral code is ours and cannot be overridden: sending a `referralCode` field is a 422, deliberately, so you find out rather than believe you set something. Typical latency is 0.2–2 s; set your client timeout to at least 35 seconds to match the route. Only mint a link with the customer’s consent — it starts a journey that authenticates them at MF Central in their own name.

## Request example

```json
{
  "lenders": [
    "bajaj",
    "piramal"
  ],
  "brand_img": "https://cdn.example.com/logo.png",
  "theme_mode": "light",
  "loan_journey": true,
  "primary_color": "#0B5FFF",
  "internal_customer_id": "CUST_00123"
}
```

## Response example

```json
{
  "status": "link_created",
  "success": true,
  "link_url": "https://<hosted-journey-host>/…?key=…",
  "description": "Link generated — it is single-use, share it with one customer",
  "internal_customer_id": "CUST_00123"
}
```

## Fields

| Field | Description |
| --- | --- |
| `internal_customer_id` | Required. Your own identifier for your user, 1–128 characters, opaque to us. Echoed back in the response so an async caller can pair the two, and recorded against the call so you can reconcile "which of my users did I mint a link for, and when". It is NOT sent to the provider and it is NOT a journey tracker — the upstream has no field for it. It answers a billing and support question, never "did this customer finish". |
| `primary_color` | Optional. Six-digit hex including the hash — #0B5FFF. Three-digit shorthand (#0B5) is rejected rather than expanded. Overrides the default configured for your account. It lands in the stylesheet of a page a real customer loads, which is why it is validated strictly rather than passed through. |
| `theme_mode` | Optional. Exactly "light" or "dark". Anything else is a 422. Overrides the default configured for your account. |
| `brand_img` | Optional. Absolute https URL to your logo, 8–1024 characters. http, a relative path, a localhost host, or a URL carrying userinfo (the https://yourcdn.example.com@evil.example/logo.png shape) is a 422 — the image is loaded by a real customer’s browser from a page that is not ours. Overrides the default configured for your account. |
| `lenders` | Optional array of lender slugs: bajaj, cub, ssfl, piramal. OMIT IT to show every lender enabled for your account — that is the recommended default, and it means a lender enabled for you later appears without a code change on your side. An unrecognised slug rejects the whole request with 422 rather than being dropped: dropping it would show the customer every lender, the opposite of what you asked for. Order and duplicates do not matter. |
| `loan_journey` | Optional boolean. true shows the loan step after the portfolio; false stops at the portfolio view. Defaults to the setting configured for your account. |
| `link_url` | The whole point of the call. SINGLE-USE and session-scoped — hand it to one customer, now. A second person opening it does not get their own journey, and a link minted in advance is money spent on a customer who may never tap the button. Treat the value as opaque: redirect to it exactly as returned, and never parse, rewrite, trim, extend or host-match it. Treat it as a credential with one use in it — not logged, not emailed, not stored. We do not store it either, so a lost link cannot be looked up; mint another. |
| `referralCode` | NOT ACCEPTED, and a 422 if you send it. The referral code is set by us and attributes the resulting loan to our account. Refusing it loudly is deliberate: silently dropping it would let a caller believe their own attribution had been applied. |
| `mobile / pan / dob / name` | NOT ACCEPTED, and a 422 if you send any of them — as is any other unknown field. This endpoint has nowhere to put customer details: the hosted journey collects them from the customer directly. Rejecting them beats swallowing them and letting you believe you had identified the customer. |

## Errors

| Code | Meaning |
| --- | --- |
| `link_created (HTTP 201)` | Link minted, and BILLED. Hand link_url to one customer now. It is single-use and session-scoped: do not cache it, re-share it, or store it against a user record. |
| `invalid_input (HTTP 200)` | The provider refused the request. Deterministic — retrying unchanged fails identically. Note the HTTP 200: always branch on `status`, never on the HTTP code alone. If this persists on a request you believe is well-formed — especially on the first call of a new integration — raise it with support rather than debugging your payload. A rejection can also come from account configuration on our side, and from where you stand the two look identical. |
| `invalid_input (HTTP 422)` | We refused it ourselves and nothing was sent upstream, so it is FREE: a theme_mode that is not light/dark, a brand_img that is not an absolute https URL, an unknown lender slug, a primary_color that is not #RRGGBB, a missing or over-long internal_customer_id, or any unknown field (referralCode, mobile, pan). Fix the request; retrying unchanged fails identically. |
| `failed (HTTP 502)` | Upstream unavailable, or it refused the request for a reason that is ours to fix rather than yours. Nothing was billed and no link was minted. Transient from your side — retry with exponential backoff, and if it persists quote the time of the call to support. |

## Changelog

- **2026-08-03** — Initial release: a single call that returns one branded, single-use link for the entire hosted mutual-fund pledge journey. No customer PII is sent or stored. Every 201 is metered, so mint one link per customer interaction rather than caching or pre-generating them. There is no status endpoint — the upstream call carries no customer identity and no callback, so journey completion cannot be reported.

---

_Generated from the pehchaantech developer portal · canonical page: https://docs.pehchaantech.com/docs/liquify-journey-v1 · last updated: 2026-08-04T05:19:33.136Z._