> ## 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.

# Update Customer Address, Phone, or Email

> Update a customer by their ID. (This endpoint only allows updates of personal information for individual customers)

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.

Use this endpoint to backfill EEA+ fields (`accountPurpose`, `countryOfBirth`, `nationality`) on existing individual customers. Validation runs on the merged customer state — send only the fields you are adding or changing. See [EEA+ residents](/concepts/onboarding/individual-kyc#eea-residents).

<Note>
  This endpoint currently supports updates for individual customers only. Business customer fields must be managed through the KYC link flow.
</Note>


## OpenAPI

````yaml openapi/spherepay.yaml PATCH /v2/customer/{id}
openapi: 3.0.0
info:
  contact: {}
  description: The Sphere REST API for payments, transfers, and accounts.
  title: Sphere API
  version: '2'
servers:
  - description: Production
    url: https://api.spherepay.co
security:
  - bearer: []
tags: []
paths:
  /v2/customer/{id}:
    patch:
      summary: Update a Customer by ID
      description: >-
        Update a customer by their ID. (This endpoint only allows updates of
        personal information for individual customers)
      operationId: patchV2CustomerById
      parameters:
        - description: Customer ID
          in: path
          name: id
          required: true
          schema:
            example: customer_f31121c389624d3697cbf3ea8830b7a4
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                address:
                  description: >-
                    The address of the customer. Required if personalInformation
                    is provided.
                  example:
                    city: Chicago
                    country: USA
                    line1: 233 South Wacker Drive
                    line2: Suite 4700
                    postalCode: '60606'
                    state: IL
                  properties:
                    city:
                      description: The city name
                      example: Chicago
                      maxLength: 255
                      minLength: 1
                      type: string
                    country:
                      description: >-
                        The ISO3166-1 Alpha-3 country code (e.g., USA, GBR,
                        CAN). See [Country
                        Codes](/concepts/reference/supported-countries).
                      example: USA
                      type: string
                    line1:
                      description: The first line of the street address
                      example: 233 South Wacker Drive
                      maxLength: 255
                      minLength: 1
                      type: string
                    line2:
                      description: >-
                        The second line of the street address (apartment, suite,
                        etc.)
                      example: Suite 4700
                      maxLength: 255
                      type: string
                    postalCode:
                      description: >-
                        The postal or ZIP code. Required for countries that use
                        postal codes
                      example: '60606'
                      type: string
                    state:
                      description: >-
                        The state or province code (ISO3166-2 subdivision code).
                        Required for countries that have states/provinces. See
                        State Codes.
                      example: IL
                      type: string
                  required:
                    - line1
                    - city
                    - country
                  type: object
                meta:
                  additionalProperties:
                    type: string
                  description: The customer metadata
                  example:
                    key: value
                  type: object
                personalInformation:
                  description: >-
                    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](/concepts/onboarding/verification-profile) for the
                    full list of reference.
                  properties:
                    accountPurpose:
                      description: >-
                        The purpose of the account. Required for EEA-resident
                        individuals before they can be submitted for
                        verification.
                      enum:
                        - personal_or_living_expenses
                        - payments_to_friends_or_family_abroad
                        - receive_salary
                        - receive_payment_for_freelancing
                        - protect_wealth
                        - purchase_goods_and_services
                        - charitable_donations
                        - ecommerce_retail_payments
                        - investment_purposes
                        - operating_a_company
                        - other
                      example: receive_salary
                      type: string
                    accountPurposeDescription:
                      description: >-
                        A free-text description of the account purpose. Required
                        when `accountPurpose` is `other`.
                      type: string
                    actingAsIntermediary:
                      description: >-
                        Whether the customer is acting as an intermediary on
                        behalf of a third party. Required by some verification
                        providers.
                      example: false
                      type: boolean
                    countryOfBirth:
                      description: >-
                        The ISO3166-1 Alpha-3 country code of the country where
                        the customer was born. See [Country
                        Codes](/concepts/reference/supported-countries).
                      example: USA
                      type: string
                    employmentStatus:
                      description: >-
                        The customer's employment status. Required by some
                        verification providers.
                      enum:
                        - employed
                        - homemaker
                        - retired
                        - self_employed
                        - student
                        - unemployed
                      example: employed
                      type: string
                    expectedMonthlyPayments:
                      description: >-
                        The expected monthly payment volume in USD, as a bucket
                        range. Required by some verification providers.
                      enum:
                        - 0_4999
                        - 5000_9999
                        - 10000_49999
                        - 50000_plus
                      example: 5000_9999
                      type: string
                    gender:
                      description: >-
                        The gender of the customer. Required by some
                        verification providers.
                      enum:
                        - male
                        - female
                        - other
                      example: male
                      type: string
                    middleName:
                      description: >-
                        The customer's middle name. Required for some
                        verification flows.
                      example: James
                      maxLength: 255
                      minLength: 1
                      type: string
                    nationality:
                      description: >-
                        The ISO3166-1 Alpha-3 country code of the customer's
                        nationality. Required by some verification providers.
                        See [Country
                        Codes](/concepts/reference/supported-countries).
                      example: USA
                      type: string
                    occupationSocCode:
                      description: >-
                        The customer's occupation as a 6-digit Standard
                        Occupational Classification (SOC) code, validated
                        against the supported occupation list. Required for some
                        verification flows.
                      example: '151252'
                      maxLength: 20
                      minLength: 1
                      type: string
                    residencyCountry:
                      description: >-
                        The ISO3166-1 Alpha-3 country code of the customer's
                        country of residency. Often satisfied by the address
                        country, but some verification providers require it as a
                        separate attribute. See [Country
                        Codes](/concepts/reference/supported-countries).
                      example: USA
                      type: string
                    sourceOfFunds:
                      description: >-
                        The customer's primary source of funds. Required by some
                        verification providers.
                      enum:
                        - salary
                        - business_income
                        - investment_returns
                        - inheritance
                        - gift
                        - savings
                        - other
                      example: salary
                      type: string
                    taxIdentificationNumber:
                      description: >-
                        The tax identification number. Required when providing
                        tax identification information. Only alphanumeric
                        characters (letters and numbers) are accepted - omit
                        separators such as dashes or spaces (e.g. send
                        "123456789", not "123-45-6789").
                      example: '123456789'
                      minLength: 1
                      pattern: ^[a-zA-Z0-9]+$
                      type: string
                    taxIdentificationNumberCountry:
                      description: >-
                        The ISO3166-1 Alpha-3 country code for the tax
                        identification number. Required when providing tax
                        identification information. See [Country
                        Codes](/concepts/reference/supported-countries).
                      example: USA
                      minLength: 1
                      type: string
                    taxIdentificationNumberDescription:
                      description: >-
                        Description of the tax identification number. Required
                        when type is `other`
                      type: string
                    taxIdentificationNumberType:
                      description: >-
                        The type of tax identification number of the customer.
                        Required when providing tax identification information.
                        Please refer to the [Individual Verification
                        Criteria](/concepts/onboarding/verification-profile) for
                        the full list of reference.
                      example: ssn
                      minLength: 1
                      type: string
                  type: object
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponseDto'
          description: ''
        '400':
          content:
            application/json:
              examples:
                Bad Request:
                  summary: Bad Request
                  value:
                    code: address/invalid
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    detail: Invalid request parameters
                    status: 400
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          description: Bad Request
        '404':
          content:
            application/json:
              examples:
                Not Found:
                  summary: Not Found
                  value:
                    code: resource/not-found
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    detail: Resource not found
                    status: 404
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          description: Not Found
        '422':
          content:
            application/json:
              examples:
                Validation Error:
                  summary: Validation Error
                  value:
                    code: validation/failed
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    detail: Validation failed
                    errors:
                      - detail: Invalid email format
                        pointer: /email
                      - detail: Name is required
                        pointer: /name
                    status: 422
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          description: Unprocessable Entity - Validation Error
components:
  schemas:
    CustomerResponseDto:
      oneOf:
        - description: Response containing information about an individual customer.
          properties:
            createdAt:
              description: ISO 8601 formatted customer creation timestamp
              example: '2026-03-09T20:46:31.305Z'
              type: string
            dateOfBirth:
              description: >-
                The customer's date of birth in YYYY-MM-DD format (individual
                customers only).
              example: '1990-01-15'
              type: string
            email:
              description: Customer email address
              example: jane.smith@example.com
              type: string
            firstName:
              description: Customer first name (individual customers only)
              example: Jane
              type: string
            id:
              description: Customer ID
              example: customer_f31121c389624d3697cbf3ea8830b7a4
              type: string
            lastName:
              description: Customer last name (individual customers only)
              example: Smith
              type: string
            meta:
              additionalProperties: {}
              type: object
            personalInformation:
              description: >-
                Personal information for an individual customer, echoed back
                from the most recent submission. The tax identification number
                is omitted from responses for privacy.
              properties:
                accountPurpose:
                  type: string
                accountPurposeDescription:
                  description: >-
                    A free-text description of the account purpose. Required
                    when `accountPurpose` is `other`.
                  type: string
                actingAsIntermediary:
                  description: >-
                    Whether the customer is acting as an intermediary on behalf
                    of a third party. Required by some verification providers.
                  example: false
                  type: boolean
                countryOfBirth:
                  description: >-
                    The ISO3166-1 Alpha-3 country code of the country where the
                    customer was born. See [Country
                    Codes](/concepts/reference/supported-countries).
                  example: USA
                  type: string
                employmentStatus:
                  type: string
                expectedMonthlyPayments:
                  type: string
                gender:
                  type: string
                middleName:
                  description: >-
                    The customer's middle name. Required for some verification
                    flows.
                  example: James
                  maxLength: 255
                  minLength: 1
                  type: string
                nationality:
                  description: >-
                    The ISO3166-1 Alpha-3 country code of the customer's
                    nationality. Required by some verification providers. See
                    [Country Codes](/concepts/reference/supported-countries).
                  example: USA
                  type: string
                occupationSocCode:
                  description: >-
                    The customer's occupation as a 6-digit Standard Occupational
                    Classification (SOC) code, validated against the supported
                    occupation list. Required for some verification flows.
                  example: '151252'
                  maxLength: 20
                  minLength: 1
                  type: string
                residencyCountry:
                  description: >-
                    The ISO3166-1 Alpha-3 country code of the customer's country
                    of residency. Often satisfied by the address country, but
                    some verification providers require it as a separate
                    attribute. See [Country
                    Codes](/concepts/reference/supported-countries).
                  example: USA
                  type: string
                sourceOfFunds:
                  type: string
                taxIdentificationNumberCountry:
                  description: >-
                    The ISO3166-1 Alpha-3 country code for the tax
                    identification number. Required when providing tax
                    identification information. See [Country
                    Codes](/concepts/reference/supported-countries).
                  example: USA
                  minLength: 1
                  type: string
                taxIdentificationNumberDescription:
                  description: >-
                    Description of the tax identification number. Required when
                    type is `other`
                  type: string
                taxIdentificationNumberType:
                  description: >-
                    The type of tax identification number of the customer.
                    Required when providing tax identification information.
                    Please refer to the [Individual Verification
                    Criteria](/concepts/onboarding/verification-profile) for the
                    full list of reference.
                  example: ssn
                  minLength: 1
                  type: string
              type: object
            phone:
              description: Customer phone number
              example: '+14155550123'
              type: string
            tosStatus:
              description: >-
                Customer Terms of Service acceptance status (incomplete |
                pending | approved).
              enum:
                - incomplete
                - pending
                - approved
              example: incomplete
              type: string
              x-enumNames:
                - Incomplete
                - Pending
                - Approved
            type:
              description: Customer type
              enum:
                - individual
              example: individual
              type: string
            updatedAt:
              description: ISO 8601 formatted customer update timestamp
              example: '2026-03-09T20:46:31.305Z'
              type: string
            verificationProfiles:
              description: >-
                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](/concepts/onboarding/individual-kyc) for individuals or
                [KYB Flow](/concepts/onboarding/business-kyb) for businesses.
                See [Verification
                Profile](/concepts/onboarding/verification-profile) for
                individual status definitions and criteria breakdown or
                [Verification
                Profile](/concepts/onboarding/verification-profile) for business
                status definitions and criteria breakdown.
              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
              items:
                properties:
                  criteria:
                    description: The criteria for the verification profile.
                    example:
                      complete:
                        - email_address
                        - phone_number
                        - residential_address
                        - tax_identification_number
                      errors: []
                      pending: []
                      required:
                        - identity_document
                        - liveness_report_document
                    properties:
                      complete:
                        description: Completed fields.
                        example:
                          - email_address
                          - phone_number
                          - residential_address
                          - tax_identification_number
                        items:
                          type: string
                        type: array
                      errors:
                        description: The errors that occurred while verifying the fields.
                        example: []
                        items:
                          properties:
                            detail:
                              type: string
                            name:
                              enum:
                                - email_verification
                                - phone_verification
                                - residential_address
                                - identity_document
                                - tax_identification_number
                                - liveness_check
                                - terms_of_service
                                - email_address
                                - phone_number
                                - master_service_agreement
                                - legal_name
                                - trade_name
                                - entity_type
                                - entity_type_description
                                - description
                                - registered_address
                                - operating_address
                                - business_representatives
                                - naics_code
                                - website
                                - incorporated_on
                                - identification_number
                                - registration_number
                                - estimated_annual_revenue
                                - expected_monthly_payments
                                - account_purpose
                                - account_purpose_description
                                - source_of_funds
                                - source_of_funds_description
                                - is_dao
                                - regulated_activities
                                - regulated_activities_description
                                - participates_in_regulated_financial_activity
                                - regulated_financial_activity_description
                                - money_services_description
                                - compliance_screening_explanation
                                - operates_in_prohibited_countries
                                - incorporation_cert_document
                                - incorporation_articles_document
                                - shareholder_registry_document
                                - proof_of_nature_of_business_document
                                - proof_of_address_document
                                - liveness_report_document
                                - ownership_percentage
                                - is_control_person
                                - control_person_added
                                - is_signer
                                - relationship_established_at
                                - title
                                - sex
                                - country_of_birth
                                - nationality
                                - middle_name
                                - occupation_soc_code
                                - w8_ben_document
                                - w9_document
                                - w8_ben_e_document
                                - corporate_resolution_document
                                - source_of_funds_document
                                - financial_statements_document
                                - bank_statement_document
                                - regulated_activity_document
                                - flow_of_funds_document
                                - kyc_b_approval
                                - kyb_b_approval
                              type: string
                          required:
                            - name
                          type: object
                        type: array
                      pending:
                        description: >-
                          Pending fields. These fields are currently being
                          verified.
                        example: []
                        items:
                          type: string
                        type: array
                      required:
                        description: >-
                          Required fields. These fields are required to be
                          completed before the verification profile can be
                          approved.
                        example:
                          - identity_document
                          - liveness_report_document
                        items:
                          type: string
                        type: array
                    required:
                      - complete
                      - pending
                      - required
                      - errors
                    type: object
                  name:
                    description: The name of the verification profile.
                    enum:
                      - kyc_profile_a
                      - kyb_profile_a
                      - ubo_kyc_profile_a
                      - kyc_profile_b
                      - kyb_profile_b
                      - kyb_profile_c
                      - kyc_profile_c
                      - ubo_kyc_profile_c
                      - kyb_profile_d
                      - kyc_profile_d
                      - ubo_kyc_profile_d
                    example: kyc_profile_a
                    type: string
                  status:
                    description: The status of the verification profile.
                    enum:
                      - incomplete
                      - pending
                      - approved
                      - rejected
                      - resubmission_required
                    example: incomplete
                    type: string
                required:
                  - name
                  - status
                type: object
              type: array
          required:
            - id
            - verificationProfiles
            - tosStatus
            - createdAt
            - updatedAt
            - type
          title: Individual
          type: object
        - description: Response containing information about a business customer.
          properties:
            businessLegalName:
              description: Customer business legal name (business customers only)
              example: Acme Corporation Inc.
              type: string
            businessTradeName:
              description: Customer business trade name (business customers only)
              example: Acme Corp
              type: string
            createdAt:
              description: ISO 8601 formatted customer creation timestamp
              example: '2026-03-09T20:46:31.305Z'
              type: string
            email:
              description: Customer email address
              example: jane.smith@example.com
              type: string
            id:
              description: Customer ID
              example: customer_f31121c389624d3697cbf3ea8830b7a4
              type: string
            meta:
              additionalProperties: {}
              type: object
            phone:
              description: Customer phone number
              example: '+14155550123'
              type: string
            tosStatus:
              description: >-
                Customer Terms of Service acceptance status (incomplete |
                pending | approved).
              enum:
                - incomplete
                - pending
                - approved
              example: incomplete
              type: string
              x-enumNames:
                - Incomplete
                - Pending
                - Approved
            type:
              description: Customer type
              enum:
                - business
              example: business
              type: string
            updatedAt:
              description: ISO 8601 formatted customer update timestamp
              example: '2026-03-09T20:46:31.305Z'
              type: string
            verificationProfiles:
              description: >-
                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](/concepts/onboarding/individual-kyc) for individuals or
                [KYB Flow](/concepts/onboarding/business-kyb) for businesses.
                See [Verification
                Profile](/concepts/onboarding/verification-profile) for
                individual status definitions and criteria breakdown or
                [Verification
                Profile](/concepts/onboarding/verification-profile) for business
                status definitions and criteria breakdown.
              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
              items:
                properties:
                  criteria:
                    description: The criteria for the verification profile.
                    example:
                      complete:
                        - email_address
                        - phone_number
                        - residential_address
                        - tax_identification_number
                      errors: []
                      pending: []
                      required:
                        - identity_document
                        - liveness_report_document
                    properties:
                      complete:
                        description: Completed fields.
                        example:
                          - email_address
                          - phone_number
                          - residential_address
                          - tax_identification_number
                        items:
                          type: string
                        type: array
                      errors:
                        description: The errors that occurred while verifying the fields.
                        example: []
                        items:
                          properties:
                            detail:
                              type: string
                            name:
                              enum:
                                - email_verification
                                - phone_verification
                                - residential_address
                                - identity_document
                                - tax_identification_number
                                - liveness_check
                                - terms_of_service
                                - email_address
                                - phone_number
                                - master_service_agreement
                                - legal_name
                                - trade_name
                                - entity_type
                                - entity_type_description
                                - description
                                - registered_address
                                - operating_address
                                - business_representatives
                                - naics_code
                                - website
                                - incorporated_on
                                - identification_number
                                - registration_number
                                - estimated_annual_revenue
                                - expected_monthly_payments
                                - account_purpose
                                - account_purpose_description
                                - source_of_funds
                                - source_of_funds_description
                                - is_dao
                                - regulated_activities
                                - regulated_activities_description
                                - participates_in_regulated_financial_activity
                                - regulated_financial_activity_description
                                - money_services_description
                                - compliance_screening_explanation
                                - operates_in_prohibited_countries
                                - incorporation_cert_document
                                - incorporation_articles_document
                                - shareholder_registry_document
                                - proof_of_nature_of_business_document
                                - proof_of_address_document
                                - liveness_report_document
                                - ownership_percentage
                                - is_control_person
                                - control_person_added
                                - is_signer
                                - relationship_established_at
                                - title
                                - sex
                                - country_of_birth
                                - nationality
                                - middle_name
                                - occupation_soc_code
                                - w8_ben_document
                                - w9_document
                                - w8_ben_e_document
                                - corporate_resolution_document
                                - source_of_funds_document
                                - financial_statements_document
                                - bank_statement_document
                                - regulated_activity_document
                                - flow_of_funds_document
                                - kyc_b_approval
                                - kyb_b_approval
                              type: string
                          required:
                            - name
                          type: object
                        type: array
                      pending:
                        description: >-
                          Pending fields. These fields are currently being
                          verified.
                        example: []
                        items:
                          type: string
                        type: array
                      required:
                        description: >-
                          Required fields. These fields are required to be
                          completed before the verification profile can be
                          approved.
                        example:
                          - identity_document
                          - liveness_report_document
                        items:
                          type: string
                        type: array
                    required:
                      - complete
                      - pending
                      - required
                      - errors
                    type: object
                  name:
                    description: The name of the verification profile.
                    enum:
                      - kyc_profile_a
                      - kyb_profile_a
                      - ubo_kyc_profile_a
                      - kyc_profile_b
                      - kyb_profile_b
                      - kyb_profile_c
                      - kyc_profile_c
                      - ubo_kyc_profile_c
                      - kyb_profile_d
                      - kyc_profile_d
                      - ubo_kyc_profile_d
                    example: kyc_profile_a
                    type: string
                  status:
                    description: The status of the verification profile.
                    enum:
                      - incomplete
                      - pending
                      - approved
                      - rejected
                      - resubmission_required
                    example: incomplete
                    type: string
                required:
                  - name
                  - status
                type: object
              type: array
          required:
            - id
            - verificationProfiles
            - tosStatus
            - createdAt
            - updatedAt
            - type
          title: Business
          type: object
    ProblemDetailsDto:
      properties:
        code:
          type: string
        correlationId:
          type: string
        detail:
          type: string
        errors:
          items:
            properties:
              detail:
                type: string
              header:
                type: string
              parameter:
                type: string
              pointer:
                type: string
            required:
              - detail
            type: object
          type: array
        status:
          type: integer
        title:
          type: string
      required:
        - status
        - detail
      type: object
  securitySchemes:
    bearer:
      bearerFormat: JWT
      scheme: bearer
      type: http

````