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
      }
    ]
  }
}

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