Query 3DS Contact Details

Overview

Use this endpoint to query the 3D Secure contact details of cardholders. You can retrieve comprehensive information including mobile phone number, email address, date of birth, address, country, and security questions. Filter results by budget_id or cardholder_id to find specific cardholder records.

NOTE: This API is offered on a client-by-client approval basis. Speak to your account manager to check eligibility.

Resource Access

Production (api.ahrvo.network)

GET https://api.ahrvo.network/card/issuance/api/issuing/cardholders/v2/detail

Staging (gateway.ahrvo.network)

GET https://gateway.ahrvo.network/card/issuance/api/issuing/cardholders/v2/detail

---

Request Headers

Header	Value	Required	Description
Accept	application/json	Yes	Content type for the response
Authorization	Bearer {access_token}	Yes	Bearer token for authentication
x-api-key	API Key	Yes	API key for authentication

Query Parameters

Parameter	Type	Required	Description
page_no	integer	No	Starting page number, starts from 1 (default: 1)
page_size	integer	No	Number of results per page (default: 20)
budget_id	string	No	ID of the budget account the cardholder associates with
cardholder_id	string	No	A unique ID of the cardholder

Query Notes

• At least one of budget_id or cardholder_id should be provided for filtering
• If both are provided, the API will return cardholders matching both criteria
• Use pagination parameters (page_no, page_size) to handle large result sets

Response

Success Response (200 OK)

{
  "code": "SUCCESS",
  "data": {
    "total": 1,
    "list": [
      {
        "cardholder_id": "471041678120300545",
        "budget_id": "ci202210231533401801",
        "first_name": "Emma",
        "last_name": "Johnson",
        "email": "emma.johnson@example.com",
        "call_prefix": "+1",
        "mobile": "2125551234",
        "date_of_birth": "1996-10-31",
        "country": "United States",
        "country_code": "US",
        "state": "Illinois",
        "city": "Chicago",
        "address_line": "456 Maple Avenue",
        "post_code": "60601",
        "security_index": "2",
        "security_question": "What is your maternal grandmother's maiden name?",
        "security_answer": "Han"
      }
    ]
  }
}

Response Fields

Field	Type	Description
code	string	Status string indicating the result. "SUCCESS" refers to a successful query
data	object	Response data object
data.total	integer	Total number of cardholders meeting the query conditions
data.list	array	List of cardholder details

Cardholder Object Fields

Field	Type	Description
cardholder_id	string	A unique ID of the cardholder
budget_id	string	ID of the budget account this cardholder associates with
first_name	string	First name of the cardholder
last_name	string	Last name of the cardholder
email	string	Email of the cardholder
call_prefix	string	Country code of the mobile number (e.g., +1, +44)
mobile	string	Mobile number of the cardholder, without country code
date_of_birth	string	Date of birth of the cardholder (YYYY-MM-DD)
country	string	Full country name of the cardholder
country_code	string	Country in ISO 3166 format (e.g., US)
state	string	State of the cardholder
city	string	City of the cardholder
address_line	string	Address of the cardholder
post_code	string	Post code of the cardholder
security_index	string	Index of security question (1-5)
security_question	string	The full text of the security question
security_answer	string	Answer to the security question

Security Questions Reference

Index	Security Question
1	What was your first pet's name?
2	What is your maternal grandmother's maiden name?
3	What is the name of your favourite childhood friend?
4	What was the make of your first car?
5	In what city or town did your mother and father meet?

Error Responses

• 400 Bad Request: Invalid query parameters
• 401 Unauthorized: Invalid or missing authentication token
• 403 Forbidden: 3DS feature not enabled for this account
• 404 Not Found: No cardholders match the query criteria

Code Examples

cURL

# Query by cardholder_id
curl -X GET \
  'https://gateway.ahrvo.network/card/issuance/api/issuing/cardholders/v2/detail?cardholder_id=471041678120300545' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-api-key: YOUR_API_KEY'

# Query by budget_id with pagination
curl -X GET \
  'https://gateway.ahrvo.network/card/issuance/api/issuing/cardholders/v2/detail?budget_id=ci202210231533401801&page_no=1&page_size=20' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-api-key: YOUR_API_KEY'

Python

import requests

url = "https://gateway.ahrvo.network/card/issuance/api/issuing/cardholders/v2/detail"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "x-api-key": "YOUR_API_KEY"
}

# Query by cardholder_id
params = {
    "cardholder_id": "471041678120300545"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

# Query by budget_id with pagination
params = {
    "budget_id": "ci202210231533401801",
    "page_no": 1,
    "page_size": 20
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

JavaScript (Node.js)

const axios = require('axios');

const url = 'https://gateway.ahrvo.network/card/issuance/api/issuing/cardholders/v2/detail';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
  'x-api-key': 'YOUR_API_KEY'
};

// Query by cardholder_id
const params1 = {
  cardholder_id: '471041678120300545'
};

axios.get(url, { headers, params: params1 })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error.response.data);
  });

// Query by budget_id with pagination
const params2 = {
  budget_id: 'ci202210231533401801',
  page_no: 1,
  page_size: 20
};

axios.get(url, { headers, params: params2 })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error.response.data);
  });

Usage Notes

• Privacy Consideration: This endpoint returns sensitive personal information including security answers. Ensure proper access controls
• Pagination: Use pagination for accounts with multiple cardholders to avoid performance issues
• Query Optimization: Use cardholder_id for faster queries when you know the specific cardholder
• Security Answers: The security answers are returned in plain text, handle with appropriate security measures
• Data Verification: Use this endpoint to verify cardholder information before updating or enrolling cards

Common Use Cases

Verify Cardholder Before Enrollment

Before enrolling a card for 3DS, verify the cardholder exists:

// Check if cardholder exists
const response = await queryCardholder(cardholder_id);
if (response.data.total > 0) {
  // Proceed with enrollment
  await enrollCard(card_id, cardholder_id);
}

List All Cardholders for a Budget

Retrieve all cardholders associated with a specific budget account:

page = 1
all_cardholders = []
while True:
    response = query_cardholders(budget_id=budget_id, page_no=page)
    all_cardholders.extend(response['data']['list'])
    if len(all_cardholders) >= response['data']['total']:
        break
    page += 1

Audit Cardholder Information

Regularly audit cardholder records for compliance:

const cardholders = await queryAllCardholders();
cardholders.forEach(cardholder => {
  // Validate email format
  // Check address completeness
  // Verify security questions are answered
});

Customer Support Lookup

Quickly retrieve cardholder information for customer support:

# Search by cardholder ID from support ticket
cardholder = query_cardholder(cardholder_id=ticket_cardholder_id)
if cardholder['data']['total'] > 0:
    details = cardholder['data']['list'][0]
    print(f"Name: {details['first_name']} {details['last_name']}")
    print(f"Email: {details['email']}")
    print(f"Mobile: {details['call_prefix']}{details['mobile']}")

Best Practices

• Secure Data Handling: Implement proper security measures when storing or displaying returned data
• Rate Limiting: Implement rate limiting to avoid overwhelming the API with repeated queries
• Error Handling: Always check the response code and handle errors appropriately
• Data Caching: Cache cardholder data temporarily to reduce API calls for frequently accessed records
• Access Logging: Log all queries to this endpoint for security audit purposes
• Pagination Strategy: Start with reasonable page sizes (20-50) and adjust based on your needs

Related Endpoints

• Create Cardholder 3DS Contact - Create new cardholder profiles
• Update Cardholder Contact - Update existing cardholder information
• Enroll Card for 3DS - Link cardholder to a card for 3DS authentication
• Delete Cardholder - Remove cardholder records

Troubleshooting

Empty Results (total: 0)

• Verify the budget_id or cardholder_id is correct
• Check that the cardholder was successfully created
• Ensure the cardholder belongs to your account

Pagination Issues

• Ensure page_no starts from 1, not 0
• Check that page_size is a reasonable number (1-100)
• Verify you're not requesting a page beyond the available results

Missing Fields in Response

• Some fields may be null if not provided during cardholder creation
• Validate all required fields were submitted when creating the cardholder

Forbidden Access (403)

• Verify 3DS feature is enabled for your account
• Contact your account manager to enable this feature
• Check that your API credentials have the necessary permissions

Interactive API Explorer