> ## Documentation Index
> Fetch the complete documentation index at: https://developer.moneyone.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Consent List V3

> Retrieve consents by party identifier, consent handle, or consent ID — with full account-level details.

## Overview

The Consent List V3 API is the most flexible version of consent listing. It supports three distinct lookup modes:

1. **Party identifier lookup** — query by customer identifier (`MOBILE`, `EMAIL`, `PAN`, `AADHAR`, `DOB`, or `GSTIN`) along with `productID` and `accountID`
2. **Consent handle lookup** — query directly by one or more consent handle UUIDs
3. **Consent ID lookup** — query directly by one or more consent ID UUIDs

Modes 2 and 3 are useful when you already have a consent handle or consent ID and want to fetch its current state without needing to know the party identifier. They are mutually exclusive — you cannot pass both `consentHandle` and `consentID` in the same request.

The response includes a nested `accounts` array per consent, giving you FIP-level account details alongside the consent metadata.

## Endpoint

<CodeGroup>
  ```bash Request theme={null}
  POST {{Base_URL}}/v3/getconsentslist
  ```
</CodeGroup>

## Authentication

| Header           | Type   | Required | Description                                                             |
| ---------------- | ------ | -------- | ----------------------------------------------------------------------- |
| `Content-Type`   | string | Yes      | Must be `application/json`.                                             |
| `client_id`      | string | Yes      | Your unique client identifier provided during FIU onboarding.           |
| `client_secret`  | string | Yes      | Your confidential client secret. Never expose this in client-side code. |
| `organisationId` | string | Yes      | Your organisation's unique identifier in the FinPro system.             |
| `appIdentifier`  | string | Yes      | Application-specific identifier for the calling service.                |

## Request Body

The request body depends on which lookup mode you use.

### Mode 1 — Party Identifier Lookup

All four fields below are required together. If `consentHandle` or `consentID` is absent, these fields become mandatory.

| Parameter              | Type   | Required | Description                                                                                     |
| ---------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `partyIdentifierType`  | string | Yes      | The type of identifier. Valid values: `MOBILE`, `EMAIL`, `PAN`, `AADHAR`, `DOB`, `GSTIN`.       |
| `partyIdentifierValue` | string | Yes      | The identifier value, validated against the format for `partyIdentifierType` (see table below). |
| `productID`            | string | Yes      | The consent template identifier to filter by.                                                   |
| `accountID`            | string | Yes      | The account identifier to filter by.                                                            |
| `status`               | string | No       | Filter by consent status. Valid values: `ACTIVE`, `PAUSED`, `REVOKED`, `EXPIRED`, `PENDING`.    |

### Mode 2 — Consent Handle Lookup

| Parameter       | Type      | Required | Description                                                                                  |
| --------------- | --------- | -------- | -------------------------------------------------------------------------------------------- |
| `consentHandle` | string\[] | Yes      | Array of one or more consent handle UUIDs (v4). Cannot be combined with `consentID`.         |
| `status`        | string    | No       | Filter by consent status. Valid values: `ACTIVE`, `PAUSED`, `REVOKED`, `EXPIRED`, `PENDING`. |

### Mode 3 — Consent ID Lookup

| Parameter   | Type      | Required | Description                                                                                  |
| ----------- | --------- | -------- | -------------------------------------------------------------------------------------------- |
| `consentID` | string\[] | Yes      | Array of one or more consent ID UUIDs (v4). Cannot be combined with `consentHandle`.         |
| `status`    | string    | No       | Filter by consent status. Valid values: `ACTIVE`, `PAUSED`, `REVOKED`, `EXPIRED`, `PENDING`. |

### Party Identifier Format Reference

| `partyIdentifierType` | Expected Format                                     | Example                |
| --------------------- | --------------------------------------------------- | ---------------------- |
| `MOBILE`              | 10-digit numeric string, no country code            | `9876543210`           |
| `EMAIL`               | Valid email address                                 | `customer@example.com` |
| `PAN`                 | 5 uppercase letters + 4 digits + 1 uppercase letter | `ABCDE1234F`           |
| `AADHAR`              | 12-digit numeric string                             | `123456789012`         |
| `DOB`                 | ISO date in `YYYY-MM-DD` format                     | `1990-01-15`           |
| `GSTIN`               | 15-character GSTIN number                           | `22ABCDE1234F1Z5`      |

## Response

### Success Response (200 OK)

<CodeGroup>
  ```json Party Identifier Lookup theme={null}
  {
    "ver": "1.21.0",
    "status": "success",
    "data": [
      {
        "consentID": "a21d747a-c166-46f2-b0d6-4c22c575fb14",
        "consentHandle": "8814cd61-bf02-4548-87d8-5d1c0211cd91",
        "status": "ACTIVE",
        "productID": "MP9",
        "accountID": "1234",
        "aaId": "onemoney-aa",
        "consentCreationData": "2026-05-18T10:22:48.000Z",
        "consent_expiry": "2027-05-18 10:22:48",
        "vua": "9876543210@onemoney",
        "accounts": [
          {
            "fipName": "HDFC Bank",
            "fipId": "HDFC-FIP",
            "accountType": "SAVINGS",
            "linkReferenceNumber": "0ffc1696-38d2-4ef1-8c87-d3835d1f50a1",
            "maskedAccountNumber": "XXXX1234",
            "fiType": "DEPOSIT"
          }
        ]
      }
    ]
  }
  ```

  ```json Consent Handle / Consent ID Lookup theme={null}
  {
    "ver": "1.21.0",
    "status": "success",
    "data": [
      {
        "consentID": "eb460772-e89a-462d-b9e3-24a712a43e64",
        "consentHandle": "7dedf596-67b3-41f5-a3f9-55ceca43f31f",
        "status": "ACTIVE",
        "productID": "MP9",
        "accountID": "1234",
        "aaId": "onemoney-aa",
        "consentCreationData": "2026-05-18T10:24:53.000Z",
        "consent_expiry": "2027-05-18 10:24:53",
        "vua": "9876543210@onemoney",
        "accounts": [
          {
            "fipName": "HDFC Bank",
            "fipId": "HDFC-FIP",
            "accountType": "SAVINGS",
            "linkReferenceNumber": "0ffc1696-38d2-4ef1-8c87-d3835d1f50a1",
            "maskedAccountNumber": "XXXX1234",
            "fiType": "DEPOSIT"
          }
        ]
      }
    ]
  }
  ```
</CodeGroup>

### Response Fields

| Field    | Type   | Description                                                |
| -------- | ------ | ---------------------------------------------------------- |
| `ver`    | string | FinPro API version that processed the request.             |
| `status` | string | `success` for all 200 responses.                           |
| `data`   | array  | Array of consent objects. Empty array if no matches found. |

### Consent Object Fields

| Field                 | Type           | Description                                                                                                                        |
| --------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `consentID`           | string \| null | Unique consent identifier assigned by the Account Aggregator after the customer approves. `null` for pending or rejected consents. |
| `consentHandle`       | string         | Consent handle generated when the consent request was created. Available immediately upon creation.                                |
| `status`              | string         | Current consent status: `ACTIVE`, `PAUSED`, `REVOKED`, `EXPIRED`, or `PENDING`.                                                    |
| `productID`           | string         | The consent template used to create this consent.                                                                                  |
| `accountID`           | string         | The account identifier associated with this consent.                                                                               |
| `aaId`                | string         | Identifier of the Account Aggregator that processed this consent.                                                                  |
| `consentCreationData` | string         | ISO 8601 timestamp of when the consent was created.                                                                                |
| `consent_expiry`      | string         | Timestamp of when the consent expires. After this, data fetching is no longer possible.                                            |
| `vua`                 | string         | The customer's virtual user address at the AA (e.g., `9876543210@onemoney`).                                                       |
| `accounts`            | array          | List of linked financial accounts covered by this consent.                                                                         |

### Account Object Fields

| Field                 | Type   | Description                                                                       |
| --------------------- | ------ | --------------------------------------------------------------------------------- |
| `fipName`             | string | Human-readable name of the Financial Information Provider (bank/institution).     |
| `fipId`               | string | Unique identifier of the FIP in the AA ecosystem.                                 |
| `accountType`         | string | Type of account, e.g. `SAVINGS`, `CURRENT`, `RECURRING_DEPOSIT`.                  |
| `linkReferenceNumber` | string | The AA-assigned reference number for the linked account.                          |
| `maskedAccountNumber` | string | Account number with most digits masked for privacy, e.g. `XXXX1234`.              |
| `fiType`              | string | Financial information type, e.g. `DEPOSIT`, `MUTUAL_FUNDS`, `INSURANCE_POLICIES`. |

### Empty Result (200 OK)

```json theme={null}
{
  "ver": "1.21.0",
  "status": "success",
  "data": []
}
```

### Error Response (400 Bad Request)

```json theme={null}
{
  "ver": "1.21.0",
  "timestamp": "2026-05-18T11:43:56.125Z",
  "errorCode": "InvalidRequest",
  "errorMsg": " [ \"partyIdentifierValue\" must be valid Mobile number ] "
}
```

## Common Error Codes

| Error Code               | HTTP Status | Description                                                                           | Resolution                                                                                              |
| ------------------------ | ----------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `InvalidRequest`         | 400         | Missing or invalid fields, or both `consentHandle` and `consentID` provided together. | Check that exactly one lookup mode is used. For party identifier mode, all four fields must be present. |
| `InvalidPartyIdentifier` | 400         | `partyIdentifierValue` does not match the expected format for `partyIdentifierType`.  | See the Party Identifier Format Reference table above.                                                  |
| `InvalidProductID`       | 400         | The `productID` does not exist or is not configured for your organisation.            | Verify the product ID in the FinPro admin portal.                                                       |
| `InvalidAccountID`       | 400         | The `accountID` is invalid or not associated with the given product.                  | Confirm the account ID was used during consent creation.                                                |
| `AuthenticationFailed`   | 401         | Invalid or missing authentication credentials.                                        | Verify `client_id`, `client_secret`, and `organisationId`.                                              |

## Example Requests

<CodeGroup>
  ```bash cURL — Party Identifier (Mobile) theme={null}
  curl --location '{{Base_URL}}/v3/getconsentslist' \
  --header 'Content-Type: application/json' \
  --header 'client_id: {{Client_Id}}' \
  --header 'client_secret: {{Client_Secret}}' \
  --header 'organisationId: {{Organisation_Id}}' \
  --header 'appIdentifier: {{App_Identifier}}' \
  --data '{
      "partyIdentifierType": "MOBILE",
      "partyIdentifierValue": "9876543210",
      "productID": "MP9",
      "accountID": "1234"
  }'
  ```

  ```bash cURL — Consent Handle Lookup theme={null}
  curl --location '{{Base_URL}}/v3/getconsentslist' \
  --header 'Content-Type: application/json' \
  --header 'client_id: {{Client_Id}}' \
  --header 'client_secret: {{Client_Secret}}' \
  --header 'organisationId: {{Organisation_Id}}' \
  --header 'appIdentifier: {{App_Identifier}}' \
  --data '{
      "consentHandle": ["8814cd61-bf02-4548-87d8-5d1c0211cd91"]
  }'
  ```

  ```bash cURL — Consent ID Lookup theme={null}
  curl --location '{{Base_URL}}/v3/getconsentslist' \
  --header 'Content-Type: application/json' \
  --header 'client_id: {{Client_Id}}' \
  --header 'client_secret: {{Client_Secret}}' \
  --header 'organisationId: {{Organisation_Id}}' \
  --header 'appIdentifier: {{App_Identifier}}' \
  --data '{
      "consentID": ["a21d747a-c166-46f2-b0d6-4c22c575fb14"]
  }'
  ```

  ```javascript JavaScript theme={null}
  async function getConsentsV3(payload) {
    const response = await fetch('{{Base_URL}}/v3/getconsentslist', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'client_id': '{{Client_Id}}',
        'client_secret': '{{Client_Secret}}',
        'organisationId': '{{Organisation_Id}}',
        'appIdentifier': '{{App_Identifier}}'
      },
      body: JSON.stringify(payload)
    });
    return await response.json();
  }

  // Party identifier lookup
  const byMobile = await getConsentsV3({
    partyIdentifierType: 'MOBILE',
    partyIdentifierValue: '9876543210',
    productID: 'MP9',
    accountID: '1234'
  });

  // Consent handle lookup
  const byHandle = await getConsentsV3({
    consentHandle: ['8814cd61-bf02-4548-87d8-5d1c0211cd91']
  });

  // Consent ID lookup
  const byId = await getConsentsV3({
    consentID: ['a21d747a-c166-46f2-b0d6-4c22c575fb14']
  });
  ```

  ```python Python theme={null}
  import requests

  def get_consents_v3(payload):
      url = "{{Base_URL}}/v3/getconsentslist"
      headers = {
          "Content-Type": "application/json",
          "client_id": "{{Client_Id}}",
          "client_secret": "{{Client_Secret}}",
          "organisationId": "{{Organisation_Id}}",
          "appIdentifier": "{{App_Identifier}}"
      }
      response = requests.post(url, json=payload, headers=headers)
      return response.json()

  # Party identifier lookup
  by_mobile = get_consents_v3({
      "partyIdentifierType": "MOBILE",
      "partyIdentifierValue": "9876543210",
      "productID": "MP9",
      "accountID": "1234"
  })

  # Consent handle lookup
  by_handle = get_consents_v3({
      "consentHandle": ["8814cd61-bf02-4548-87d8-5d1c0211cd91"]
  })

  # Consent ID lookup
  by_id = get_consents_v3({
      "consentID": ["a21d747a-c166-46f2-b0d6-4c22c575fb14"]
  })
  ```
</CodeGroup>


## OpenAPI

````yaml POST /v3/getconsentslist
openapi: 3.0.3
info:
  title: FinPro API
  description: MoneyOne FinPro - Account Aggregator FIU Platform APIs
  version: 1.21.0
servers:
  - url: '{baseUrl}'
    description: FinPro API Server
    variables:
      baseUrl:
        default: https://scramblerpay-uat.moneyone.in
        description: API Base URL - change this to your environment
security:
  - clientId: []
    clientSecret: []
    organisationId: []
    appIdentifier: []
paths:
  /v3/getconsentslist:
    post:
      tags:
        - Consent Management
      summary: Get Consents List V3
      description: >-
        Retrieve consents by party identifier, consent handle, or consent ID.
        Supports three lookup modes: party identifier (MOBILE, EMAIL, PAN,
        AADHAR, DOB, GSTIN) with productID and accountID; direct lookup by
        consentHandle array; or direct lookup by consentID array. consentHandle
        and consentID are mutually exclusive.
      operationId: getConsentsListV3
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetConsentsListV3Request'
            example:
              partyIdentifierType: MOBILE
              partyIdentifierValue: '9876543210'
              productID: MP9
              accountID: '1234'
      responses:
        '200':
          description: Consents retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetConsentsListV3SuccessResponse'
              example:
                ver: 1.21.0
                status: success
                data:
                  - consentID: a21d747a-c166-46f2-b0d6-4c22c575fb14
                    consentHandle: 8814cd61-bf02-4548-87d8-5d1c0211cd91
                    status: ACTIVE
                    productID: MP9
                    accountID: '1234'
                    aaId: onemoney-aa
                    consentCreationData: '2026-05-18T10:22:48.000Z'
                    consent_expiry: '2027-05-18 10:22:48'
                    vua: 9876543210@onemoney
                    accounts:
                      - fipName: HDFC Bank
                        fipId: HDFC-FIP
                        accountType: SAVINGS
                        linkReferenceNumber: 0ffc1696-38d2-4ef1-8c87-d3835d1f50a1
                        maskedAccountNumber: XXXX1234
                        fiType: DEPOSIT
        '400':
          description: Bad Request - Invalid data or validation failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                ver: 1.21.0
                timestamp: '2026-05-18T11:43:56.125Z'
                errorCode: InvalidRequest
                errorMsg: ' [ "partyIdentifierValue" must be valid Mobile number ] '
        '401':
          description: Authentication Failed - Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - clientId: []
          clientSecret: []
          organisationId: []
          appIdentifier: []
components:
  schemas:
    GetConsentsListV3Request:
      type: object
      description: >-
        Request body for v3 consent list. Use party identifier mode OR
        consentHandle OR consentID — consentHandle and consentID are mutually
        exclusive.
      properties:
        partyIdentifierType:
          type: string
          enum:
            - MOBILE
            - EMAIL
            - PAN
            - AADHAR
            - DOB
            - GSTIN
          description: >-
            Required when using party identifier lookup mode. The type of
            customer identifier.
        partyIdentifierValue:
          type: string
          description: >-
            Required when using party identifier lookup mode. The identifier
            value, validated against the format for partyIdentifierType.
        productID:
          type: string
          description: >-
            Required when using party identifier lookup mode. The consent
            template identifier.
        accountID:
          type: string
          description: >-
            Required when using party identifier lookup mode. The account
            identifier.
        consentHandle:
          type: array
          items:
            type: string
            format: uuid
          minItems: 1
          description: >-
            Array of consent handle UUIDs for direct lookup. Mutually exclusive
            with consentID.
        consentID:
          type: array
          items:
            type: string
            format: uuid
          minItems: 1
          description: >-
            Array of consent ID UUIDs for direct lookup. Mutually exclusive with
            consentHandle.
        status:
          type: string
          enum:
            - ACTIVE
            - PAUSED
            - REVOKED
            - EXPIRED
            - PENDING
          description: Optional filter by consent status.
    GetConsentsListV3SuccessResponse:
      type: object
      properties:
        ver:
          type: string
          description: FinPro API version.
        status:
          type: string
          description: Always 'success' for 200 responses.
        data:
          type: array
          description: Array of consent objects. Empty if no matches found.
          items:
            $ref: '#/components/schemas/ConsentListV3Item'
    ErrorResponse:
      type: object
      properties:
        ver:
          type: string
          description: API version
        timestamp:
          type: string
          format: date-time
          description: When the error occurred
        errorCode:
          type: string
          description: Error category code
        errorMsg:
          type: string
          description: Detailed error message
        status:
          type: string
          description: FinPro-specific error code (FPxxxx format)
    ConsentListV3Item:
      type: object
      properties:
        consentID:
          type: string
          format: uuid
          description: >-
            Unique consent identifier assigned by the AA after customer
            approval. Null for pending or rejected consents.
        consentHandle:
          type: string
          format: uuid
          description: Consent handle generated at consent request creation time.
        status:
          type: string
          enum:
            - PENDING
            - ACTIVE
            - REVOKED
            - EXPIRED
            - PAUSED
          description: Current consent status.
        productID:
          type: string
          description: The consent template used to create this consent.
        accountID:
          type: string
          description: The account identifier associated with this consent.
        aaId:
          type: string
          description: Identifier of the Account Aggregator that processed this consent.
        consentCreationData:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the consent was created.
        consent_expiry:
          type: string
          description: Timestamp of when the consent expires.
        vua:
          type: string
          description: >-
            The customer's virtual user address at the AA, e.g.
            '9876543210@onemoney'.
        accounts:
          type: array
          description: List of linked financial accounts covered by this consent.
          items:
            $ref: '#/components/schemas/ConsentListV3Account'
    ConsentListV3Account:
      type: object
      properties:
        fipName:
          type: string
          description: Human-readable name of the Financial Information Provider.
        fipId:
          type: string
          description: Unique identifier of the FIP in the AA ecosystem.
        accountType:
          type: string
          description: Type of account, e.g. SAVINGS, CURRENT, RECURRING_DEPOSIT.
        linkReferenceNumber:
          type: string
          description: AA-assigned reference number for the linked account.
        maskedAccountNumber:
          type: string
          description: Account number with most digits masked, e.g. XXXX1234.
        fiType:
          type: string
          description: >-
            Financial information type, e.g. DEPOSIT, MUTUAL_FUNDS,
            INSURANCE_POLICIES.
  securitySchemes:
    clientId:
      type: apiKey
      in: header
      name: client_id
      description: Your unique client identifier provided by MoneyOne during FIU onboarding
    clientSecret:
      type: apiKey
      in: header
      name: client_secret
      description: Your confidential client secret provided by MoneyOne
    organisationId:
      type: apiKey
      in: header
      name: organisationId
      description: Your organization's unique identifier in the FinPro system
    appIdentifier:
      type: apiKey
      in: header
      name: appIdentifier
      description: Application-specific identifier for tracking API calls

````