Skip to main content
POST
Error

Overview

The Consent List V2 API provides an enhanced version of consent listing with support for flexible party identifiers. While V1 only supports mobile numbers, V2 allows you to query consents using different identifier types including mobile numbers, email addresses, PAN (Permanent Account Number), AADHAR, DOB (Date of Birth), or GSTIN. This flexibility is particularly valuable when:
  • 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
V2 maintains the same simple, flat list structure as V1 while providing enhanced querying capabilities through the party identifier system. This makes it the recommended choice for new integrations that need flexible customer identification.

Endpoint

Authentication

This API requires authentication through the following headers that must be included in every request:

Request Body

The request body must be a JSON object containing the following parameters:

Party Identifier Type Validation

The partyIdentifierValue format is validated based on the partyIdentifierType:

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.
  • AADHAR Format: Aadhaar numbers must be exactly 12 digits. Example: 123456789012.
  • DOB Format: Date of birth must follow the YYYY-MM-DD format. Example: 1990-01-15.
  • GSTIN Format: GSTIN must be a 15-character alphanumeric string following the standard Indian GSTIN format. Example: 22ABCDE1234F1Z5.
  • 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)

When consents are found matching all the specified criteria, the API returns an array of consent objects:
Each consent object in the data array contains the following fields:

Empty Result Response

If no consents match all the specified criteria:
This can occur when:
  • 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)

When the request contains invalid data or fails validation:

Common Error Codes

Example Request

Use Cases

Multi-Channel Customer Identification

Support different identifier types based on the customer acquisition channel:
Track consents for specific loan applications or customer interactions:

Cross-Reference Identifier Types

Validate that the same customer entity has consents across different identifier types:

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, AADHAR, DOB, GSTIN). Requires account ID for more targeted filtering. Optional consentHandle and status filters. Recommended for new integrations.
  • V1 Unique Accounts: Provides deduplicated view with pagination. Best for scenarios needing unique account lists across multiple consents.
Choose V2 when:
  • 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, email, AADHAR, DOB, or GSTIN as primary identifiers alongside or instead of mobile numbers
  • You need to filter by specific consent handle or status

Authorizations

client_id
string
header
required

Your unique client identifier provided by MoneyOne during FIU onboarding

client_secret
string
header
required

Your confidential client secret provided by MoneyOne

organisationId
string
header
required

Your organization's unique identifier in the FinPro system

appIdentifier
string
header
required

Application-specific identifier for tracking API calls

Body

application/json
partyIdentifierType
enum<string>
required

The type of identifier being used to query consents. Valid values are MOBILE, EMAIL, PAN, AADHAR, DOB, or GSTIN. This determines how the partyIdentifierValue will be validated and matched against consent records.

Available options:
MOBILE,
EMAIL,
PAN,
AADHAR,
DOB,
GSTIN
partyIdentifierValue
string
required

The actual identifier value to search for. Format must match the partyIdentifierType: for MOBILE, provide a 10-digit number; for EMAIL, provide a valid email address; for PAN, provide a 10-character PAN number (5 uppercase letters, 4 digits, 1 uppercase letter); for AADHAR, provide a 12-digit number; for DOB, provide date in YYYY-MM-DD format; for GSTIN, provide a 15-character GSTIN number.

productID
string
required

The unique identifier of the consent template (product) for which you want to retrieve consents. This filters the consent list to only show consents created using this specific product configuration.

accountID
string
required

The account identifier that links consents to specific customer interactions in your system. This provides an additional level of filtering, returning only consents associated with this specific account ID.

An optional consent handle to filter results to a specific consent request. Must be alphanumeric (hyphens allowed). Use this when you need to look up a specific consent by its handle.

Pattern: ^[a-zA-Z0-9-]+$
status
enum<string>

An optional consent status value to filter the results. If not provided, consents of all statuses are returned.

Available options:
ACTIVE,
PAUSED,
REVOKED,
EXPIRED,
PENDING

Response

Consents retrieved successfully

ver
string

The version of the FinPro API that processed this request.

status
string

Overall API call status. Will be 'success' for successful requests.

data
object[]

An array of consent objects matching the query criteria. Each object represents one consent record. The array may be empty if no matching consents exist.