> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.liquifyfin.in/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.liquifyfin.in/_mcp/server.

# Liquify Vendor API Reference

The **Liquify Vendor API** provides RESTful endpoints to facilitate loan-against-mutual-funds (LAMF) customer onboarding, identity verification, portfolio sync, and credit limit computation.

## Base URLs

All requests must be directed to your assigned Liquify gateway environment:

| Environment       | Base URL                       | Description                                         |
| :---------------- | :----------------------------- | :-------------------------------------------------- |
| **UAT / Sandbox** | `https://a7.liquifyfin-uat.in` | Partner staging and integration testing             |
| **Production**    | *(blank)*                      | Dedicated production endpoint provided upon go-live |

## Authentication

Every API call requires Bearer Token authentication via the `VendorBearerAuth` scheme. Pass your vendor token in the `Authorization` HTTP header:

```http
Authorization: Bearer <vendor_token>
```

> **Note**
>
> Each API is switched on for your organization individually. An API you do not hold returns `403 ACCESS_DENIED`. Keep your token confidential. If your token is compromised, contact Liquify Partner Operations immediately for key rotation.

## Request & Response Format

All API requests accepting a payload must send `Content-Type: application/json`.

* **Money** is formatted as a decimal string (e.g. `"245000.00"`), never a JSON number.
* **Timestamps** are ISO 8601 formatted strings.
* **Rate Limits & Failures** return a `Retry-After` header indicating seconds to wait.

### Standard Success Envelope (2xx)

Every successful response contains:

* `data`: The requested entity or operation payload.
* `meta`: Operational metadata including the unique request ID (`request_id`) and ISO 8601 timestamp (`ts`).

```json
{
  "data": {
    "customer_id": "cust_9830ed6a8ad3",
    "eligible_amount": "245000.00",
    "portfolio_value": "612500.40",
    "portfolio_synced_at": "2026-10-05T10:20:27Z",
    "stale": false
  },
  "meta": {
    "request_id": "38461348-c5e4-449c-b9cc-d6b08c06d11b",
    "ts": "2026-10-05T10:23:48Z"
  }
}
```

### Standard Error Envelope (RFC 9457 Problem Details)

All 4xx and 5xx errors adhere to RFC 9457 problem details (`application/problem+json`). The `code` field is from Liquify's stable error registry and never changes meaning:

```json
{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "Customer has not granted MF_HOLDINGS consent required for portfolio synchronization",
  "code": "CONSENT_REQUIRED",
  "errors": [],
  "request_id": "8b3b64dc-1123-4212-bf9a-3214819d4bca",
  "trace_id": "trace_796f5cdf"
}
```

## Error Codes Reference

| HTTP Status               | Error Code                                              | Description                                                                                                          |
| :------------------------ | :------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`         | `VALIDATION_FAILED`                                     | Request breaks schema or field constraints. Inspect `errors` for field details.                                      |
| `401 Unauthorized`        | `AUTH_INVALID_TOKEN`                                    | Bearer token is missing, expired, or invalid.                                                                        |
| `403 Forbidden`           | `ACCESS_DENIED`                                         | This API endpoint is not switched on for your organization.                                                          |
| `403 Forbidden`           | `CONSENT_REQUIRED`                                      | Customer has not granted (or has withdrawn) a necessary consent purpose (`KYC_PAN`, `MF_HOLDINGS`, `PARTNER_SHARE`). |
| `404 Not Found`           | `NOT_FOUND`                                             | Customer is not on your book, or an unknown verification ID was provided.                                            |
| `409 Conflict`            | `STATE_CONFLICT` / `PORTFOLIO_NOT_SYNCED`               | Customer is not in an actionable state (e.g. sync incomplete or existing active session).                            |
| `422 Unprocessable`       | `KYC_REQUIRED`                                          | Not an individual's PAN (fourth char must be `P`), under 18, or PAN failed verification.                             |
| `422 Unprocessable`       | `MF_SYNC_CONTACT_NOT_LINKED`                            | Customer folios are registered to a different email or mobile at the registrar.                                      |
| `429 Too Many Requests`   | `MF_SYNC_RATE_LIMITED`                                  | Customer sync cooldown reached or caller rate limits exceeded. Check `Retry-After` header.                           |
| `503 Service Unavailable` | `PROVIDER_UNAVAILABLE` / `MF_SYNC_PROVIDER_UNAVAILABLE` | Downstream registrar or KYC provider is unreachable. Retry after `Retry-After` seconds.                              |

---

## API Endpoints Overview

The Liquify Vendor API is organized into 3 functional domains across 10 endpoints:

#### Platform

* **`GET /v1/ping`**\
  Check token validity and API grant status.

#### Customer onboarding

* **`POST /v1/pan-verifications`**\
  Verify a PAN with KYC provider or read cached verification.
* **`POST /v1/customers`**\
  Create a customer on your partner book.
* **`POST /v1/customers/{customer_id}/consents`**\
  Relay customer consent or withdrawal with evidence.
* **`GET /v1/customers/{customer_id}/consents`**\
  Read the customer's active consent status per purpose.

#### Eligibility

* **`POST /v1/customers/{customer_id}/holding-syncs`**\
  Start holdings sync with registrar (`MFCENTRAL`, `CAMS`, `KFIN`).
* **`POST /v1/customers/{customer_id}/holding-syncs/{session_id}/verify`**\
  Submit registrar OTP or expedite MF Central check.
* **`GET /v1/customers/{customer_id}/holding-syncs/{session_id}`**\
  Check status of asynchronous holdings sync.
* **`GET /v1/customers/{customer_id}/eligibility`**\
  Query borrowing limit by Customer ID.
* **`POST /v1/eligibility/lookup`**\
  Query borrowing limit by PAN (body payload).

## Interactive API Explorer

Use the navigation in the sidebar to inspect every endpoint, view detailed request/response schemas, configure parameters, and execute live calls right from this documentation portal.