Consent List V2

​

Overview

• Your customer identification strategy varies across products or channels
• You need to support multiple identifier types within the same application
• You’re integrating with systems that use PAN or email as primary identifiers
• You want more precise filtering using the account ID along with party identifiers

​

Endpoint

POST {{Base_URL}}/v2/getconsentslist

​

Authentication

​

Request Body

​

Important Notes

• Identifier Validation: The API validates that the partyIdentifierValue matches the expected format for the partyIdentifierType. Mismatched formats will result in validation errors.
• Mobile Format: Mobile numbers must be exactly 10 digits without country code (+91), spaces, hyphens, or other special characters. Example: 9876543210 (correct), +919876543210 (incorrect).
• Email Format: Email addresses must follow standard email format validation. The API checks for valid email structure including @ symbol and domain.
• PAN Format: PAN numbers must follow the Indian PAN format: 5 uppercase letters, 4 digits, and 1 uppercase letter. Example: ABCDE1234F.
• Account ID Filtering: Unlike V1 which returns all consents for a product, V2 requires and filters by accountID, providing more targeted results for specific customer journeys.

​

Response

​

Success Response (200 OK)

{
  "ver": "1.21.0",
  "status": "success",
  "data": [
    {
      "consentID": "8d8dbf30-7057-441a-9486-6e67c70b4b2e",
      "consentHandle": "3a3f2d96-fc3b-42e5-804f-e65d10a4be98",
      "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",
      "partyIdentifierType": "MOBILE",
      "partyIdentifierValue": "9876543210"
    }
  ]
}

​

Consent Object Fields

​

Empty Result Response

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

• No consents have been created for this combination of party identifier, product ID, and account ID
• All consents matching the criteria have been deleted or purged from the system
• The party identifier value doesn’t match any consent records (possible typo or incorrect identifier)

​

Error Response (400 Bad Request)

{
  "ver": "1.21.0",
  "timestamp": "2025-10-01T11:43:56.125Z",
  "errorCode": "InvalidRequest",
  "errorMsg": " [ partyIdentifierValue must be valid Mobile number ] "
}

​

Common Error Codes

​

Example Request

curl --location '{{Base_URL}}/v2/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": "TESTWM01",
    "accountID": "test123"
}'

​

Use Cases

​

Multi-Channel Customer Identification

async function getCustomerConsents(customer, productID, accountID) {
  // Determine which identifier to use based on what's available
  if (customer.mobile) {
    return await getConsentsV2('MOBILE', customer.mobile, productID, accountID);
  } else if (customer.email) {
    return await getConsentsV2('EMAIL', customer.email, productID, accountID);
  } else if (customer.pan) {
    return await getConsentsV2('PAN', customer.pan, productID, accountID);
  } else {
    throw new Error('No valid identifier available for customer');
  }
}

​

Account-Specific Consent Tracking

def get_loan_application_consents(application_id, customer_mobile, product_id):
    """Get consents specific to a loan application"""
    account_id = f"LOAN_{application_id}"

    response = get_consents_v2(
        identifier_type='MOBILE',
        identifier_value=customer_mobile,
        product_id=product_id,
        account_id=account_id
    )

    # Check if active consents exist for this application
    active_consents = [
        c for c in response['data']
        if c['status'] == 'ACTIVE'
    ]

    return {
        'application_id': application_id,
        'has_active_consents': len(active_consents) > 0,
        'consent_count': len(active_consents),
        'consents': active_consents
    }

​

Cross-Reference Identifier Types

async function validateCustomerConsents(customer) {
  const results = {};

  // Query with different identifiers
  if (customer.mobile) {
    const mobileResults = await getConsentsV2(
      'MOBILE',
      customer.mobile,
      'TESTWM01',
      customer.accountID
    );
    results.mobile = mobileResults.data;
  }

  if (customer.pan) {
    const panResults = await getConsentsV2(
      'PAN',
      customer.pan,
      'TESTWM01',
      customer.accountID
    );
    results.pan = panResults.data;
  }

  // Verify consistency - same consents should appear in both queries
  const mobileConsentIDs = new Set(results.mobile?.map(c => c.consentID) || []);
  const panConsentIDs = new Set(results.pan?.map(c => c.consentID) || []);

  const isConsistent =
    mobileConsentIDs.size === panConsentIDs.size &&
    [...mobileConsentIDs].every(id => panConsentIDs.has(id));

  return {
    isConsistent,
    mobileCount: mobileConsentIDs.size,
    panCount: panConsentIDs.size,
    consents: results
  };
}

​

Best Practices

1. Choose the Right Identifier: Use the identifier type that best matches your customer data model and acquisition channel. Mobile is most common, but PAN may be required for certain financial products.
2. Account ID Strategy: Design a consistent account ID naming convention that allows you to correlate consents with your internal workflows. Examples: LOAN_${applicationId}, WM_${customerId}, INS_${policyId}.
3. Identifier Validation: Validate identifier formats on the client side before making API calls to reduce unnecessary error responses and improve user experience.
4. Caching Strategy: Cache consent lists per account ID for reasonable durations, but ensure cache invalidation when webhook notifications indicate status changes.
5. Error Handling: Handle validation errors gracefully by providing clear user feedback about identifier format requirements.

​

API Version Comparison

• V1: Uses only mobile number as identifier. No account ID filtering. Returns all consents for a product.
• V2 (this API): Supports multiple identifier types (MOBILE, EMAIL, PAN). Requires account ID for more targeted filtering. Recommended for new integrations.
• V1 Unique Accounts: Provides deduplicated view with pagination. Best for scenarios needing unique account lists across multiple consents.

• You need flexibility in customer identification methods
• You want more precise filtering using account IDs
• You’re building new integrations and want to future-proof identifier handling
• Your system uses PAN or email as primary identifiers alongside or instead of mobile numbers