Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt

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

Before you can initiate any transfer, you must create a customer record in SpherePay. This endpoint registers either an individual or a business customer and returns a customer object with a unique ID and a verificationProfiles array that tracks KYC/KYB completion status. You must specify type upfront — it cannot be changed after creation.

​
Endpoint

POST https://api.spherepay.co/v2/customer

​
Authentication

All requests require a Bearer token in the Authorization header. 
Authorization: Bearer <token>

​
Request body

​
Individual customer

​
type
string
required
Customer type. Must be "individual".
​
email
string
required
Customer email address. Maximum 254 characters. Must be a valid email format.
​
phone
string
required
Customer phone number in E.164 format (e.g. +14155550123). Must match ^\+(?:[0-9]){6,14}[0-9]$.
​
address
object
required
The customer’s residential address.
​
personalInformation
object
Personal information including tax identification details. When any tax identification field is provided, all tax identification fields (number, type, country) and address are required. See Individual Verification Criteria for the full reference.
​
meta
object
Optional arbitrary key-value metadata to attach to the customer. Values must be null or a primitive type.

​
Business customer

​
type
string
required
Customer type. Must be "business".
​
email
string
required
Business email address. Maximum 254 characters.
​
phone
string
required
Business phone number in E.164 format.
​
addresses
object[]
required
Array of address objects for the business. Includes a registered address and an operating address.
​
businessInformation
object
required
Business identification and onboarding details. See Business Verification Criteria.
​
meta
object
Optional arbitrary key-value metadata.
curl -X POST "https://api.spherepay.co/v2/customer" \
  -H "Authorization: Bearer $SPHEREPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "email": "jane.smith@example.com",
    "phone": "+14155550123",
    "address": {
      "line1": "233 South Wacker Drive",
      "city": "Chicago",
      "state": "IL",
      "postalCode": "60606",
      "country": "USA"
    },
    "personalInformation": {
      "firstName": "Jane",
      "lastName": "Smith",
      "dateOfBirth": "1990-04-15"
    }
  }'

​
Response fields

​
id
string
Unique customer identifier, prefixed with customer_.
​
type
string
Customer type: individual or business.
​
email
string
Registered email address.
​
phone
string
Registered phone number in E.164 format.
​
firstName
string
First name (individual customers only).
​
lastName
string
Last name (individual customers only).
​
verificationProfiles
object[]
Array of verification profiles tracking KYC/KYB completion status.
​
meta
object
Metadata associated with the customer.
​
createdAt
string
ISO 8601 timestamp of when the customer was created.
​
updatedAt
string
ISO 8601 timestamp of the most recent update.
{
  "id": "customer_f31121c389624d3697cbf3ea8830b7a4",
  "type": "individual",
  "email": "jane.smith@example.com",
  "phone": "+14155550123",
  "firstName": "Jane",
  "lastName": "Smith",
  "verificationProfiles": [
    {
      "name": "kyc_profile_a",
      "status": "incomplete",
      "criteria": {
        "complete": [
          "email_address",
          "phone_number",
          "residential_address",
          "tax_identification_number"
        ],
        "pending": [],
        "required": [
          "identity_document",
          "liveness_report_document"
        ],
        "errors": []
      }
    }
  ],
  "meta": {},
  "createdAt": "2026-03-09T20:46:31.305Z",
  "updatedAt": "2026-03-09T20:46:31.305Z"
}

​
Error codes

StatusCodeDescription
400address/invalidThe address object contains invalid or missing fields.
404resource/not-foundThe referenced resource does not exist.
422validation/failedOne or more fields failed validation. The errors array identifies each failing field.
Last modified on May 12, 2026