Consent List

​

Overview

• Display all consents to the customer in their account dashboard
• Check if active consents exist before creating new ones
• Audit consent history for compliance and record-keeping purposes
• Verify consent status before initiating data fetch operations

​

Endpoint

POST {{Base_URL}}/getconsentslist

​

Authentication

​

Request Body

​

Important Notes

• Mobile Number Format: The mobile number must be exactly 10 digits without any country code, spaces, hyphens, or other special characters. Examples: 9876543210 (correct), +919876543210 (incorrect), 98765-43210 (incorrect).
• Product Filtering: When productID is provided, the API only returns consents associated with that product. If omitted, consents across all products for the mobile number are returned.
• Historical Data: The API returns all consents regardless of their status, providing a complete historical view of the consent relationship with the customer.
• Pagination: Use limit and pageno together to paginate through large result sets. For example, limit: 10 and pageno: 1 returns the first 10 results.

​

Response

​

Success Response (200 OK)

{
  "ver": "1.21.0",
  "status": "success",
  "data": [
    {
      "consentID": "20918495-ea9c-4508-a1b4-93ca1fbfd0f3",
      "consentHandle": "8b5b9333-00df-4b99-99d8-b0918f897e7b",
      "status": "ACTIVE",
      "productID": "TESTWM01",
      "accountID": "test123",
      "aaId": "onemoney-aa",
      "createdOn": "2025-09-15T10:30:00.000Z",
      "modifiedOn": "2025-09-15T11:00:00.000Z",
      "consentStart": "2025-09-15T10:30:00.000Z",
      "consentExpiry": "2026-09-15T10:30:00.000Z",
      "fetchType": "PERIODIC",
      "fiTypes": ["DEPOSIT", "TERM_DEPOSIT"],
      "fipId": "HDFC-FIP",
      "maskedAccountNumber": "XXXXXXXX1234"
    },
    {
      "consentID": "3f2a8c91-2d4e-4b1a-8c6d-1e5f4a7b8c1d",
      "consentHandle": "7a4b8222-11cd-4a88-88d7-a0817e786d6a",
      "status": "REVOKED",
      "productID": "TESTWM01",
      "accountID": "test123",
      "aaId": "onemoney-aa",
      "createdOn": "2025-08-01T09:00:00.000Z",
      "modifiedOn": "2025-09-01T14:30:00.000Z",
      "consentStart": "2025-08-01T09:00:00.000Z",
      "consentExpiry": "2026-08-01T09:00:00.000Z",
      "fetchType": "ONETIME",
      "fiTypes": ["DEPOSIT"],
      "fipId": "ICICI-FIP",
      "maskedAccountNumber": "XXXXXXXX5678"
    }
  ]
}

​

Consent Object Fields

​

Empty Result Response

{
  "ver": "1.21.0",
  "status": "success",
  "data": []
}

​

Error Response (400 Bad Request)

{
  "ver": "1.21.0",
  "timestamp": "2025-10-01T11:43:37.741Z",
  "errorCode": "InvalidRequest",
  "errorMsg": " [ mobileNumber must be valid 10 digit ] "
}

​

Common Error Codes

​

Example Request

curl --location '{{Base_URL}}/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 '{
    "mobileNumber": "9876543210",
    "productID": "TESTWM01",
    "accountID": "test123",
    "status": ["ACTIVE", "PENDING"],
    "limit": 10,
    "pageno": 1
}'

​

Use Cases

​

Displaying Customer Consent Dashboard

async function loadConsentDashboard(mobileNumber, productID) {
  const response = await getConsentsList(mobileNumber, productID);
  const consents = response.data;

  // Organize by status
  const organized = {
    active: consents.filter(c => c.status === 'ACTIVE'),
    pending: consents.filter(c => c.status === 'PENDING'),
    revoked: consents.filter(c => c.status === 'REVOKED'),
    expired: consents.filter(c => c.status === 'EXPIRED')
  };

  return organized;
}

​

Checking for Existing Active Consents

def has_active_consent(mobile_number, product_id, fip_id):
    """Check if customer already has an active consent for a specific FIP"""
    response = get_consents_list(mobile_number, product_id)

    for consent in response['data']:
        if consent['status'] == 'ACTIVE' and consent['fipId'] == fip_id:
            return True, consent['consentID']

    return False, None

# Usage
has_consent, consent_id = has_active_consent('9876543210', 'TESTWM01', 'HDFC-FIP')
if has_consent:
    print(f"Active consent already exists: {consent_id}")
else:
    # Proceed to create new consent
    pass

​

Consent Audit Report

function generateConsentAuditReport(consents) {
  return consents.map(consent => ({
    consentID: consent.consentID,
    status: consent.status,
    fipName: consent.fipId,
    accountNumber: consent.maskedAccountNumber,
    createdDate: new Date(consent.createdOn).toLocaleDateString(),
    expiryDate: new Date(consent.consentExpiry).toLocaleDateString(),
    daysActive: calculateDaysBetween(consent.createdOn, consent.modifiedOn),
    dataTypes: consent.fiTypes.join(', ')
  }));
}

​

Best Practices

1. Cache Consent Lists: The consent list doesn’t change frequently. Cache the results for a reasonable duration (e.g., 5-10 minutes) to reduce API calls.
2. Status Filtering: After retrieving the list, filter on the client side based on your needs (active consents for data fetching, pending for reminders, etc.).
3. Combine with Webhooks: Use this API to populate initial state, then rely on webhooks for real-time updates rather than polling repeatedly.
4. Error Handling: Always check the status field and handle empty arrays gracefully when no consents exist.
5. Display Masked Data: When showing consent information to customers, use the maskedAccountNumber to protect privacy while allowing customers to identify their accounts.

​

API Version Comparison

• V1 (this API): Uses mobile number as identifier. Supports optional filtering by product, account, and status. Supports pagination via limit and pageno.
• V2: Uses flexible party identifiers (mobile, email, PAN, AADHAR, DOB, GSTIN). Returns similar flat list with enhanced filtering based on identifier type and account ID.
• V1 Unique Accounts: Provides deduplicated view with unique accounts per FIP. Supports status filtering and pagination for large result sets.

• You need simple, straightforward consent listing by mobile number
• You want optional filtering by product, account, or status
• You need basic pagination support via limit and pageno
• You want the most compatible API version with legacy systems