Create a cardholder

curl --request POST \
  --url https://api.usenumero.com/numeroaccount/api/v1/business/cardholders \
  --header 'Content-Type: application/json' \
  --header 'X-Numero-Api-Key: <api-key>' \
  --header 'X-Numero-Signature: <api-key>' \
  --data '
{
  "firstName": "<string>",
  "lastName": "<string>",
  "email": "<string>",
  "phone": "<string>",
  "dateOfBirth": "2023-12-25",
  "address1": "<string>",
  "city": "<string>",
  "state": "<string>",
  "zipcode": "<string>",
  "country": "NG",
  "idType": "PASSPORT",
  "idNumber": "<string>",
  "bvn": "<string>",
  "idDocumentFrontUrl": "<string>",
  "idDocumentBackUrl": "<string>",
  "gender": "<string>",
  "proofOfAddressDocumentUrl": "<string>"
}
'

import requests

url = "https://api.usenumero.com/numeroaccount/api/v1/business/cardholders"

payload = {
    "firstName": "<string>",
    "lastName": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "dateOfBirth": "2023-12-25",
    "address1": "<string>",
    "city": "<string>",
    "state": "<string>",
    "zipcode": "<string>",
    "country": "NG",
    "idType": "PASSPORT",
    "idNumber": "<string>",
    "bvn": "<string>",
    "idDocumentFrontUrl": "<string>",
    "idDocumentBackUrl": "<string>",
    "gender": "<string>",
    "proofOfAddressDocumentUrl": "<string>"
}
headers = {
    "X-Numero-Api-Key": "<api-key>",
    "X-Numero-Signature": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Numero-Api-Key': '<api-key>',
    'X-Numero-Signature': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    firstName: '<string>',
    lastName: '<string>',
    email: '<string>',
    phone: '<string>',
    dateOfBirth: '2023-12-25',
    address1: '<string>',
    city: '<string>',
    state: '<string>',
    zipcode: '<string>',
    country: 'NG',
    idType: 'PASSPORT',
    idNumber: '<string>',
    bvn: '<string>',
    idDocumentFrontUrl: '<string>',
    idDocumentBackUrl: '<string>',
    gender: '<string>',
    proofOfAddressDocumentUrl: '<string>'
  })
};

fetch('https://api.usenumero.com/numeroaccount/api/v1/business/cardholders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usenumero.com/numeroaccount/api/v1/business/cardholders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'firstName' => '<string>',
    'lastName' => '<string>',
    'email' => '<string>',
    'phone' => '<string>',
    'dateOfBirth' => '2023-12-25',
    'address1' => '<string>',
    'city' => '<string>',
    'state' => '<string>',
    'zipcode' => '<string>',
    'country' => 'NG',
    'idType' => 'PASSPORT',
    'idNumber' => '<string>',
    'bvn' => '<string>',
    'idDocumentFrontUrl' => '<string>',
    'idDocumentBackUrl' => '<string>',
    'gender' => '<string>',
    'proofOfAddressDocumentUrl' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Numero-Api-Key: <api-key>",
    "X-Numero-Signature: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usenumero.com/numeroaccount/api/v1/business/cardholders"

	payload := strings.NewReader("{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"dateOfBirth\": \"2023-12-25\",\n  \"address1\": \"<string>\",\n  \"city\": \"<string>\",\n  \"state\": \"<string>\",\n  \"zipcode\": \"<string>\",\n  \"country\": \"NG\",\n  \"idType\": \"PASSPORT\",\n  \"idNumber\": \"<string>\",\n  \"bvn\": \"<string>\",\n  \"idDocumentFrontUrl\": \"<string>\",\n  \"idDocumentBackUrl\": \"<string>\",\n  \"gender\": \"<string>\",\n  \"proofOfAddressDocumentUrl\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Numero-Api-Key", "<api-key>")
	req.Header.Add("X-Numero-Signature", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.usenumero.com/numeroaccount/api/v1/business/cardholders")
  .header("X-Numero-Api-Key", "<api-key>")
  .header("X-Numero-Signature", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"dateOfBirth\": \"2023-12-25\",\n  \"address1\": \"<string>\",\n  \"city\": \"<string>\",\n  \"state\": \"<string>\",\n  \"zipcode\": \"<string>\",\n  \"country\": \"NG\",\n  \"idType\": \"PASSPORT\",\n  \"idNumber\": \"<string>\",\n  \"bvn\": \"<string>\",\n  \"idDocumentFrontUrl\": \"<string>\",\n  \"idDocumentBackUrl\": \"<string>\",\n  \"gender\": \"<string>\",\n  \"proofOfAddressDocumentUrl\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usenumero.com/numeroaccount/api/v1/business/cardholders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Numero-Api-Key"] = '<api-key>'
request["X-Numero-Signature"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"dateOfBirth\": \"2023-12-25\",\n  \"address1\": \"<string>\",\n  \"city\": \"<string>\",\n  \"state\": \"<string>\",\n  \"zipcode\": \"<string>\",\n  \"country\": \"NG\",\n  \"idType\": \"PASSPORT\",\n  \"idNumber\": \"<string>\",\n  \"bvn\": \"<string>\",\n  \"idDocumentFrontUrl\": \"<string>\",\n  \"idDocumentBackUrl\": \"<string>\",\n  \"gender\": \"<string>\",\n  \"proofOfAddressDocumentUrl\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "customerId": "NCUS9953596C2B7F45",
    "firstName": "<string>",
    "lastName": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "country": "<string>",
    "status": "<string>",
    "activeCardCount": 123,
    "createdAt": "2023-11-07T05:31:56Z"
  },
  "error": {
    "code": "missing_field",
    "message": "<string>",
    "param": "<string>"
  },
  "meta": {
    "request_id": "<string>",
    "pagination": {
      "page": 123,
      "page_size": 123,
      "total": 123,
      "has_more": true
    }
  }
}

POST

business

cardholders

Create a cardholder

curl --request POST \
  --url https://api.usenumero.com/numeroaccount/api/v1/business/cardholders \
  --header 'Content-Type: application/json' \
  --header 'X-Numero-Api-Key: <api-key>' \
  --header 'X-Numero-Signature: <api-key>' \
  --data '
{
  "firstName": "<string>",
  "lastName": "<string>",
  "email": "<string>",
  "phone": "<string>",
  "dateOfBirth": "2023-12-25",
  "address1": "<string>",
  "city": "<string>",
  "state": "<string>",
  "zipcode": "<string>",
  "country": "NG",
  "idType": "PASSPORT",
  "idNumber": "<string>",
  "bvn": "<string>",
  "idDocumentFrontUrl": "<string>",
  "idDocumentBackUrl": "<string>",
  "gender": "<string>",
  "proofOfAddressDocumentUrl": "<string>"
}
'

import requests

url = "https://api.usenumero.com/numeroaccount/api/v1/business/cardholders"

payload = {
    "firstName": "<string>",
    "lastName": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "dateOfBirth": "2023-12-25",
    "address1": "<string>",
    "city": "<string>",
    "state": "<string>",
    "zipcode": "<string>",
    "country": "NG",
    "idType": "PASSPORT",
    "idNumber": "<string>",
    "bvn": "<string>",
    "idDocumentFrontUrl": "<string>",
    "idDocumentBackUrl": "<string>",
    "gender": "<string>",
    "proofOfAddressDocumentUrl": "<string>"
}
headers = {
    "X-Numero-Api-Key": "<api-key>",
    "X-Numero-Signature": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Numero-Api-Key': '<api-key>',
    'X-Numero-Signature': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    firstName: '<string>',
    lastName: '<string>',
    email: '<string>',
    phone: '<string>',
    dateOfBirth: '2023-12-25',
    address1: '<string>',
    city: '<string>',
    state: '<string>',
    zipcode: '<string>',
    country: 'NG',
    idType: 'PASSPORT',
    idNumber: '<string>',
    bvn: '<string>',
    idDocumentFrontUrl: '<string>',
    idDocumentBackUrl: '<string>',
    gender: '<string>',
    proofOfAddressDocumentUrl: '<string>'
  })
};

fetch('https://api.usenumero.com/numeroaccount/api/v1/business/cardholders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usenumero.com/numeroaccount/api/v1/business/cardholders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'firstName' => '<string>',
    'lastName' => '<string>',
    'email' => '<string>',
    'phone' => '<string>',
    'dateOfBirth' => '2023-12-25',
    'address1' => '<string>',
    'city' => '<string>',
    'state' => '<string>',
    'zipcode' => '<string>',
    'country' => 'NG',
    'idType' => 'PASSPORT',
    'idNumber' => '<string>',
    'bvn' => '<string>',
    'idDocumentFrontUrl' => '<string>',
    'idDocumentBackUrl' => '<string>',
    'gender' => '<string>',
    'proofOfAddressDocumentUrl' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Numero-Api-Key: <api-key>",
    "X-Numero-Signature: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usenumero.com/numeroaccount/api/v1/business/cardholders"

	payload := strings.NewReader("{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"dateOfBirth\": \"2023-12-25\",\n  \"address1\": \"<string>\",\n  \"city\": \"<string>\",\n  \"state\": \"<string>\",\n  \"zipcode\": \"<string>\",\n  \"country\": \"NG\",\n  \"idType\": \"PASSPORT\",\n  \"idNumber\": \"<string>\",\n  \"bvn\": \"<string>\",\n  \"idDocumentFrontUrl\": \"<string>\",\n  \"idDocumentBackUrl\": \"<string>\",\n  \"gender\": \"<string>\",\n  \"proofOfAddressDocumentUrl\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Numero-Api-Key", "<api-key>")
	req.Header.Add("X-Numero-Signature", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.usenumero.com/numeroaccount/api/v1/business/cardholders")
  .header("X-Numero-Api-Key", "<api-key>")
  .header("X-Numero-Signature", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"dateOfBirth\": \"2023-12-25\",\n  \"address1\": \"<string>\",\n  \"city\": \"<string>\",\n  \"state\": \"<string>\",\n  \"zipcode\": \"<string>\",\n  \"country\": \"NG\",\n  \"idType\": \"PASSPORT\",\n  \"idNumber\": \"<string>\",\n  \"bvn\": \"<string>\",\n  \"idDocumentFrontUrl\": \"<string>\",\n  \"idDocumentBackUrl\": \"<string>\",\n  \"gender\": \"<string>\",\n  \"proofOfAddressDocumentUrl\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usenumero.com/numeroaccount/api/v1/business/cardholders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Numero-Api-Key"] = '<api-key>'
request["X-Numero-Signature"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"dateOfBirth\": \"2023-12-25\",\n  \"address1\": \"<string>\",\n  \"city\": \"<string>\",\n  \"state\": \"<string>\",\n  \"zipcode\": \"<string>\",\n  \"country\": \"NG\",\n  \"idType\": \"PASSPORT\",\n  \"idNumber\": \"<string>\",\n  \"bvn\": \"<string>\",\n  \"idDocumentFrontUrl\": \"<string>\",\n  \"idDocumentBackUrl\": \"<string>\",\n  \"gender\": \"<string>\",\n  \"proofOfAddressDocumentUrl\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "customerId": "NCUS9953596C2B7F45",
    "firstName": "<string>",
    "lastName": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "country": "<string>",
    "status": "<string>",
    "activeCardCount": 123,
    "createdAt": "2023-11-07T05:31:56Z"
  },
  "error": {
    "code": "missing_field",
    "message": "<string>",
    "param": "<string>"
  },
  "meta": {
    "request_id": "<string>",
    "pagination": {
      "page": 123,
      "page_size": 123,
      "total": 123,
      "has_more": true
    }
  }
}

Authorizations

X-Numero-Api-Key

string

header

required

Your business API key (live_key_...). Issued on approval; managed in Dashboard → Settings → Developer.

X-Numero-Signature

string

header

required

Base64(HMAC-SHA256(publicApiKey, input)) over the raw request body (POST) or canonicalized query string (signed GET). Also send X-Numero-Signature-Version: v2. Required on money-movement / state-changing endpoints (marked 🔒).

The HMAC key is your Public Key as raw UTF-8 bytes — a SECRET despite the name, and a different value from the X-Numero-Api-Key authentication header. Signing with the API key will never produce a valid signature.

Body

application/json

firstName

string

required

lastName

string

required

string | null

phone

string | null

dateOfBirth

string<date> | null

address1

string | null

city

string | null

state

string | null

zipcode

string | null

country

string | null

Example:

"NG"

idType

string | null

Example:

"PASSPORT"

idNumber

string | null

bvn

string | null

idDocumentFrontUrl

string<uri> | null

Direct HTTPS JPEG/PNG identity-document image for issuer KYC; not a PDF or management page.

idDocumentBackUrl

string<uri> | null

Reverse-side document image, when applicable.

gender

string | null

proofOfAddressDocumentUrl

string<uri> | null

proofOfFunds

object

Customer-attested answers. Do not invent answers or substitute example values.

Show child attributes

Response

Cardholder

Canonical response envelope for the public surface. data on success, error on failure.

data

object

required

Endpoint payload on success (object or array); null on failure.

Show child attributes

error

object | null

required

Show child attributes

Utilities

Balance

Cards

Cardholders

Transfers

Virtual Accounts

Airtime

Data

Electricity

Cable TV

Betting

Verification

Credit

Customers

Invoices

Sandbox

Customer Wallets

API Reference

Create a cardholder

Authorizations

Body

Response