Create an Individual or Business Customer

Create a Customer

curl --request POST \
  --url https://api.spherepay.co/v2/customer \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "address": {
    "city": "Chicago",
    "country": "USA",
    "line1": "233 South Wacker Drive",
    "line2": "Suite 4700",
    "postalCode": "60606",
    "state": "IL"
  },
  "email": "jane.smith@example.com",
  "phone": "+14155550123",
  "type": "individual",
  "dateOfBirth": "2026-01-01",
  "firstName": "Jane",
  "lastName": "Smith",
  "meta": {},
  "middleName": "Anne"
}
'

import requests

url = "https://api.spherepay.co/v2/customer"

payload = {
    "address": {
        "city": "Chicago",
        "country": "USA",
        "line1": "233 South Wacker Drive",
        "line2": "Suite 4700",
        "postalCode": "60606",
        "state": "IL"
    },
    "email": "jane.smith@example.com",
    "phone": "+14155550123",
    "type": "individual",
    "dateOfBirth": "2026-01-01",
    "firstName": "Jane",
    "lastName": "Smith",
    "meta": {},
    "middleName": "Anne"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    address: {
      city: 'Chicago',
      country: 'USA',
      line1: '233 South Wacker Drive',
      line2: 'Suite 4700',
      postalCode: '60606',
      state: 'IL'
    },
    email: 'jane.smith@example.com',
    phone: '+14155550123',
    type: 'individual',
    dateOfBirth: '2026-01-01',
    firstName: 'Jane',
    lastName: 'Smith',
    meta: {},
    middleName: 'Anne'
  })
};

fetch('https://api.spherepay.co/v2/customer', 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.spherepay.co/v2/customer",
  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([
    'address' => [
        'city' => 'Chicago',
        'country' => 'USA',
        'line1' => '233 South Wacker Drive',
        'line2' => 'Suite 4700',
        'postalCode' => '60606',
        'state' => 'IL'
    ],
    'email' => 'jane.smith@example.com',
    'phone' => '+14155550123',
    'type' => 'individual',
    'dateOfBirth' => '2026-01-01',
    'firstName' => 'Jane',
    'lastName' => 'Smith',
    'meta' => [
        
    ],
    'middleName' => 'Anne'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.spherepay.co/v2/customer"

	payload := strings.NewReader("{\n  \"address\": {\n    \"city\": \"Chicago\",\n    \"country\": \"USA\",\n    \"line1\": \"233 South Wacker Drive\",\n    \"line2\": \"Suite 4700\",\n    \"postalCode\": \"60606\",\n    \"state\": \"IL\"\n  },\n  \"email\": \"jane.smith@example.com\",\n  \"phone\": \"+14155550123\",\n  \"type\": \"individual\",\n  \"dateOfBirth\": \"2026-01-01\",\n  \"firstName\": \"Jane\",\n  \"lastName\": \"Smith\",\n  \"meta\": {},\n  \"middleName\": \"Anne\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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.spherepay.co/v2/customer")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"address\": {\n    \"city\": \"Chicago\",\n    \"country\": \"USA\",\n    \"line1\": \"233 South Wacker Drive\",\n    \"line2\": \"Suite 4700\",\n    \"postalCode\": \"60606\",\n    \"state\": \"IL\"\n  },\n  \"email\": \"jane.smith@example.com\",\n  \"phone\": \"+14155550123\",\n  \"type\": \"individual\",\n  \"dateOfBirth\": \"2026-01-01\",\n  \"firstName\": \"Jane\",\n  \"lastName\": \"Smith\",\n  \"meta\": {},\n  \"middleName\": \"Anne\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.spherepay.co/v2/customer")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"address\": {\n    \"city\": \"Chicago\",\n    \"country\": \"USA\",\n    \"line1\": \"233 South Wacker Drive\",\n    \"line2\": \"Suite 4700\",\n    \"postalCode\": \"60606\",\n    \"state\": \"IL\"\n  },\n  \"email\": \"jane.smith@example.com\",\n  \"phone\": \"+14155550123\",\n  \"type\": \"individual\",\n  \"dateOfBirth\": \"2026-01-01\",\n  \"firstName\": \"Jane\",\n  \"lastName\": \"Smith\",\n  \"meta\": {},\n  \"middleName\": \"Anne\"\n}"

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

{
  "createdAt": "2026-03-09T20:46:31.305Z",
  "id": "customer_f31121c389624d3697cbf3ea8830b7a4",
  "tosStatus": "incomplete",
  "type": "individual",
  "updatedAt": "2026-03-09T20:46:31.305Z",
  "verificationProfiles": [
    {
      "criteria": {
        "complete": [
          "email_address",
          "phone_number",
          "residential_address",
          "tax_identification_number"
        ],
        "errors": [],
        "pending": [],
        "required": [
          "identity_document",
          "liveness_report_document"
        ]
      },
      "name": "kyc_profile_a",
      "status": "incomplete"
    }
  ],
  "dateOfBirth": "1990-01-15",
  "email": "jane.smith@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "meta": {},
  "personalInformation": {
    "accountPurpose": "<string>",
    "accountPurposeDescription": "<string>",
    "actingAsIntermediary": false,
    "countryOfBirth": "USA",
    "employmentStatus": "<string>",
    "expectedMonthlyPayments": "<string>",
    "gender": "<string>",
    "middleName": "James",
    "nationality": "USA",
    "occupationSocCode": "151252",
    "residencyCountry": "USA",
    "sourceOfFunds": "<string>",
    "taxIdentificationNumberCountry": "USA",
    "taxIdentificationNumberDescription": "<string>",
    "taxIdentificationNumberType": "ssn"
  },
  "phone": "+14155550123"
}

{
  "code": "address/invalid",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "Invalid request parameters",
  "status": 400
}

{
  "code": "resource/not-found",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "Resource not found",
  "status": 404
}

{
  "code": "validation/failed",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "Validation failed",
  "errors": [
    {
      "detail": "Invalid email format",
      "pointer": "/email"
    },
    {
      "detail": "Name is required",
      "pointer": "/name"
    }
  ],
  "status": 422
}

Create a Customer

curl --request POST \
  --url https://api.spherepay.co/v2/customer \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "address": {
    "city": "Chicago",
    "country": "USA",
    "line1": "233 South Wacker Drive",
    "line2": "Suite 4700",
    "postalCode": "60606",
    "state": "IL"
  },
  "email": "jane.smith@example.com",
  "phone": "+14155550123",
  "type": "individual",
  "dateOfBirth": "2026-01-01",
  "firstName": "Jane",
  "lastName": "Smith",
  "meta": {},
  "middleName": "Anne"
}
'

import requests

url = "https://api.spherepay.co/v2/customer"

payload = {
    "address": {
        "city": "Chicago",
        "country": "USA",
        "line1": "233 South Wacker Drive",
        "line2": "Suite 4700",
        "postalCode": "60606",
        "state": "IL"
    },
    "email": "jane.smith@example.com",
    "phone": "+14155550123",
    "type": "individual",
    "dateOfBirth": "2026-01-01",
    "firstName": "Jane",
    "lastName": "Smith",
    "meta": {},
    "middleName": "Anne"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    address: {
      city: 'Chicago',
      country: 'USA',
      line1: '233 South Wacker Drive',
      line2: 'Suite 4700',
      postalCode: '60606',
      state: 'IL'
    },
    email: 'jane.smith@example.com',
    phone: '+14155550123',
    type: 'individual',
    dateOfBirth: '2026-01-01',
    firstName: 'Jane',
    lastName: 'Smith',
    meta: {},
    middleName: 'Anne'
  })
};

fetch('https://api.spherepay.co/v2/customer', 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.spherepay.co/v2/customer",
  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([
    'address' => [
        'city' => 'Chicago',
        'country' => 'USA',
        'line1' => '233 South Wacker Drive',
        'line2' => 'Suite 4700',
        'postalCode' => '60606',
        'state' => 'IL'
    ],
    'email' => 'jane.smith@example.com',
    'phone' => '+14155550123',
    'type' => 'individual',
    'dateOfBirth' => '2026-01-01',
    'firstName' => 'Jane',
    'lastName' => 'Smith',
    'meta' => [
        
    ],
    'middleName' => 'Anne'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.spherepay.co/v2/customer"

	payload := strings.NewReader("{\n  \"address\": {\n    \"city\": \"Chicago\",\n    \"country\": \"USA\",\n    \"line1\": \"233 South Wacker Drive\",\n    \"line2\": \"Suite 4700\",\n    \"postalCode\": \"60606\",\n    \"state\": \"IL\"\n  },\n  \"email\": \"jane.smith@example.com\",\n  \"phone\": \"+14155550123\",\n  \"type\": \"individual\",\n  \"dateOfBirth\": \"2026-01-01\",\n  \"firstName\": \"Jane\",\n  \"lastName\": \"Smith\",\n  \"meta\": {},\n  \"middleName\": \"Anne\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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.spherepay.co/v2/customer")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"address\": {\n    \"city\": \"Chicago\",\n    \"country\": \"USA\",\n    \"line1\": \"233 South Wacker Drive\",\n    \"line2\": \"Suite 4700\",\n    \"postalCode\": \"60606\",\n    \"state\": \"IL\"\n  },\n  \"email\": \"jane.smith@example.com\",\n  \"phone\": \"+14155550123\",\n  \"type\": \"individual\",\n  \"dateOfBirth\": \"2026-01-01\",\n  \"firstName\": \"Jane\",\n  \"lastName\": \"Smith\",\n  \"meta\": {},\n  \"middleName\": \"Anne\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.spherepay.co/v2/customer")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"address\": {\n    \"city\": \"Chicago\",\n    \"country\": \"USA\",\n    \"line1\": \"233 South Wacker Drive\",\n    \"line2\": \"Suite 4700\",\n    \"postalCode\": \"60606\",\n    \"state\": \"IL\"\n  },\n  \"email\": \"jane.smith@example.com\",\n  \"phone\": \"+14155550123\",\n  \"type\": \"individual\",\n  \"dateOfBirth\": \"2026-01-01\",\n  \"firstName\": \"Jane\",\n  \"lastName\": \"Smith\",\n  \"meta\": {},\n  \"middleName\": \"Anne\"\n}"

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

{
  "createdAt": "2026-03-09T20:46:31.305Z",
  "id": "customer_f31121c389624d3697cbf3ea8830b7a4",
  "tosStatus": "incomplete",
  "type": "individual",
  "updatedAt": "2026-03-09T20:46:31.305Z",
  "verificationProfiles": [
    {
      "criteria": {
        "complete": [
          "email_address",
          "phone_number",
          "residential_address",
          "tax_identification_number"
        ],
        "errors": [],
        "pending": [],
        "required": [
          "identity_document",
          "liveness_report_document"
        ]
      },
      "name": "kyc_profile_a",
      "status": "incomplete"
    }
  ],
  "dateOfBirth": "1990-01-15",
  "email": "jane.smith@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "meta": {},
  "personalInformation": {
    "accountPurpose": "<string>",
    "accountPurposeDescription": "<string>",
    "actingAsIntermediary": false,
    "countryOfBirth": "USA",
    "employmentStatus": "<string>",
    "expectedMonthlyPayments": "<string>",
    "gender": "<string>",
    "middleName": "James",
    "nationality": "USA",
    "occupationSocCode": "151252",
    "residencyCountry": "USA",
    "sourceOfFunds": "<string>",
    "taxIdentificationNumberCountry": "USA",
    "taxIdentificationNumberDescription": "<string>",
    "taxIdentificationNumberType": "ssn"
  },
  "phone": "+14155550123"
}

{
  "code": "address/invalid",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "Invalid request parameters",
  "status": 400
}

{
  "code": "resource/not-found",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "Resource not found",
  "status": 404
}

{
  "code": "validation/failed",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "Validation failed",
  "errors": [
    {
      "detail": "Invalid email format",
      "pointer": "/email"
    },
    {
      "detail": "Name is required",
      "pointer": "/name"
    }
  ],
  "status": 422
}

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. Individual customers resident in the EEA+ region and EEA+ incorporated businesses have additional fields that must be present before verification. Those fields are optional at creation. See EEA+ residents and EEA+ businesses.

Authorizations

Authorization

string

header

required

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

Body

application/json

Individual Customer Create
Business Customer Create

address

object

required

The customer's address.

Show child attributes

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"

type

enum<string>

required

Available options:

individual

dateOfBirth

string

The date string in YYYY-MM-DD format

Example:

"2026-01-01"

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"

Response

Individual
Business

Response containing information about an individual customer.

createdAt

string

required

ISO 8601 formatted customer creation timestamp

Example:

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

string

required

Customer ID

Example:

"customer_f31121c389624d3697cbf3ea8830b7a4"

tosStatus

enum<string>

required

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

Available options:

incomplete,

pending,

approved

Example:

"incomplete"

type

enum<string>

required

Customer type

Available options:

individual

Example:

"individual"

updatedAt

string

required

ISO 8601 formatted customer update timestamp

Example:

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

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.

Show child attributes

Example:

[
  {
    "criteria": {
      "complete": [
        "email_address",
        "phone_number",
        "residential_address",
        "tax_identification_number"
      ],
      "errors": [],
      "pending": [],
      "required": [
        "identity_document",
        "liveness_report_document"
      ]
    },
    "name": "kyc_profile_a",
    "status": "incomplete"
  }
]

dateOfBirth

string

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

Example:

"1990-01-15"

string

Customer email address

Example:

"jane.smith@example.com"

firstName

string

Customer first name (individual customers only)

Example:

"Jane"

lastName

string

Customer last name (individual customers only)

Example:

"Smith"

Onboarding

Accounts

Money movement

Webhooks

Create an Individual or Business Customer

Authorizations

Body

Response