Update Customer Address, Phone, or Email

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.

Endpoint

PATCH https://api.spherepay.co/v2/customer/{id}

Authentication

All requests require a Bearer token in the Authorization header.

Authorization: Bearer <token>

Path parameters

string

required

The unique customer ID, prefixed with customer_ (e.g. customer_f31121c389624d3697cbf3ea8830b7a4).

Request body

All body fields are optional. Include only the fields you want to update.

address

object

Updated residential address. Required if personalInformation is provided with tax identification fields.

Show address properties

line1

string

Street address line 1.

line2

string

Street address line 2 (apartment, suite, etc.).

city

string

City name.

state

string

State or province code.

postalCode

string

Postal or ZIP code.

country

string

ISO 3166-1 alpha-3 country code.

personalInformation

object

Personal information fields. When any tax identification field is provided, all three tax identification fields (number, type, country) and address are required.

After KYC has been submitted for review, identity fields (name, date of birth, tax identification) cannot be modified. Attempting to change them will return a 400 error.

Show personalInformation properties

firstName

string

Customer’s legal first name.

lastName

string

Customer’s legal last name.

dateOfBirth

string

Date of birth in YYYY-MM-DD format.

taxIdentification

object

Tax identification details.

Show taxIdentification properties

number

string

Tax identification number (e.g. SSN, CPF).

type

string

Tax identification type (e.g. ssn, cpf).

country

string

ISO 3166-1 alpha-3 country that issued the tax ID.

Response fields

The response contains the full updated customer object.

string

Unique customer identifier.

type

string

Customer type: individual or business.

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[]

Current verification profile array with updated criteria status.

meta

object

Updated metadata object.

createdAt

string

ISO 8601 creation timestamp (unchanged).

updatedAt

string

ISO 8601 timestamp reflecting the current 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": {
    "internalUserId": "usr_9912"
  },
  "createdAt": "2026-03-09T20:46:31.305Z",
  "updatedAt": "2026-04-01T14:22:10.000Z"
}

Mutable vs. immutable fields

Field	Mutable before KYC	Mutable after KYC submission
`address`	Yes	Yes
`meta`	Yes	Yes
`personalInformation.firstName`	Yes	No
`personalInformation.lastName`	Yes	No
`personalInformation.dateOfBirth`	Yes	No
`personalInformation.taxIdentification`	Yes	No

Error codes

Status	Code	Description
`400`	`address/invalid`	The address object contains invalid fields, or an immutable field was modified after KYC submission.
`404`	`resource/not-found`	No customer exists with the given ID.
`422`	`validation/failed`	One or more fields failed validation. The `errors` array identifies each failing field.

Documentation Index

​Endpoint

​Authentication

​Path parameters

​Request body

​Response fields

​Mutable vs. immutable fields

​Error codes

Endpoint

Authentication

Path parameters

Request body

Response fields

Mutable vs. immutable fields

Error codes