Skip to main content
POST
/
api
/
v1
/
customers
Create Customer Account
curl --request POST \
  --url https://api-production.fossapay.com/api/v1/customers \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "firstName": "<string>",
  "lastName": "<string>",
  "middleName": "<string>",
  "emailAddress": "<string>",
  "mobileNumber": "<string>",
  "dob": "<string>",
  "address": "<string>",
  "city": "<string>",
  "country": "<string>",
  "type": "<string>"
}
'
{
  "status": "success",
  "statusCode": 201,
  "message": "Customer created successfully",
  "data": {
    "id": "ch2eda1f-e2a3-47ac-b8de-3149a3fb7esf",
    "firstName": "John",
    "lastName": "Henry",
    "middleName": "Doe",
    "emailAddress": "john.doe@gmail.com",
    "mobileNumber": "09184728251",
    "dob": "1991-08-15",
    "address": "12 customer rd.",
    "customerType": "individual",
    "businessId": "x93f9867-e4b3-24da-9d1e-aax032bf7a3a",
    "createdAt": "2026-01-08T21:39:52+01:00"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.fossapay.com/llms.txt

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

​
Request

​
x-api-key
string
required
Your API key for authentication
​
firstName
string
required
First name of the customer
​
lastName
string
required
Last name of the customer
​
middleName
string
Middle name of the customer
​
emailAddress
string
required
Email address of the customer
​
mobileNumber
string
required
Mobile number of the customer
​
dob
string
required
Date of birth in YYYY-MM-DD format (e.g., 1990-08-15)
​
address
string
required
Address of the customer
​
city
string
required
City of the customer
​
country
string
required
Country of the customer
​
type
string
required
Customer Account type

​
Request Example

curl -X POST https://api-production.fossapay.com/api/v1/customers \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "Michael",
    "emailAddress": "john.doe@example.com",
    "mobileNumber": "+2348012345678",
    "dob": "1990-08-15",
    "address": "123 Main Street",
    "city": "Lagos",
    "country": "Nigeria",
    "type": "individual"
  }'

const response = await fetch('https://api-production.fossapay.com/api/v1/customers', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    firstName: 'John',
    lastName: 'Doe',
    middleName: 'Michael',
    emailAddress: 'john.doe@example.com',
    mobileNumber: '+2348012345678',
    dob: '1990-08-15',
    address: '123 Main Street',
    city: 'Lagos',
    country: 'Nigeria',
    type: 'individual'
  })
});

const customer = await response.json();
console.log(customer);

import requests

headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    'firstName': 'John',
    'lastName': 'Doe',
    'middleName': 'Michael',
    'emailAddress': 'john.doe@example.com',
    'mobileNumber': '+2348012345678',
    'dob': '1990-08-15',
    'address': '123 Main Street',
    'city': 'Lagos',
    'country': 'Nigeria',
    'type': 'individual'
}

response = requests.post('https://api-production.fossapay.com/api/v1/customers', headers=headers, json=data)
customer = response.json()
print(customer)

​
Response

​
status
string
Response status: success or error
​
statusCode
number
HTTP status code (201 for successful creation)
​
message
string
Human-readable response message
​
data
object

​
Response Example

{
  "status": "success",
  "statusCode": 201,
  "message": "Customer created successfully",
  "data": {
    "id": "ch2eda1f-e2a3-47ac-b8de-3149a3fb7esf",
    "firstName": "John",
    "lastName": "Henry",
    "middleName": "Doe",
    "emailAddress": "john.doe@gmail.com",
    "mobileNumber": "09184728251",
    "dob": "1991-08-15",
    "address": "12 customer rd.",
    "customerType": "individual",
    "businessId": "x93f9867-e4b3-24da-9d1e-aax032bf7a3a",
    "createdAt": "2026-01-08T21:39:52+01:00"
  }
}

​
Error Codes

CodeDescription
INVALID_EMAILEmail address is invalid
INVALID_PHONEPhone number is invalid
INVALID_DOBDate of birth format is invalid
MISSING_REQUIRED_FIELDRequired field is missing
INVALID_CUSTOMER_TYPECustomer type is invalid
Rate Limit: 100 requests per minute
Store the customer_id in your database for future reference and customer management.