Collection Session Create

Endpoint Overview

POST /api/v1/services/collection/session/create

Description

The Collection Session Create endpoint generates a secure, hosted data-collection session for a specified financial workflow. For the itr (Income Tax Return) flow, it creates a tokenised session link that can be shared with a recipient — via email or directly — so they can securely submit their ITR data through FinPass's hosted interface.

The session is time-limited, tied to a specific recipient, and configurable with redirect and callback URLs so your platform receives control and webhook notifications upon completion.

Key Benefits

Hosted, No-Code Collection: Generates a ready-to-share hosted_url that opens FinPass's secure ITR data-collection interface — no frontend build required.

Automated Email Delivery: The session link is automatically emailed to the recipient_email, reducing manual coordination.

Webhook Integration: Configure a callback_url to receive real-time notifications when the recipient completes or abandons the session.

Expiry Control: Set a custom expires_in duration to enforce time-bound data collection aligned with your workflow SLAs.

Metadata Passthrough: Attach arbitrary metadata (e.g., customer reference IDs) to correlate sessions with your internal records.

Use Cases

Lending & Credit

Compliance & Audit

Fintech & BFSI Onboarding

Loan origination platforms sending ITR collection links to applicants to verify income and tax filings as part of the credit underwriting process.

NBFC onboarding flows that trigger a collection session after KYC completion, ensuring ITR data is gathered within a defined expiry window.

Technical Implementation

Authentication

All API requests must be authenticated using your API Key and API Secret as request headers, along with a refresh token via the Cookie header.

Obtain API Credentials: Contact FinPass to receive your x-api-key and x-api-secret.

Obtain Refresh Token: Authenticate via the FinPass auth flow to receive a refresh_token cookie.

Include in Every Request: Add all three to each API call as shown below.

Environment	Base URL
Production	`https://api.finpass.ai`

Header format:

x-api-key: <YOUR_X_API_KEY>
x-api-secret: <YOUR_X_API_SECRET>
Cookie: refresh_token=<YOUR_REFRESH_TOKEN>

⚠️ Never expose x-api-key, x-api-secret, or refresh_token in client-side code or public repositories. Always call this endpoint from a secure server-side environment.

Request Parameters

Request Headers

Header	Required	Description
`x-api-key`	Yes	Your FinPass API key for authentication.
`x-api-secret`	Yes	Your FinPass API secret for authentication.
`Content-Type`	Yes	Must be `application/json`.
`Cookie`	Yes	Must include `refresh_token=<token>` for session authentication.

Request Body

Parameter	Type	Required	Description
`flow`	String	Yes	The data-collection workflow to initiate. Currently supported value: `"itr"` (Income Tax Return collection).
`redirect_url`	String	Yes	URL to redirect the recipient to after they complete or exit the hosted session.
`callback_url`	String	Yes	Webhook URL that FinPass will POST to when the session status changes (e.g., on completion or expiry).
`metadata`	Object	No	Arbitrary key-value pairs to attach to the session for internal tracking (e.g., `{"customer_ref": "CUST-001"}`).
`expires_in`	Integer	No	Session validity in seconds from creation time. Defaults to system maximum if omitted. Example: `86400` for 24 hours.
`recipient_email`	String	Yes	Email address of the person who will complete the collection session. The hosted link is automatically sent to this address.
`recipient_name`	String	No	Full name of the recipient, used for personalising the email and hosted session.
`requester_name`	String	No	Name of the requesting organisation or individual, displayed in the hosted session UI for context.

Example Request

{
  "flow": "itr",
  "redirect_url": "https://example.com/redirect",
  "callback_url": "https://example.com/webhook",
  "metadata": {
    "customer_ref": "CUST-001"
  },
  "expires_in": 86400,
  "recipient_email": "customer@example.com",
  "recipient_name": "Customer Name",
  "requester_name": "FinPass Demo"
}

Process Response

Response Parameters

Top-Level Fields

Field	Type	Description
`success`	Boolean	`true` if the session was created successfully.
`status_code`	Integer	HTTP status code of the operation (e.g., `200`).
`message`	String	Human-readable result message confirming session creation and email dispatch.
`data`	Object	The session details object. See sub-fields below.

`data` Object Fields

Field	Type	Description
`session_id`	String	Unique identifier for the created collection session (e.g., `"col_6a27e7c6_2cbd9201e91c737f2e3e08b2"`). Store this to track or reference the session later.
`flow`	String	The flow type for this session, as provided in the request (e.g., `"itr"`).
`hosted_url`	String	The full shareable URL that opens the FinPass hosted collection interface. Share this with the recipient or embed it in your communications.
`token`	String	The bearer token embedded in the `hosted_url`. Can be used to construct or validate the session link independently.
`expires_at`	String (ISO 8601)	Timestamp indicating when the session will expire. After this time, the `hosted_url` will no longer be accessible.
`status`	String	Current session status. `"created"` on initial response. Other possible values include `"completed"`, `"expired"`, and `"abandoned"`.
`recipient_email`	String	Email address of the session recipient, confirming where the hosted link was sent.
`pan`	String \| null	PAN number associated with the session, if available at creation time. `null` until the recipient submits their ITR data.

Example Successful Response

{
  "success": true,
  "status_code": 200,
  "message": "Collection session created; hosted link emailed to recipient",
  "data": {
    "session_id": "col_6a27e7c6_2cbd9201e91c737f2e3e08b2",
    "flow": "itr",
    "hosted_url": "https://verify.finpass.ai?flow=itr&token=-lInefSeQbacMkWAjXzS7kk-Fh_e9DQNPihNMjqqvjc",
    "token": "-lInefSeQbacMkWAjXzS7kk-Fh_e9DQNPihNMjqqvjc",
    "expires_at": "2026-06-09T10:30:34.999026",
    "status": "created",
    "recipient_email": "customer@example.com",
    "pan": null
  }
}

Possible Error Responses

401 Unauthorized

400 Bad Request

422 Unprocessable Entity

500 Internal Server Error

{
  "success": false,
  "status_code": 401,
  "message": "Invalid or missing API credentials.",
  "message_code": "unauthorized"
}

Returned when x-api-key, x-api-secret, or refresh_token is absent, incorrect, or expired. Re-authenticate to obtain a fresh token and verify your API credentials before retrying.

Integration Best Practices

Security Recommendations

Server-side only: Always call this endpoint from your backend server. Never expose x-api-key, x-api-secret, or refresh_token in browser JavaScript or mobile app code.

Protect the hosted_url: The generated hosted_url contains a bearer token granting access to the session. Treat it as sensitive — do not log it, expose it in URLs, or share it beyond the intended recipient.

Set appropriate expires_in: Use the shortest expiry that fits your workflow to minimise the window of exposure if a session link is intercepted or forwarded.

Validate callback_url signatures: Verify that webhook POSTs to your callback_url originate from FinPass before processing the payload.

Rotate credentials regularly: Periodically rotate your x-api-secret and update your server configuration to minimise the impact of accidental exposure.

User Experience Guidelines

Inform recipients proactively: Notify users that they will receive an email with a session link, and set expectations around the expiry time so they complete the flow promptly.

Use redirect_url to close the loop: After the recipient completes the hosted session, they'll be redirected to your redirect_url. Use this page to confirm submission and guide them to the next step in your product.

Implement callback_url webhooks: Don't rely on polling — use the webhook to trigger downstream processing (e.g., credit decisioning, document storage) as soon as the session status changes.

Store session_id: Persist the session_id against your internal customer record so you can correlate webhook events and query session status later.

Personalise with recipient_name and requester_name: Populating these fields improves the recipient's experience in the hosted session and email, building trust and reducing drop-off.

Code Samples

cURL

Python

Node.js

PHP

Related APIs

Collection Session Status — Poll the status of an existing collection session using its session_id to check whether the recipient has completed, abandoned, or not yet started the flow.

Collection Session List — Retrieve a paginated list of all collection sessions created under your account, filterable by flow type and status.

BSA Upload Statements Batch — Upload bank statement files for analysis as part of a broader financial data collection workflow.

BSA Batch Result — Retrieve analysis results for a submitted bank statement batch, complementing ITR data for comprehensive income verification.

Customer KYC Verification — Verify identity documents alongside ITR and bank data as part of a complete onboarding or lending workflow.

Compliance and Legal Considerations

Consent: Ensure you have explicit, informed consent from the recipient_email holder before initiating a collection session on their behalf. Maintain auditable records of consent tied to the session_id.

Data Privacy: The session link grants access to the recipient's ITR data. Comply with DPDP (India), GDPR (EU), or the applicable data protection regulation in your jurisdiction when storing or processing the collected data.

Email Deliverability and Phishing Risk: The hosted session link is emailed to the recipient. Ensure your domain and requester_name are clearly identifiable to reduce the risk of the email being flagged as phishing or spam.

Session Expiry Enforcement: Do not attempt to extend or reuse expired session tokens. Create a new session if a recipient needs additional time, to maintain security boundaries.

Audit Trails: Retain logs of all session creation events — including session_id, recipient_email, requester_name, and creation timestamp — to support audit and regulatory compliance requirements.

Create ITR Collection Session

Collection Session Create#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Top-Level Fields#

data Object Fields#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses