Guides
  1. GETTING STARTED

Your First API Call (Quickstart)

This walkthrough takes you from zero to a newly created cardholder in the sandbox environment. It assumes you've already completed Authentication & Environments — specifically, that you have a sandbox mTLS client certificate, a sandbox program-level API key, and an allowlisted calling IP.

📘

Checklist before you start

Step 1: Confirm connectivity

Start with a read-only call to confirm your certificate, API key, and IP allowlisting are all correctly configured. List the cardholders in your Program — on a brand-new Program, this will be an empty list:

curl --cert /path/to/sandbox-cert.pem \
     --key /path/to/sandbox-key.pem \
     -H "X-API-Key: YOUR_SANDBOX_API_KEY" \
     "https://staging.api.axyscards.com/v2/cardholders"
{
  "status": "success",
  "items": [],
  "total": 0,
  "limit": 50,
  "offset": 0
}

If you receive this response, your authentication setup is correct. If you instead see a TLS error or a 403, work through If authentication fails before continuing.

Step 2: Create your first cardholder

Remember: a Cardholder is always a natural person — see Program Architecture if you're onboarding a corporate client and need to decide who that person is.

curl --cert /path/to/sandbox-cert.pem \
     --key /path/to/sandbox-key.pem \
     -H "X-API-Key: YOUR_SANDBOX_API_KEY" \
     -H "Content-Type: application/json" \
     -X POST "https://staging.api.axyscards.com/v2/cardholders" \
     -d '{
  "firstName": "Jordan",
  "lastName": "Reyes",
  "emailAdr": "[email protected]",
  "gender": 0,
  "nationality": "American",
  "placeOfBirth": "USA",
  "dob": "1990-05-14",
  "adrLine1": "123 Market Street",
  "city": "San Francisco",
  "state": "CA",
  "country": "US",
  "zipCode": "94105",
  "callingCode": "001",
  "cellNum": "4155551234",
  "countryCallingCode": "US",
  "phoneNum": "4155551234"
}'
{
  "status": "success",
  "cardholderId": 10532
}
🚧

Known divergent ISO code standards: placeOfBirth correctly expects an ISO 3166-1 Alpha-3 country code (e.g., USA for the United States), as its description states. By contrast, country and countryCallingCode correctly expect two-letter Alpha-2 codes (e.g., US). See ISO Code Conventions for the full picture.

📘

callingCode formatting: callingCode should always be passed as exactly three digits, zero-padded where the ITU dialing code is shorter than three digits — e.g., 001 for the United States (dialing code 1), 044 for the United Kingdom (44), or 971 for the UAE (already three digits, no padding needed).

A few things worth noting about the fields above:

  • gender is 0 (Male), 1 (Female), or 2 (Other).
  • callingCode/cellNum and countryCallingCode/phoneNum are two separate phone numbers with their dialing codes specified separately — callingCode is a zero-padded, three-digit ITU dialing code (e.g., 001, 044, 971), while countryCallingCode (despite its name) is an Alpha-2 country code.
  • Several of these fields — gender, dob, nationality, placeOfBirth, country, zipCode, adrLine1 — become locked once the cardholder enters compliance review and cannot be changed afterward. Double-check them before submitting to compliance. See Cardholders & the Compliance Lifecycle.

Save the returned cardholderId — you'll need it for every subsequent call related to this cardholder.

Step 3: Retrieve the cardholder

curl --cert /path/to/sandbox-cert.pem \
     --key /path/to/sandbox-key.pem \
     -H "X-API-Key: YOUR_SANDBOX_API_KEY" \
     "https://staging.api.axyscards.com/v2/cardholders/10532"

The cardholder's status will be 4 (Draft) — they've been created but haven't yet been submitted for compliance review, and no cards can be issued to them yet.

What's next

You've created a cardholder in Draft status. From here: