Skip to main content
Create a Customer
curl --request POST \
  --url https://api.spherepay.co/v2/customer \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "individual",
  "email": "jane.smith@example.com",
  "phone": "+14155550123",
  "address": {
    "line1": "233 South Wacker Drive",
    "city": "Chicago",
    "country": "USA",
    "line2": "Suite 4700",
    "state": "IL",
    "postalCode": "60606"
  },
  "firstName": "Jane",
  "lastName": "Smith",
  "middleName": "Anne",
  "dateOfBirth": "2026-01-01",
  "meta": {}
}
'
{
  "id": "customer_f31121c389624d3697cbf3ea8830b7a4",
  "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": []
      }
    }
  ],
  "tosStatus": "incomplete",
  "createdAt": "2026-03-09T20:46:31.305Z",
  "updatedAt": "2026-03-09T20:46:31.305Z",
  "type": "individual",
  "email": "jane.smith@example.com",
  "phone": "+14155550123",
  "meta": {},
  "firstName": "Jane",
  "lastName": "Smith",
  "dateOfBirth": "1990-01-15",
  "personalInformation": {
    "taxIdentificationNumberType": "ssn",
    "taxIdentificationNumberCountry": "USA",
    "taxIdentificationNumberDescription": "<string>",
    "gender": "male",
    "countryOfBirth": "USA",
    "nationality": "USA",
    "middleName": "James",
    "occupationSocCode": "15-1132",
    "residencyCountry": "USA",
    "sourceOfFunds": "salary"
  }
}
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.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
type
enum<string>
required
Available options:
individual
​
email
string<email>
required

The customer email address

Maximum string length: 254
Example:

"jane.smith@example.com"

​
phone
string
required

The customer phone number in E.164 format

Pattern: ^\+(?:[0-9]){6,14}[0-9]$
Example:

"+14155550123"

​
address
object
required

The customer's address.

​
firstName
string

The customer's legal first name.

Required string length: 1 - 100
Example:

"Jane"

​
lastName
string

The customer's legal last name.

Required string length: 1 - 100
Example:

"Smith"

​
middleName
string

The customer's legal middle name.

Required string length: 1 - 100
Example:

"Anne"

​
dateOfBirth
string

The date string in YYYY-MM-DD format

Example:

"2026-01-01"

​
personalInformation
object

Personal information including tax identification details for individual customers. When any tax identification field is provided, all tax identification fields (number, type, country) and address are required. Please refer to the Individual Verification Criteria for the full list of reference.

​
meta
object

Additional metadata associated with the customer

Response

Response containing information about an individual customer.

​
id
string
required

Customer ID

Example:

"customer_f31121c389624d3697cbf3ea8830b7a4"

​
verificationProfiles
object[]
required

Array of verification profiles. For individual customers, this will include kyc_profile_a. For business customers, this will include kyb_profile_a. See KYC Flow for individuals or KYB Flow for businesses. See Verification Profile for individual status definitions and criteria breakdown or Verification Profile for business status definitions and criteria breakdown.

Example:
[
  {
    "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": []
    }
  }
]
​
tosStatus
enum<string>
required

Customer Terms of Service acceptance status (incomplete | pending | approved).

Available options:
incomplete,
pending,
approved
Example:

"incomplete"

​
createdAt
string
required

ISO 8601 formatted customer creation timestamp

Example:

"2026-03-09T20:46:31.305Z"

​
updatedAt
string
required

ISO 8601 formatted customer update timestamp

Example:

"2026-03-09T20:46:31.305Z"

​
type
enum<string>
required

Customer type

Available options:
individual
Example:

"individual"

​
email
string

Customer email address

Example:

"jane.smith@example.com"

​
phone
string

Customer phone number

Example:

"+14155550123"

​
meta
object
​
firstName
string

Customer first name (individual customers only)

Example:

"Jane"

​
lastName
string

Customer last name (individual customers only)

Example:

"Smith"

​
dateOfBirth
string

The customer's date of birth in YYYY-MM-DD format (individual customers only).

Example:

"1990-01-15"

​
personalInformation
object

Personal information for an individual customer, echoed back from the most recent submission. The tax identification number is omitted from responses for privacy.

Last modified on June 18, 2026