Collection Session Create — GST

Endpoint Overview

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

Description

The Collection Session Create (GST) endpoint generates a secure, hosted data-collection session for the GST (Goods and Services Tax) workflow. It creates a tokenised session link that is automatically emailed to the specified recipient, allowing them to securely submit their GST data through FinPass's hosted interface.

The session is time-limited, recipient-scoped, and configurable with redirect and callback URLs so your platform maintains control of the user journey and receives real-time webhook notifications upon session completion.

Key Benefits

Hosted GST Collection: Generates a ready-to-share hosted_url that opens FinPass's secure GST data-collection interface — no frontend development required on your end.

Automated Email Delivery: The session link is automatically sent to the recipient_email, reducing manual coordination and accelerating collection turnaround.

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

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

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

Use Cases

Lending & Credit

Compliance & Audit

Fintech & BFSI Onboarding

Business loan underwriting platforms collecting GST return data from SME applicants to assess revenue, GST compliance history, and tax payment regularity.

Working capital finance providers using GST data to validate declared turnover and verify the authenticity of business operations before disbursement.

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. Must be `"gst"` for this endpoint.
`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-002"}`).
`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 or business 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 interface.
`requester_name`	String	No	Name of the requesting organisation or individual, displayed in the hosted session UI to establish context and trust.

Example Request

{
  "flow": "gst",
  "redirect_url": "https://example.com/redirect",
  "callback_url": "https://example.com/webhook",
  "metadata": {
    "customer_ref": "CUST-002"
  },
  "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_6a27f24d_986d50a8e8148294f67a0ab3"`). Store this to track or reference the session later.
`flow`	String	The flow type for this session, as provided in the request — `"gst"`.
`hosted_url`	String	The full shareable URL that opens the FinPass hosted GST 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 GST data.

Example Successful Response

{
  "success": true,
  "status_code": 200,
  "message": "Collection session created; hosted link emailed to recipient",
  "data": {
    "session_id": "col_6a27f24d_986d50a8e8148294f67a0ab3",
    "flow": "gst",
    "hosted_url": "https://verify.finpass.ai?flow=gst&token=0sSktUIZFi-TZAOcWUPZiyqgi-dsdZx6gtPi2EsSPNI",
    "token": "0sSktUIZFi-TZAOcWUPZiyqgi-dsdZx6gtPi2EsSPNI",
    "expires_at": "2026-06-09T11:15:29.117255",
    "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 exposure window 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 they will receive an email with a session link, and communicate the expiry time clearly so they complete the flow before it lapses.

Use redirect_url to close the loop: After the recipient completes the hosted session, they will 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: Avoid polling — use the webhook to trigger downstream processing (e.g., GST data analysis, credit decisioning) as soon as the session status changes.

Store session_id: Persist the session_id against your internal customer or business record so you can correlate webhook events and query session status at any time.

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 Create (ITR) — Same endpoint with flow: "itr" to initiate an Income Tax Return data-collection session for individual income verification.

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 to complement GST data in a comprehensive business financial assessment.

BSA Batch Result — Retrieve bank statement analysis results to cross-validate GST-declared turnover against actual banking activity.

Compliance and Legal Considerations

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

Data Privacy: The session link grants access to the recipient's GST filing data, which may include commercially sensitive turnover and tax information. Comply with DPDP (India), GDPR (EU), or the applicable data protection regulation in your jurisdiction when storing or processing the collected data.

GSTN Data Usage: GST data fetched via this session is sourced from the GSTN portal on behalf of the taxpayer. Ensure your use of this data is restricted to the purpose for which consent was obtained and complies with GSTN's data usage policies.

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

Session Expiry Enforcement: Do not attempt to extend or reuse expired session tokens. Create a new session if a recipient requires 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 GST Collection Session

Collection Session Create — GST#

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