Create Cardholder

Create a cardholder once, then issue one or more cards to them. Best when you manage many end-customers — each cardholder has their own profile, cards and statement. This is the customer-first (BaaS) flow.

Card endpoints use the same base URL and API key as the rest of the API, and are signature-gated: send X-Numero-Signature and X-Numero-Signature-Version: v2 as well. See Request signing.

Endpoint

POST /api/v1/business/cardholders

Signature required: Yes

Headers

Header	Required	Description
`X-Numero-Api-Key`	Yes	Your API key
`X-Numero-Signature`	Yes	Base64 HMAC-SHA256 over the exact raw request body (POST) or the canonicalised query string (GET), keyed with your Public Key. See Request signing.
`X-Numero-Signature-Version`	Yes	Always `v2`.

Request body

Field	Type	Required	Description
`firstName`	string	Yes	Cardholder first name
`lastName`	string	Yes	Cardholder last name
`email`	string	No	Email
`phone`	string	No	Phone
`dateOfBirth`	string	No	`YYYY-MM-DD`
`address1`	string	No	Street address
`city`	string	No	City
`state`	string	No	State
`zipcode`	string	No	Postal code
`country`	string	No	ISO country code, e.g. `NG`
`idType`	string	No	e.g. `BVN`, `PASSPORT`
`idNumber`	string	No	ID number
`bvn`	string	No	Bank Verification Number
`idDocumentFrontUrl`	string	For new identity evidence	Direct HTTPS JPEG/PNG document image accessible to Numero; not a PDF or asset-management page.
`idDocumentBackUrl`	string	When applicable	Direct HTTPS reverse-side document image.

Provider KYC requirements apply even where a field is nullable in the generic schema. Supply accurate date of birth, contact and residential address details with the ID. See card issuance requirements and safe retries.

Request example

Proof of funds and address

Both inline issuance and cardholder creation also accept:

Field	Type	Description
`gender`	string	Customer’s gender, when required for issuer KYC.
`proofOfAddressDocumentUrl`	string	Direct HTTPS document-image URL; Numero converts it to the issuer’s base64 representation.
`proofOfFunds`	object	Customer-attested answers below; never populate using guessed or example values.

The proof-of-funds object uses camelCase Numero fields: employmentStatus, occupation, primaryPurpose, sourceOfFunds, expectedMonthlyPay. If provided, all five must contain valid documented options. See the machine-readable CardProofOfFunds schema for the complete accepted values. This is a questionnaire, not an extra document-upload URL. Provider KYC readiness is required before issuance; a locally created cardholder is not proof of approval.

curl -X POST "https://api.usenumero.com/numeroaccount/api/v1/business/cardholders" \
  -H "X-Numero-Api-Key: your_api_key" \
  -H "X-Numero-Signature: $SIGNATURE" \
  -H "X-Numero-Signature-Version: v2" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Ada",
    "lastName": "Obi",
    "email": "[email protected]",
    "country": "NG",
    "bvn": "22222222222"
  }'

Response

{
  "data": {
    "customerId": "NCUS9953596C2B7F45",
    "firstName": "Ada",
    "lastName": "Obi",
    "email": "[email protected]",
    "phone": "08012345678",
    "country": "NG",
    "status": "Active",
    "activeCardCount": 1,
    "createdAt": "2026-06-16T12:00:00Z"
  },
  "error": null,
  "meta": {
    "request_id": "req_365123ebc73323f1482508560ce6400e",
    "pagination": null
  }
}

Getting Started

Transfers & Payouts

Collections (Virtual Accounts)

Wallet-as-a-Service

Customers

Invoices

Cards

Cardholders

Balance & Transactions

Value Added Services

Credit

Verification / KYC

Webhooks

Create Cardholder

Endpoint

Headers

Request body

Request example

Proof of funds and address

Response

​Endpoint

​Headers

​Request body

​Request example

​Proof of funds and address

​Response

Endpoint

Headers

Request body

Request example

Proof of funds and address

Response