Retrieve a Customer with Verification Status

Use this endpoint to fetch the full details of a single customer by their unique ID. The response includes the customer’s current verification profile status, which tells you exactly which KYC/KYB criteria remain outstanding before the customer can initiate a transfer. You can also inspect attached bank accounts and wallets through this record.

Endpoint

GET 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).

  -H "Authorization: Bearer $SPHEREPAY_API_KEY"

Response fields

string

Unique customer identifier, prefixed with customer_.

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

Array of verification profiles describing the customer’s KYC or KYB status.

Show verificationProfile properties

name

string

Profile identifier (e.g. kyc_profile_a).

status

string

Overall profile status. Possible values:

incomplete — Required criteria have not yet been submitted.
pending — Under review by SpherePay.
approved — The customer has passed verification and is eligible for transfers.
rejected — Verification was declined.

criteria

object

Granular breakdown of each verification step.

Show criteria properties

complete

string[]

Steps that have been satisfied (e.g. email_address, phone_number, residential_address, tax_identification_number).

pending

string[]

Steps currently under manual review.

required

string[]

Steps still needed before the customer can be submitted for review (e.g. identity_document, liveness_report_document).

errors

string[]

Steps that encountered an error or were rejected and require remediation.

meta

object

Arbitrary key-value metadata associated with the customer.

createdAt

string

ISO 8601 timestamp of when the customer record was created.

updatedAt

string

ISO 8601 timestamp of the most recent update to the customer record.

  "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": {},
  "createdAt": "2026-03-09T20:46:31.305Z",
  "updatedAt": "2026-03-09T20:46:31.305Z"
}

Error codes

Status	Code	Description
`400`	`address/invalid`	The request is malformed.
`404`	`resource/not-found`	No customer exists with the given ID.
`422`	`validation/failed`	The provided ID did not pass format validation.

Documentation Index

​Endpoint

​Authentication

​Path parameters

​Response fields

​Error codes

Endpoint

Authentication

Path parameters

Response fields

Error codes