​
Overview

The Customers API enables you to create and manage customer profiles for your integration. Each customer object includes personal information, contact details, and billing information that can be referenced in future transactions.

​
Create a Customer

POST /customers

Create a new customer profile with the specified information. Each customer must have a unique email address within your integration.

Ensure phone numbers match the billing address country format. For example, Nigerian phone numbers (+234) should have a Nigerian billing address.

​
Request Parameters

​
first_name
string
required

Customer’s first name.

  • Maximum length: 100 characters

  • Must contain only letters, spaces, hyphens, and apostrophes

​
last_name
string
required

Customer’s last name.

  • Maximum length: 100 characters

  • Must contain only letters, spaces, hyphens, and apostrophes

​
email
string
required

Customer’s email address.

  • Must be a valid email format

  • Must be unique within your integration

​
phone_number
string
required

Customer’s phone number in E.164 format.

  • Must include country code

  • Must be a valid number for the billing address country

  • Example: +2348012345678

​
billing_address
object
required

Customer’s billing address information.

​
Code Examples

curl -X POST "https://api.spendjuice.com/customers" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone_number": "+2348012345678",
  "billing_address": {
    "line1": "123 Test Lane",
    "line2": "Suite 456",
    "city": "Lagos",
    "state": "Lagos",
    "zip_code": "100001",
    "country": "NG"
  }
}'

​
Response

{
  "data": {
    "id": "6f7e1e7f-93d1-4fcc-b7a4-738f869615c8",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_number": "+2348012345678",
    "billing_address": {
      "line1": "123 Test Lane",
      "line2": "Suite 456",
      "city": "Lagos",
      "state": "Lagos",
      "zip_code": "100001",
      "country": "NG"
    }
  }
}

​
Rate Limits

EnvironmentRequests per minute
Test100
Production1000

Exceeding these limits will return a 429 Too Many Requests response.

​
Idempotency

All POST requests support idempotency to prevent duplicate customer creation. Include an Idempotency-Key header with a unique value for each request:

Idempotency-Key: a123b456-c789-d012-e345-f67890123456

The same key will return the original response for duplicate requests within 24 hours.

​
Best Practices

  1. Validation

    • Validate email formats before sending

    • Ensure phone numbers match country codes

    • Use proper character encoding for names

  2. Error Handling

    • Implement retry logic with exponential backoff

    • Handle validation errors gracefully

    • Check for duplicate customers before creation

  3. Security

    • Use HTTPS for all API calls

    • Keep API keys secure

    • Implement proper access controls

Need help?

For support with customer creation: