Skip to main content
POST
/
api
/
v2.1
/
fincard
/
virtual
/
card
/
holder
/
list
Cardholder List
curl --request POST \
  --url https://sandbox.finhub.cloud/api/v2.1/fincard/virtual/card/holder/list \
  --header 'Content-Type: application/json' \
  --header 'X-Forwarded-From: <x-forwarded-from>' \
  --data '
{
  "cardholderId": 123,
  "areaCode": "<string>",
  "mobile": "<string>",
  "email": "<string>",
  "merchantOrderNo": "<string>",
  "pageNum": 1,
  "pageSize": 10,
  "cardholderType": "<string>",
  "cardholderStatus": "<string>",
  "searchTerm": "<string>"
}
'
{
  "success": true,
  "code": 200,
  "msg": "Success",
  "data": {
    "total": 150,
    "pageNum": 1,
    "pageSize": 10,
    "records": [
      {
        "cardholderId": "ch-12345678",
        "accountId": "wsb-12345678",
        "cardholderReference": "REF123456",
        "personalInfo": {
          "firstName": "John",
          "lastName": "Doe",
          "middleName": "William",
          "dateOfBirth": "1990-01-15T00:00:00.000Z",
          "gender": "MALE",
          "nationality": "US",
          "email": "john.doe@example.com",
          "phoneNumber": "+1234567890",
          "mobileNumber": "+1234567890"
        },
        "residentialAddress": {
          "addressLine1": "123 Main St",
          "addressLine2": "Apt 4B",
          "city": "New York",
          "state": "NY",
          "postalCode": "10001",
          "country": "US",
          "addressType": "RESIDENTIAL",
          "isPrimary": true
        },
        "mailingAddress": {
          "addressLine1": "123 Main St",
          "addressLine2": "Apt 4B",
          "city": "New York",
          "state": "NY",
          "postalCode": "10001",
          "country": "US",
          "addressType": "RESIDENTIAL",
          "isPrimary": true
        },
        "employmentInfo": {
          "employerName": "Tech Corp",
          "occupationCode": "001",
          "occupationTitle": "Software Engineer",
          "industry": "TECHNOLOGY",
          "employmentStatus": "FULL_TIME",
          "employmentStartDate": "2020-01-01T00:00:00.000Z",
          "monthlyIncome": 5000,
          "annualIncome": 60000,
          "incomeCurrency": "USD",
          "employerAddress": {
            "addressLine1": "123 Main St",
            "addressLine2": "Apt 4B",
            "city": "New York",
            "state": "NY",
            "postalCode": "10001",
            "country": "US",
            "addressType": "RESIDENTIAL",
            "isPrimary": true
          }
        },
        "kycDocuments": [
          {
            "documentType": "PASSPORT",
            "documentNumber": "AB123456789",
            "documentExpiryDate": "2030-01-15T00:00:00.000Z",
            "documentIssueDate": "2020-01-15T00:00:00.000Z",
            "documentIssuingCountry": "US",
            "documentFrontImageUrl": "https://example.com/doc-front.jpg",
            "documentBackImageUrl": "https://example.com/doc-back.jpg",
            "selfieImageUrl": "https://example.com/selfie.jpg",
            "verificationStatus": "PENDING"
          }
        ],
        "cardholderType": "B2B",
        "riskLevel": "LOW",
        "kycLevel": "STANDARD",
        "sourceOfFunds": "SALARY",
        "purposeOfAccount": "PERSONAL_USE",
        "politicallyExposedPerson": false,
        "sanctionsScreeningRequired": true,
        "cardholderStatus": "ACTIVE",
        "kycStatus": "VERIFIED",
        "verificationTime": 1640995200000,
        "createTime": 1640995200000,
        "updateTime": 1640995200000,
        "numberOfCards": 2,
        "activeCards": 2
      }
    ]
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.finhub.cloud/llms.txt

Use this file to discover all available pages before exploring further.

Headers

​
User-Agent
string

User agent

​
X-Forwarded-For
string

Forwarded for

​
X-Forwarded-From
string
required

Client application identifier

Example:

"client-app"

​
X-Tenant-ID
string

Tenant ID

​
deviceId
string

Device ID

​
platform
string

Platform

Body

application/json

Cardholder list request

Cardholder list request

​
cardholderId
integer<int64>

Cardholder ID (optional filter)

​
areaCode
string

Mobile area code (optional, must be passed with mobile)

​
mobile
string

Mobile phone number (optional)

​
email
string

Email (optional)

​
merchantOrderNo
string

Client transaction reference (optional)

​
pageNum
integer<int32>
default:1

Current page. Default is 1

​
pageSize
integer<int32>
default:10

Page size. Maximum 100, default 10

​
cardholderType
string

Cardholder type filter (optional)

​
cardholderStatus
string

Cardholder status filter (optional)

​
searchTerm
string

Search term (optional)

Response

Successful response

Cardholder list response

​
success
boolean

Success flag

Example:

true

​
code
integer<int32>

Response code

Example:

200

​
msg
string

Response message

Example:

"Success"

​
data
object

Cardholder list data