API Documentation | Unaport.ai

🔑

Postman Collection

Import our Postman collection to quickly test all APIs in both UAT and Production environments.

⬇ Download Postman Collection v2.0 ⬇ Download Environment Variables

💡After importing, set the token environment variable from the Login API response before calling any other endpoints.

📝

FIU Data Flow

The standard end-to-end integration flow for an FIU to retrieve consented financial data.

1

Authenticate

Call the Login API to receive an access_token and refresh_token.

2

Create Consent Template

Pre-define consent parameters as a reusable Product template (optional but recommended).

3

Raise a Consent

Create a consent request for the user, providing vuaId, trackingId, AA, and consent parameters.

4

User Approves Consent

User is redirected to the AA platform via redirectUrl to approve or reject.

5

Receive Consent Notification

Unaport calls your webhook with the updated consent status (ACTIVE, FAILED, EXPIRED, etc.).

6

Data Fetched Automatically

On approval, Unaport fetches financial data from FIPs via the AA.

7

Receive Data Notification

Your webhook receives the sessionId when data is ready.

8

Fetch Data

Call Fetch Data by Session API with the sessionId to retrieve financial data.

9

Run Analytics (optional)

Call the Generate Analytics API on the session for ML-powered insights and spend analysis.

🌟

Introduction

All API requests require a Bearer token obtained via the Login API. Send it in the Authorization header for every authenticated request.

🔒Required headers for all authenticated requests: Authorization: Bearer <token> and Content-Type: application/json

🔒

Authentication API

Authenticate with email and password to get access and refresh tokens.

Login

POST https://common.sandbox.unaport.com/api/v1/public/user/login

No authentication required

Attribute	Description	Length	Type	Req
`emailId`	User email address	254	String	M
`password`	Login password	8-64	String	M

Request

POST https://common.sandbox.unaport.com/api/v1/public/user/login
Content-Type: application/json

{
  "emailId": "[email protected]",
  "password": "*****"
}

Response 200

{
  "access_token": "eyJhbGci...",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGci...",
  "token_type": "Bearer",
  "txnId": "...",
  "timestamp": "2024-03-28T05:04:39.821Z"
}

Attribute	Description	Type
`access_token`	Bearer token for all authenticated requests (valid 300s)	String
`refresh_token`	Used to get a new access token (valid 1800s)	String
`expires_in`	Seconds before access token expires	Number
`token_type`	Always "Bearer"	String

Refresh Token API

POST https://common.sandbox.unaport.com/api/v1/public/user/refresh

Attribute	Description	Req
`refresh_token`	Refresh token from Login response	M

Returns the same structure as Login — a new access_token and refresh_token.

Get FIU Organisation Details

GET https://common.sandbox.unaport.com/api/v1/FIU/getClientOrganisation

Headers: Authorization: Bearer <token>

Attribute	Description
`fiulive.entityId`	FIU entity ID in live mode
`fiutest.entityId`	FIU entity ID in test mode
`orgId`	Organisation identifier

📑

Consents API

Create templates, raise consents, check status, and revoke consents.

Create Consent Template

POST https://api.sandbox.unaport.com/backend-v2/api/v2/FIU/ConsentTemplate/{orgId}

Attribute	Description	Type	Req
`product_name`	Unique name for the consent template	String	M
`ConsentDetail.consentMode`	`VIEW` \| `STORE` \| `QUERY` \| `STREAM`	String	M
`ConsentDetail.fetchType`	`ONETIME` \| `PERIODIC`	String	M
`ConsentDetail.consentTypes`	`PROFILE`, `SUMMARY`, `TRANSACTIONS`	Array	M
`ConsentDetail.fiTypes`	See FI Types table below	Array	M
`ConsentDetail.Purpose.code`	101–105 (see Purpose Codes)	String	M
`ConsentDetail.FIDataRange.from`	Start months (negative = past, e.g. -12)	Number	M
`ConsentDetail.FIDataRange.to`	End months	Number	M
`ConsentDetail.DataLife.unit`	`MONTH` \| `YEAR` \| `DAY` \| `INF`	String	M
`ConsentDetail.Frequency.unit`	`HOUR` \| `DAY` \| `MONTH` \| `YEAR`	String	M

FI Types Reference

Category	FI Types
Bank	`DEPOSIT`, `TERM_DEPOSIT`, `RECURRING_DEPOSIT`
Investment	`MUTUAL_FUNDS`, `ETF`, `EQUITIES`, `NPS`
Insurance	`INSURANCE_POLICIES`
GST	`GSTR1_3B`

Create Consent with Template

POST https://api.sandbox.unaport.com/backend-v2/api/v2/FIU/Consents/{orgId}

Attribute	Description	Req
`vuaId`	User's virtual AA ID (e.g. `9867902913@ink`)	M
`mobileNumber`	Mobile number linked to user's AA account	M
`trackingId`	Your unique tracking reference for this request	M
`aaId`	Account Aggregator identifier	M
`fiuId`	FIU identifier (as registered in Sahamati)	M
`productId`	ID of the consent template to use	M
`redirectUrl`	URL to redirect user after consent processed	O
`fiuBaseUrl`	Your FIU API base URL for notifications	M

Sample Request

{
  "vuaId": "9867902913@ink",
  "createdBy": "[email protected]",
  "trackingId": "your-unique-id-001",
  "aaId": "UNACORES-AA-UAT",
  "fiuId": "UNACORES-FIU-UAT",
  "redirectUrl": "https://your-app.com/consent-callback",
  "fiuBaseUrl": "https://api.sandbox.unaport.com/backend/api/v1",
  "productId": "5961868f-ac0e-45e6-9e7b-394c535fa4cc"
}

Response 200

{
  "ver": "1.0",
  "timestamp": "2024-03-28T05:04:39.821Z",
  "txnid": "4a4adbbe-29ae-11e8-a8d7-0289437bf331",
  "Customer": { "id": "9867902913@ink" },
  "ConsentHandle": "39e108fe-9243-11e8-b9f2-0256d88baae8",
  "success": "Consent created successfully",
  "redirectUrl": "https://api.sandbox.unaport.com/backend/api/v1/redirect/dfdESWW23dx"
}

Check Consent Status

GET https://api.sandbox.unaport.com/backend-v2/api/v2/FIU/GetConsent/{consentHandle}

Attribute	Description	Type
`consentHandle`	The handle returned at consent creation	String
`approveStatus`	`PENDING` \| `READY` \| `FAILED` \| `EXPIRED`	String
`consentStatus`	`ACTIVE` \| `PAUSED` \| `REVOKED` \| `EXPIRED`	String
`consentId`	Unique consent ID (available only after approval)	String
`consentStart`	Consent validity start	ISO 8601
`consentExpried`	Consent expiration	ISO 8601
`fetchType`	ONETIME or PERIODIC	String

Revoke Consent

DELETE https://api.sandbox.unaport.com/backend-v2/api/v2/FIU/RevokeConsent/{org_id}/{consentId}

Path params: org_id and consentId of the consent to revoke

📊

Data API

Fetch financial data using session IDs received via webhook notifications after consent approval.

Get FI Notification (Fetch Data Status)

GET https://api.sandbox.unaport.com/backend-v2/api/v2/FIU/FINotification/{consentHandle}

Attribute	Description	Type
`FIStatusNotification.sessionId`	Session ID — use this to fetch data	String
`FIStatusNotification.sessionStatus`	`ACTIVE` \| `COMPLETED`	String
`FIStatusResponse[].fipID`	FIP identifier	String
`Accounts[].FIStatus`	`READY` \| `PENDING` \| `FAILED`	String

Fetch Data by Session ID

GET https://api.sandbox.unaport.com/backend-v2/api/v2/FIU/FifetchDataBySessionId/{sessionId}

Returns full account summary, holder details, and transactions

Attribute	Description	Type
`tabs[].name`	FI type tab names (e.g. "DEPOSIT")	Array
`DEPOSIT.summary[].currentBalance`	Current account balance	String
`DEPOSIT.summary[].accountNumber`	Masked account number	String
`DEPOSIT.summary[].accountType`	SAVINGS \| CURRENT \| OD	String
`DEPOSIT.accountHolder[].name`	Account holder name	String
`DEPOSIT.accountHolder[].pan`	PAN number	String
`DEPOSIT.transactions[].amount`	Transaction amount	String
`DEPOSIT.transactions[].type`	DEBIT \| CREDIT	String
`DEPOSIT.transactions[].narration`	Transaction description	String
`DEPOSIT.transactions[].tranTimestamp`	Transaction timestamp	ISO 8601
`DEPOSIT.transactions[].currentBalance`	Balance after transaction	String

📈

Analytics API

ML-powered analytics for single and aggregate accounts — available in sync and async modes. Includes spend categorization, income analysis, and EMI matching.

Single Account — Generate Analytics (Sync & Async)

POST https://api.sandbox.unaport.com/backend-v2/api/v2/FIU/Analytics/{reportId}/{sessionId}

Headers: Authorization: Bearer <token>

Response	Description	Type
`reportId`	Unique ID for the generated analytics report	Integer
`status`	HTTP status of the request	String

Aggregate Analytics — Generate (Sync & Async)

POST https://api.sandbox.unaport.com/backend-v2/api/v2/FIU/AggregateAnalytics/{sessionId}

Header	Description
`Authorization`	Bearer token
`OrgID`	Organisation ID

🔔

Consent Notification API

A webhook you implement on your server. Unaport calls it when consent status changes due to customer actions on the AA platform.

🔧Expose this endpoint and share the base_url with Unaport. Whitelist IPs — UAT: 15.206.247.111 Production: 13.234.23.251

Attribute	Description	Type
`ConsentStatusNotification.consentId`	Consent ID	String
`ConsentStatusNotification.consentHandle`	Consent handle	String
`ConsentStatusNotification.consentStatus`	`ACTIVE` \| `PAUSED` \| `REVOKED` \| `EXPIRED` \| `FAILED`	String
`Notifier.type`	Source — `AA`	String
`txnid`	Unique transaction ID	UUID

📊

Data Notification API

Webhook sent when financial data is fetched. Contains the sessionId to retrieve the data.

Attribute	Description	Type
`FIStatusNotification.sessionId`	Use this to call Fetch Data by Session	String
`FIStatusNotification.sessionStatus`	`ACTIVE` \| `COMPLETED`	String
`Accounts[].FIStatus`	`READY` — data is available	String

📈

Analytics Notification API

Webhook called when analytics processing completes for a session.

Attribute	Description	Type
`sessionId`	Session identifier	String
`analyticId`	List of generated analytic report IDs	Array
`status`	`SUCCESS` \| `FAILED`	String

📜

Consent Relationship Overview

How consent status, consent handle, and consent ID relate throughout the full lifecycle.

ℹ Consent Handle is available from the moment a consent is raised. Consent ID is only generated after customer approval at the AA.

Use Case	Status	Notifier	Receiver	Consent ID	Handle
Consent Approval Flow
FIU raises consent request	`PENDING`	AA	Customer	Null	✓
Customer rejects at AA	`FAILED`	AA	FIU	Null	✓
Customer approves / pauses / revokes	`READY`	AA	FIU, FIP	✓	✓
Consent expires at AA	`EXPIRED`	AA	FIU	Null	✓
Consent Lifecycle Status
Consent request created	`CREATED`	AA	Customer	Null	✓
Customer approves	`ACTIVE`	AA	FIU, FIP	✓	✓
Customer revokes via AA	`REVOKED`	AA	FIU, FIP	✓	✓
FIU revokes consent	`REVOKED`	FIU	AA	✓	✓
Customer pauses	`PAUSED`	AA	FIU, FIP	✓	✓
Customer resumes	`ACTIVE`	AA	FIU, FIP	✓	✓
Consent expires	`EXPIRED`	AA	FIU, FIP	✓	✓