# Volt_Journey_V1 — Loan Against Mutual Funds Journey Link

**Volt_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` | `/volt-journey/v1/link` | `https://api.pehchaantech.com/volt-journey/v1/link` | 65000 ms |

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

## Overview

Turn a customer’s details into a ready-to-open link for the Volt Money loan-against-mutual-funds journey. One call in, one URL out — send the customer straight to it.

THE LINK EXPIRES IN ABOUT TWO MINUTES. This is the single most important thing about this API. The URL carries a short-lived sign-on token, so call this at the moment the customer taps the button — never in advance, never in a batch job, and never cached. An expired link looks exactly like a broken one to the customer, so a link generated even a few minutes early is a support ticket waiting to happen.

ONE CALL, NOT A JOURNEY YOU ORCHESTRATE. Behind this single request we sign in, create or resolve the customer, and mint the sign-on token. You hold none of that: no Volt credentials, no session, no state.

CALLING IT AGAIN FOR THE SAME CUSTOMER IS FINE AND EXPECTED. A returning customer gets a fresh link. There is no "already exists" error to handle and nothing to clean up between attempts — if a customer lets a link expire, just ask for another one.

MOBILE NUMBER AND EMAIL MUST BE UNIQUE PER CUSTOMER. They identify the customer at Volt, so a pair already attached to a DIFFERENT external_id is refused with `invalid_input` naming the offending fields. That is a genuine conflict in your own data to resolve, not a transient error — retrying unchanged will fail identically.

Only request this with the customer’s consent: you are starting a lending journey in their name. Typical latency is well under 2 seconds; set your client timeout to at least 65 seconds to match the route.

## Request example

```json
{
  "dob": "01-12-1990",
  "pan": "ABCDE1234F",
  "email": "customer@example.com",
  "mobile": "9876543210",
  "external_id": "CUST_00123",
  "client_ref_num": "your-trace-key-001"
}
```

## Response example

```json
{
  "status": "link_created",
  "success": true,
  "link_url": "https://app.voltmoney.in/partnerPlatform?platform=MAXIMONEY&primaryColor=00C9A7&secondaryColor=00A889&showHome=false&showVoltDefaultHeader=false&isRedirection=true&isFromRnSdk=true&ssoToken=eyJhbGciOiJIUzI1NiJ9.PLACEHOLDER",
  "description": "Link generated — open it immediately, the embedded token expires in about 2 minutes",
  "client_ref_num": "your-trace-key-001",
  "sso_expires_in_s": 120,
  "volt_customer_code": "FEB612FC8227928A8D66A865C764EBB4"
}
```

## Fields

| Field | Description |
| --- | --- |
| `external_id` | Required. Your own identifier for the customer, 1–128 characters, URL-safe only (letters, digits, dot, underscore, hyphen — no spaces). This is the key the customer is remembered by, so send the SAME value every time for the same person: a new value for an existing customer creates a conflict on their mobile and email rather than a new link. |
| `pan` | Required. 5 letters, 4 digits, 1 letter. Case is not significant. Used to identify the customer for the lending journey and NOT stored by this API. |
| `dob` | Required. Date of birth as dd-mm-yyyy — for example 01-12-1990. This is NOT ISO format: 1990-12-01 is rejected. Must be a real calendar date. NOT stored by this API. |
| `email` | Required. Must not already belong to a different external_id — email identifies the customer at the lender. NOT stored by this API. |
| `mobile` | Required. 10 digits starting 6–9, with no country code and no +91. Must not already belong to a different external_id. |
| `client_ref_num` | Optional. Your trace key, 6–64 characters of letters, digits, dot, underscore or hyphen. Echoed in the response body and the X-Client-Ref-Num header, and recorded against the call — quote it to support. One is generated for you if you omit it. |
| `link_url` | The whole point of the call. Send the customer here immediately — it carries a sign-on token valid for roughly two minutes. Do not store it, log it, email it, or reuse it: it signs the customer in, so treat it as a credential with a very short life. Treat the whole value as opaque and redirect to it as-is. The host and the query parameters differ between the test and production environments, so a UAT key returns a staging host — never hard-code the host, rebuild the URL, or match on it. |
| `volt_customer_code` | The customer’s identifier at the lender. Web integrations can ignore it. If you use the mobile SDK you MUST pass it alongside the token — the SDK errors out given the token alone. Stable across calls for the same customer. |
| `sso_expires_in_s` | Roughly how many seconds the embedded token stays valid (120). Approximate and set by the lender — treat it as "open this now", not as a countdown to schedule against. |
| `invalid_fields` | Present on invalid_input. Names OUR field names — for example ["mobile","email"] — for the fields the lender objected to, usually because they already belong to a different external_id. A HINT, not a guarantee: it can be an empty array when the rejection names no specific field, so never branch on it being non-empty. |

## Errors

| Code | Meaning |
| --- | --- |
| `link_created (HTTP 201)` | Link minted. Send the customer to link_url NOW — the token inside it expires in about two minutes. |
| `invalid_input (HTTP 200)` | The lender rejected the customer details. Most often the mobile or email already belongs to a different external_id — check invalid_fields. This is a conflict in your data, not a transient fault: retrying unchanged fails identically. |
| `validation (HTTP 422)` | Malformed request — bad PAN, a dob that is not dd-mm-yyyy or not a real date, a mobile with a country code, an external_id with unsafe characters, or an unknown field. Rejected before anything is sent upstream. 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. Transient from your side — retry with backoff, and if it persists quote your client_ref_num to support. |

## Changelog

- **2026-07-28** — Initial release: a single call that returns a ready-to-open journey link. The embedded sign-on token lives about two minutes, so generate links on demand rather than ahead of time. Repeat calls for the same customer are supported and return a fresh link.

---

_Generated from the pehchaantech developer portal · canonical page: https://docs.pehchaantech.com/docs/volt-journey-v1 · last updated: 2026-07-28T14:39:09.570Z._