Update a Customer by ID
curl --request PATCH \
--url https://api.spherepay.co/v2/customer/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"address": {
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"city": "Chicago",
"postalCode": "60606",
"state": "IL",
"country": "USA"
},
"personalInformation": {
"taxIdentificationNumber": "123456789",
"taxIdentificationNumberType": "ssn",
"taxIdentificationNumberCountry": "USA",
"taxIdentificationNumberDescription": "<string>",
"accountPurpose": "receive_salary",
"gender": "male",
"countryOfBirth": "USA",
"nationality": "USA",
"middleName": "James",
"occupationSocCode": "15-1132",
"residencyCountry": "USA",
"sourceOfFunds": "salary"
},
"meta": {
"key": "value"
}
}
'import requests
url = "https://api.spherepay.co/v2/customer/{id}"
payload = {
"address": {
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"city": "Chicago",
"postalCode": "60606",
"state": "IL",
"country": "USA"
},
"personalInformation": {
"taxIdentificationNumber": "123456789",
"taxIdentificationNumberType": "ssn",
"taxIdentificationNumberCountry": "USA",
"taxIdentificationNumberDescription": "<string>",
"accountPurpose": "receive_salary",
"gender": "male",
"countryOfBirth": "USA",
"nationality": "USA",
"middleName": "James",
"occupationSocCode": "15-1132",
"residencyCountry": "USA",
"sourceOfFunds": "salary"
},
"meta": { "key": "value" }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
address: {
line1: '233 South Wacker Drive',
line2: 'Suite 4700',
city: 'Chicago',
postalCode: '60606',
state: 'IL',
country: 'USA'
},
personalInformation: {
taxIdentificationNumber: '123456789',
taxIdentificationNumberType: 'ssn',
taxIdentificationNumberCountry: 'USA',
taxIdentificationNumberDescription: '<string>',
accountPurpose: 'receive_salary',
gender: 'male',
countryOfBirth: 'USA',
nationality: 'USA',
middleName: 'James',
occupationSocCode: '15-1132',
residencyCountry: 'USA',
sourceOfFunds: 'salary'
},
meta: {key: 'value'}
})
};
fetch('https://api.spherepay.co/v2/customer/{id}', 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/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'address' => [
'line1' => '233 South Wacker Drive',
'line2' => 'Suite 4700',
'city' => 'Chicago',
'postalCode' => '60606',
'state' => 'IL',
'country' => 'USA'
],
'personalInformation' => [
'taxIdentificationNumber' => '123456789',
'taxIdentificationNumberType' => 'ssn',
'taxIdentificationNumberCountry' => 'USA',
'taxIdentificationNumberDescription' => '<string>',
'accountPurpose' => 'receive_salary',
'gender' => 'male',
'countryOfBirth' => 'USA',
'nationality' => 'USA',
'middleName' => 'James',
'occupationSocCode' => '15-1132',
'residencyCountry' => 'USA',
'sourceOfFunds' => 'salary'
],
'meta' => [
'key' => 'value'
]
]),
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/{id}"
payload := strings.NewReader("{\n \"address\": {\n \"line1\": \"233 South Wacker Drive\",\n \"line2\": \"Suite 4700\",\n \"city\": \"Chicago\",\n \"postalCode\": \"60606\",\n \"state\": \"IL\",\n \"country\": \"USA\"\n },\n \"personalInformation\": {\n \"taxIdentificationNumber\": \"123456789\",\n \"taxIdentificationNumberType\": \"ssn\",\n \"taxIdentificationNumberCountry\": \"USA\",\n \"taxIdentificationNumberDescription\": \"<string>\",\n \"accountPurpose\": \"receive_salary\",\n \"gender\": \"male\",\n \"countryOfBirth\": \"USA\",\n \"nationality\": \"USA\",\n \"middleName\": \"James\",\n \"occupationSocCode\": \"15-1132\",\n \"residencyCountry\": \"USA\",\n \"sourceOfFunds\": \"salary\"\n },\n \"meta\": {\n \"key\": \"value\"\n }\n}")
req, _ := http.NewRequest("PATCH", 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.patch("https://api.spherepay.co/v2/customer/{id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"address\": {\n \"line1\": \"233 South Wacker Drive\",\n \"line2\": \"Suite 4700\",\n \"city\": \"Chicago\",\n \"postalCode\": \"60606\",\n \"state\": \"IL\",\n \"country\": \"USA\"\n },\n \"personalInformation\": {\n \"taxIdentificationNumber\": \"123456789\",\n \"taxIdentificationNumberType\": \"ssn\",\n \"taxIdentificationNumberCountry\": \"USA\",\n \"taxIdentificationNumberDescription\": \"<string>\",\n \"accountPurpose\": \"receive_salary\",\n \"gender\": \"male\",\n \"countryOfBirth\": \"USA\",\n \"nationality\": \"USA\",\n \"middleName\": \"James\",\n \"occupationSocCode\": \"15-1132\",\n \"residencyCountry\": \"USA\",\n \"sourceOfFunds\": \"salary\"\n },\n \"meta\": {\n \"key\": \"value\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.spherepay.co/v2/customer/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"address\": {\n \"line1\": \"233 South Wacker Drive\",\n \"line2\": \"Suite 4700\",\n \"city\": \"Chicago\",\n \"postalCode\": \"60606\",\n \"state\": \"IL\",\n \"country\": \"USA\"\n },\n \"personalInformation\": {\n \"taxIdentificationNumber\": \"123456789\",\n \"taxIdentificationNumberType\": \"ssn\",\n \"taxIdentificationNumberCountry\": \"USA\",\n \"taxIdentificationNumberDescription\": \"<string>\",\n \"accountPurpose\": \"receive_salary\",\n \"gender\": \"male\",\n \"countryOfBirth\": \"USA\",\n \"nationality\": \"USA\",\n \"middleName\": \"James\",\n \"occupationSocCode\": \"15-1132\",\n \"residencyCountry\": \"USA\",\n \"sourceOfFunds\": \"salary\"\n },\n \"meta\": {\n \"key\": \"value\"\n }\n}"
response = http.request(request)
puts response.read_body{
"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>",
"accountPurpose": "receive_salary",
"gender": "male",
"countryOfBirth": "USA",
"nationality": "USA",
"middleName": "James",
"occupationSocCode": "15-1132",
"residencyCountry": "USA",
"sourceOfFunds": "salary"
}
}{
"status": 400,
"detail": "Invalid request parameters",
"code": "address/invalid",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c"
}{
"status": 404,
"detail": "Resource not found",
"code": "resource/not-found",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c"
}{
"status": 422,
"detail": "Validation failed",
"code": "validation/failed",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"errors": [
{
"detail": "Invalid email format",
"pointer": "/email"
},
{
"detail": "Name is required",
"pointer": "/name"
}
]
}Customers
Update Customer Address, Phone, or Email
Update a customer by their ID. (This endpoint only allows updates of personal information for individual customers)
Update a Customer by ID
curl --request PATCH \
--url https://api.spherepay.co/v2/customer/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"address": {
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"city": "Chicago",
"postalCode": "60606",
"state": "IL",
"country": "USA"
},
"personalInformation": {
"taxIdentificationNumber": "123456789",
"taxIdentificationNumberType": "ssn",
"taxIdentificationNumberCountry": "USA",
"taxIdentificationNumberDescription": "<string>",
"accountPurpose": "receive_salary",
"gender": "male",
"countryOfBirth": "USA",
"nationality": "USA",
"middleName": "James",
"occupationSocCode": "15-1132",
"residencyCountry": "USA",
"sourceOfFunds": "salary"
},
"meta": {
"key": "value"
}
}
'import requests
url = "https://api.spherepay.co/v2/customer/{id}"
payload = {
"address": {
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"city": "Chicago",
"postalCode": "60606",
"state": "IL",
"country": "USA"
},
"personalInformation": {
"taxIdentificationNumber": "123456789",
"taxIdentificationNumberType": "ssn",
"taxIdentificationNumberCountry": "USA",
"taxIdentificationNumberDescription": "<string>",
"accountPurpose": "receive_salary",
"gender": "male",
"countryOfBirth": "USA",
"nationality": "USA",
"middleName": "James",
"occupationSocCode": "15-1132",
"residencyCountry": "USA",
"sourceOfFunds": "salary"
},
"meta": { "key": "value" }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
address: {
line1: '233 South Wacker Drive',
line2: 'Suite 4700',
city: 'Chicago',
postalCode: '60606',
state: 'IL',
country: 'USA'
},
personalInformation: {
taxIdentificationNumber: '123456789',
taxIdentificationNumberType: 'ssn',
taxIdentificationNumberCountry: 'USA',
taxIdentificationNumberDescription: '<string>',
accountPurpose: 'receive_salary',
gender: 'male',
countryOfBirth: 'USA',
nationality: 'USA',
middleName: 'James',
occupationSocCode: '15-1132',
residencyCountry: 'USA',
sourceOfFunds: 'salary'
},
meta: {key: 'value'}
})
};
fetch('https://api.spherepay.co/v2/customer/{id}', 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/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'address' => [
'line1' => '233 South Wacker Drive',
'line2' => 'Suite 4700',
'city' => 'Chicago',
'postalCode' => '60606',
'state' => 'IL',
'country' => 'USA'
],
'personalInformation' => [
'taxIdentificationNumber' => '123456789',
'taxIdentificationNumberType' => 'ssn',
'taxIdentificationNumberCountry' => 'USA',
'taxIdentificationNumberDescription' => '<string>',
'accountPurpose' => 'receive_salary',
'gender' => 'male',
'countryOfBirth' => 'USA',
'nationality' => 'USA',
'middleName' => 'James',
'occupationSocCode' => '15-1132',
'residencyCountry' => 'USA',
'sourceOfFunds' => 'salary'
],
'meta' => [
'key' => 'value'
]
]),
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/{id}"
payload := strings.NewReader("{\n \"address\": {\n \"line1\": \"233 South Wacker Drive\",\n \"line2\": \"Suite 4700\",\n \"city\": \"Chicago\",\n \"postalCode\": \"60606\",\n \"state\": \"IL\",\n \"country\": \"USA\"\n },\n \"personalInformation\": {\n \"taxIdentificationNumber\": \"123456789\",\n \"taxIdentificationNumberType\": \"ssn\",\n \"taxIdentificationNumberCountry\": \"USA\",\n \"taxIdentificationNumberDescription\": \"<string>\",\n \"accountPurpose\": \"receive_salary\",\n \"gender\": \"male\",\n \"countryOfBirth\": \"USA\",\n \"nationality\": \"USA\",\n \"middleName\": \"James\",\n \"occupationSocCode\": \"15-1132\",\n \"residencyCountry\": \"USA\",\n \"sourceOfFunds\": \"salary\"\n },\n \"meta\": {\n \"key\": \"value\"\n }\n}")
req, _ := http.NewRequest("PATCH", 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.patch("https://api.spherepay.co/v2/customer/{id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"address\": {\n \"line1\": \"233 South Wacker Drive\",\n \"line2\": \"Suite 4700\",\n \"city\": \"Chicago\",\n \"postalCode\": \"60606\",\n \"state\": \"IL\",\n \"country\": \"USA\"\n },\n \"personalInformation\": {\n \"taxIdentificationNumber\": \"123456789\",\n \"taxIdentificationNumberType\": \"ssn\",\n \"taxIdentificationNumberCountry\": \"USA\",\n \"taxIdentificationNumberDescription\": \"<string>\",\n \"accountPurpose\": \"receive_salary\",\n \"gender\": \"male\",\n \"countryOfBirth\": \"USA\",\n \"nationality\": \"USA\",\n \"middleName\": \"James\",\n \"occupationSocCode\": \"15-1132\",\n \"residencyCountry\": \"USA\",\n \"sourceOfFunds\": \"salary\"\n },\n \"meta\": {\n \"key\": \"value\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.spherepay.co/v2/customer/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"address\": {\n \"line1\": \"233 South Wacker Drive\",\n \"line2\": \"Suite 4700\",\n \"city\": \"Chicago\",\n \"postalCode\": \"60606\",\n \"state\": \"IL\",\n \"country\": \"USA\"\n },\n \"personalInformation\": {\n \"taxIdentificationNumber\": \"123456789\",\n \"taxIdentificationNumberType\": \"ssn\",\n \"taxIdentificationNumberCountry\": \"USA\",\n \"taxIdentificationNumberDescription\": \"<string>\",\n \"accountPurpose\": \"receive_salary\",\n \"gender\": \"male\",\n \"countryOfBirth\": \"USA\",\n \"nationality\": \"USA\",\n \"middleName\": \"James\",\n \"occupationSocCode\": \"15-1132\",\n \"residencyCountry\": \"USA\",\n \"sourceOfFunds\": \"salary\"\n },\n \"meta\": {\n \"key\": \"value\"\n }\n}"
response = http.request(request)
puts response.read_body{
"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>",
"accountPurpose": "receive_salary",
"gender": "male",
"countryOfBirth": "USA",
"nationality": "USA",
"middleName": "James",
"occupationSocCode": "15-1132",
"residencyCountry": "USA",
"sourceOfFunds": "salary"
}
}{
"status": 400,
"detail": "Invalid request parameters",
"code": "address/invalid",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c"
}{
"status": 404,
"detail": "Resource not found",
"code": "resource/not-found",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c"
}{
"status": 422,
"detail": "Validation failed",
"code": "validation/failed",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"errors": [
{
"detail": "Invalid email format",
"pointer": "/email"
},
{
"detail": "Name is required",
"pointer": "/name"
}
]
}Use this endpoint to update mutable fields on an existing individual customer. You can update the customer’s address, personal information, and metadata at any time before KYC submission. Once a KYC review has been submitted, identity fields such as name, date of birth, and tax identification number are locked and cannot be changed — only contact details and metadata remain editable.
This endpoint currently supports updates for individual customers only. Business customer fields must be managed through the KYC link flow.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Customer ID
Example:
"customer_f31121c389624d3697cbf3ea8830b7a4"
Body
application/json
The address of the customer. Required if personalInformation is provided.
Show child attributes
Show child attributes
Example:
{
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"city": "Chicago",
"postalCode": "60606",
"state": "IL",
"country": "USA"
}
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.
Show child attributes
Show child attributes
The customer metadata
Show child attributes
Show child attributes
Example:
{ "key": "value" }
Response
- Individual
- Business
Response containing information about an individual customer.
Customer ID
Example:
"customer_f31121c389624d3697cbf3ea8830b7a4"
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
Show child attributes
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": []
}
}
]
Customer Terms of Service acceptance status (incomplete | pending | approved).
Available options:
incomplete, pending, approved Example:
"incomplete"
ISO 8601 formatted customer creation timestamp
Example:
"2026-03-09T20:46:31.305Z"
ISO 8601 formatted customer update timestamp
Example:
"2026-03-09T20:46:31.305Z"
Customer type
Available options:
individual Example:
"individual"
Customer email address
Example:
"jane.smith@example.com"
Customer phone number
Example:
"+14155550123"
Show child attributes
Show child attributes
Customer first name (individual customers only)
Example:
"Jane"
Customer last name (individual customers only)
Example:
"Smith"
The customer's date of birth in YYYY-MM-DD format (individual customers only).
Example:
"1990-01-15"
Personal information for an individual customer, echoed back from the most recent submission. The tax identification number is omitted from responses for privacy.
Show child attributes
Show child attributes
Last modified on June 18, 2026
⌘I