Customers

Information

For business customer creation please refer to our Customer v1 endpoint

The Customer object stores details about individuals and businesses associated with your application. Customers are typically people who have purchased your products or those who have explicitly registered for transfers within your application.

A Customer can belong to one of two types:

  • individual - A person who interacts with your application.
  • business - An organization or entity registered as a customer.

Since businesses and individuals have different attributes, the structure of the Customer object will vary depending on the type of customer.

Customers can be created in three ways:

  • Automatically via Sphere when a customer completes a transaction through the ramp widget.
  • Automatically via Sphere when a customer makes a payment using a Payment Link.
  • Manually Via API by calling the Create Customer API..

This allows for flexibility in customer registration and management, ensuring that customer data is stored and processed efficiently.

The Customer object

Properties

    Name
    id
    Type
    string
    Description

    A unique identifier for the object.

    Name
    meta
    Type
    object
    Description

    Set of key-value pairs (JSON) that you can attach to a customer object which can be useful for storing additional information about the object.

    Name
    description
    Type
    string
    Description

    The description of your customer. Relevant if the customer is a business.

    Name
    sourceOfFunds
    Type
    string
    Description

    The customer's source of funds. Relevant if the customer is a business.

    Name
    thirdParty
    Type
    boolean
    Description

    Whether the customer is a third party. Relevant if the customer is a business.

    Name
    thirdPartyMessage
    Type
    string
    Description

    The message that the customer is sending to their third party. Relevant if the customer is a business.

    Name
    lookupKey
    Type
    string
    Description

    The lookup key of a customer. A lookup key allows you to list all resources associated with a given key.

    Name
    type
    Type
    enum
    Description

    The type of customer. One of individual or business.

    Name
    kyc
    Type
    enum
    Description

    A status representing the progress of the customer in Sphere's KYC process. One of incomplete, pending, additionalReviewRequired, approved, or rejected.

    Name
    tos
    Type
    enum
    Description

    A status representing the progress of the customer in accepting Sphere's TOS. One of incomplete, pending, or approved.

    Name
    msa
    Type
    enum
    Description

    A status representing the progress of the customer in accepting Sphere's MSA. One of incomplete, pending, approved, declined, or voided.

    Name
    euAccountTos
    Type
    enum
    Description

    A status representing the progress of the customer in accepting Sphere's EU Account TOS. One of incomplete, pending, or approved.

    Name
    operatingResidency
    Type
    enum
    Description

    A status representing the progress of the customer in providing their operating residency. One of incomplete, approved, or rejected.

    Name
    isProhibitedBusinessType
    Type
    boolean
    Description

    Whether the customer is a prohibited business type. Relevant if the customer is a business.

    Name
    website
    Type
    string
    Description

    The customer's website.

    Name
    additionalReviewRequiredReason
    Type
    enum
    Description

    The reason why the customer is receiving an additional review.

    Name
    requirements
    Type
    string array
    Description

    An string array corresponding to fields of information required items required to KYB this customer.

    Name
    address
    Type
    object
    Description

    The customer's address.

    • Name
      line1
      Type
      string
      Description

      Address line 1 (e.g., street, PO Box, or company name).

    • Name
      line2
      Type
      string
      Description

      Address line 2 (e.g., apartment, suite, unit, or building).

    • Name
      city
      Type
      string
      Description

      City, district, suburb, town, or village.

    • Name
      postalCode
      Type
      string
      Description

      ZIP or postal code.

    • Name
      state
      Type
      string
      Description

      Two-letter state code (ISO3166 subdivision code)

    • Name
      country
      Type
      string
      Description

      Three-letter country code (ISO 3166-1 alpha-3).

    Name
    ubos
    Type
    object array
    Description

    A list of ultimate beneficial owners (UBOs) for the customer. Relevant if the customer is a business.

    • Name
      id
      Type
      string
      Description

      Unique identifier for the UBO. Auto-generated by Sphere upon creation.

    • Name
      requirements
      Type
      string array
      Description

      A list of requirements that the UBO is missing.

    • Name
      email
      Type
      string
      Description

      The email of the UBO.

    • Name
      firstName
      Type
      string
      Description

      The first name of the UBO.

    • Name
      lastName
      Type
      string
      Description

      The last name of the UBO.

    • Name
      phoneNumber
      Type
      string
      Description

      The phone number of the UBO.

    • Name
      address
      Type
      object
      Description

      The address of the UBO.

      • Name
        line1
        Type
        string
        Description

        Address line 1 (e.g., street, PO Box, or company name).

      • Name
        line2
        Type
        string
        Description

        Address line 2 (e.g., apartment, suite, unit, or building).

      • Name
        city
        Type
        string
        Description

        City, district, suburb, town, or village.

      • Name
        postalCode
        Type
        string
        Description

        ZIP or postal code.

      • Name
        state
        Type
        string
        Description

        Two-letter state code (ISO3166 subdivision code)

      • Name
        country
        Type
        string
        Description

        Three-letter country code (ISO 3166-1 alpha-3).

    • Name
      created
      Type
      string
      Description

      Datetime of when the UBO was created.

    • Name
      updated
      Type
      string
      Description

      Datetime of when the UBO was last updated.

    Name
    email
    Type
    timestamp
    Description

    The customer's email address.

    Name
    firstName
    Type
    timestamp
    Description

    The customer's first name or the name of the business if the customer is a business.

    Name
    lastName
    Type
    timestamp
    Description

    The customer's last name. Null if the customer is a business.

    Name
    phoneNumber
    Type
    timestamp
    Description

    The customer's phone number in E.164 format.

    Name
    mock
    Type
    boolean
    Description

    Whether the customer is a mock customer. False by default.

    Name
    wallets
    Type
    string array
    Description

    A string array of Sphere wallet IDs associated with this customer.

    Name
    bankAccounts
    Type
    string array
    Description

    A string array of Sphere bank account IDs associated with this customer.

    Name
    achPullUserIntentId
    Type
    string
    Description

    The customer's user intent id. Relevant if the customer is an achPull user.

    Name
    verificationLevels
    Type
    object array
    Description

    A list of verification levels for the customer. Relevant if the customer is an achPull user.

    • Name
      name
      Type
      enum
      Description

      The name of the verification level. Only ach_pull.

    • Name
      status
      Type
      string
      Description

      The status of the verification level. One of approved, pending, retry, document, suspended, rejected, incomplete, or convereted_to_user.

    • Name
      requirements
      Type
      string array
      Description

      A list of requirements that the customer is missing.

    Name
    created
    Type
    string
    Description

    Datetime of when the customer was created.

    Name
    updated
    Type
    datstringestring
    Description

    Datetime of when the customer was last updated.

Customer Object

{
  "id": "customer_800925656fe14c63ac4ec2a98b3cd26d",
  "meta": {},
  "lookupKey": null,
  "type": "individual",
  "kyc": "approved",
  "tos": "approved",
  "msa": "incomplete",
  "euAccountTos": "approved",
  "operatingResidency": "approved",
  "isProhibitedBusinessType": null,
  "website": null,
  "additionalReviewRequiredReason": null,
  "requirements": [
    "address.line1",
    "address.city",
    "address.state",
    "address.postalCode",
    "address.city",
    "address.country"
  ],
  "address": {
    "line1": null,
    "line2": null,
    "city": null,
    "postalCode": null,
    "state": null,
    "country": null
  },
  "ubos": [],
  "email": "johndoe123@gmail.com",
  "firstName": "John",
  "lastName": "Doe",
  "phoneNumber": "+12345678900",
  "mock": false,
  "wallets": [
    "wallet_6107d15c89644518a4bff20915bc9eb2",
    "wallet_c7005f4e271e4b159c10d0b473160694",
    "wallet_32333fda69af40e58d23454f0655f91b"
  ],
  "bankAccounts": [
    "bankAccount_2ff2dcd932764cffbdfb76c2bc32fd1f",
    "bankAccount_c8ec5bdca412485ea50b7f5d1494e4a1",
    "bankAccount_85dd31c407344979a64b8ff27569e33b"
  ],
  "achPullUserIntentId": "aefdada005bb45acb91874f704fc3a72",
  "verificationLevels": [
    {
      "name": "ach_pull",
      "status": "approved",
      "requirements": [
        "address.line1",
        "address.city",
        "address.state",
        "address.postalCode",
        "createUser"
      ]
    }
  ],
  "created": "2024-07-31T23:44:16.319Z",
  "updated": "2024-08-07T22:23:45.817Z"
}
POST/v2/customer

Create a customer

Create a new customer object. For business customers please use the Create Customer API v1. If you provide the proof of address document, proof of identity document, and proof of incorporation document, Sphere will automatically verify the customer.

Content-Type: multipart/formdata

Parameters

    Name
    type
    Type
    string
    Required
    Required
    Description

    The type of customer. individual. For business customers please use the Create Customer API v1.

    Name
    email
    Type
    string
    Required
    Required
    Description

    The customer's email address.

    Name
    phoneNumber
    Type
    string
    Description

    The customer's phone number. Should contain only digits after the country code (e.g., +12345678900).

    Name
    addressLine1
    Type
    string
    Description

    Address line 1 (e.g., street, PO Box, or company name).

    Name
    addressLine2
    Type
    string
    Description

    Address line 2 (e.g., apartment, suite, unit, or building).

    Name
    addressCity
    Type
    string
    Description

    City, district, suburb, town, or village.

    Name
    addressPostalCode
    Type
    string
    Description

    ZIP or postal code.

    Name
    addressState
    Type
    string
    Description

    Two-letter state code (ISO3166 subdivision code)

    Name
    addressCountry
    Type
    string
    Description

    Three-letter country code (ISO 3166-1 alpha-3).

    Name
    firstName
    Type
    string
    Required
    Required
    Description

    The customer's first name.

    Name
    lastName
    Type
    string
    Required
    Required
    Description

    The customer's last name.

    Name
    dobDay
    Type
    string
    Description

    The day of the customer's date of birth.

    Name
    dobMonth
    Type
    string
    Description

    The month of the customer's date of birth.

    Name
    dobYear
    Type
    string
    Description

    The year of the customer's date of birth.

    Name
    ssn
    Type
    string
    Description

    The customer's social security number or any other form of identification such as passport number, driver's license number, etc.

    Name
    proofOfAddressDocument
    Type
    file
    Description

    A file of the customer's proof of address document.

    Name
    identityDocumentFront
    Type
    file
    Description

    A file of the customer's identity document (front). Ex: passport, drivers license, etc.

    Name
    identityDocumentBack
    Type
    file
    Description

    A file of the customer's identity document (back). Ex: passport, drivers license, etc.

Request

POST
/v2/customer
curl https://api.spherepay.co/v2/customer \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: multipart/formdata" \
  -F "type=individual" \
  -F "firstName=John" \
  -F "lastName=Doe" \
  -F "email=johndoe123@gmail.com" \
  -F "phoneNumber=+12345678900" \
  -F "address.line1=123 Main St" \
  -F "address.city=San Francisco" \
  -F "address.postalCode=94107" \
  -F "address.state=CA" \
  -F "address.country=USA" \
  -F "dob.month=3" \
  -F "dob.day=23" \
  -F "dob.year=1990" \
  -F "proofOfAddressDocument=@/path/to/proofOfAddressDocument.png" \
  -F "identityDocumentFront=@/path/to/identityDocumentFront.png" \
  -F "identityDocumentBack=@/path/to/identityDocumentBack.png"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "customer": {
      "id": "customer_8444b807ac58487d9ed2001e830c9e69",
      "meta": {},
      "description": null,
      "sourceOfFunds": null,
      "lookupKey": null,
      "type": "individual",
      "kyc": "incomplete",
      "tos": "incomplete",
      "website": null,
      "additionalReviewRequiredReason": null,
      "requirements": ["customerIdentityDocument", "ssn"],
      "address": {
        "line1": "123 Main St",
        "line2": null,
        "city": "San Francisco",
        "postalCode": "94107",
        "state": "CA",
        "country": "USA"
      },
      "email": "johndoe123@gmail.com",
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "+12345678900",
      "mock": false,
      "wallets": [],
      "bankAccounts": [],
      "achPullUserIntentId": null,
      "verificationLevels": [],
      "created": "2024-08-22T16:13:01.227Z",
      "updated": "2024-08-22T16:13:01.227Z"
    }
  },
  "ts": "2024-08-22T16:13:02.026Z",
  "request": "request_29562171ced84c5ea09df36ef22101e8"
}
GET/v2/customer/:id

Retrieve a customer

This endpoint allows you to retrieve a customer by id.

Request

GET
/v2/customer/:id
# Replace {customer_id} with the id of the customer you want to retrieve
curl -G https://api.spherepay.co/v2/customer/{customer_id} \
  -H "Authorization: Bearer {token}"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "customer": {
      "id": "{customer_id}",
      "meta": {},
      "description": null,
      "sourceOfFunds": null,
      "thirdParty": null,
      "thirdPartyMessage": null,
      "lookupKey": null,
      "type": "individual",
      "kyc": "incomplete",
      "tos": "incomplete",
      "msa": "incomplete",
      "euAccountTos": "incomplete",
      "operatingResidency": "incomplete",
      "isProhibitedBusinessType": null,
      "website": null,
      "additionalReviewRequiredReason": null,
      "requirements": ["customerIdentityDocument", "ssn"],
      "address": {
        "line1": "123 Main St",
        "line2": null,
        "city": "San Francisco",
        "postalCode": "94107",
        "state": "CA",
        "country": "USA"
      },
      "ubos": [],
      "email": "johndoe123@gmail.com",
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "+12345678900",
      "mock": false,
      "wallets": [],
      "bankAccounts": [],
      "achPullUserIntentId": null,
      "verificationLevels": [],
      "created": "2024-08-22T16:13:01.227Z",
      "updated": "2024-08-22T16:13:01.227Z"
    }
  },
  "ts": "2024-08-22T16:15:42.707Z",
  "request": "request_cdde26b2c0534183a1aaba6baebaec1f"
}
GET/v2/customer

Retrieve customer list

This endpoint allows you to retrieve a list of customers of the account.

Request

GET
/v2/customer
curl -G https://api.spherepay.co/v2/customer\
  -H "Authorization: Bearer {token}"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "customers": [{
      "id": "{customer_id}",
      "meta": {},
      "description": null,
      "sourceOfFunds": null,
      "thirdParty": null,
      "thirdPartyMessage": null,
      "lookupKey": null,
      "type": "individual",
      "kyc": "incomplete",
      "tos": "incomplete",
      "msa": "incomplete",
      "euAccountTos": "incomplete",
      "operatingResidency": "incomplete",
      "isProhibitedBusinessType": null,
      "website": null,
      "additionalReviewRequiredReason": null,
      "requirements": ["customerIdentityDocument", "ssn"],
      "address": {
        "line1": "123 Main St",
        "line2": null,
        "city": "San Francisco",
        "postalCode": "94107",
        "state": "CA",
        "country": "USA"
      },
      "ubos": [],
      "email": "johndoe123@gmail.com",
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "+12345678900",
      "mock": false,
      "wallets": [],
      "bankAccounts": [],
      "achPullUserIntentId": null,
      "verificationLevels": [],
      "created": "2024-08-22T16:13:01.227Z",
      "updated": "2024-08-22T16:13:01.227Z"
    }]
  },
  "ts": "2024-08-22T16:15:42.707Z",
  "request": "request_cdde26b2c0534183a1aaba6baebaec1f"
}
POST/v2/customer/:id/tos-link

This endpoint is required to generate a link to the terms of service for a customer.

Request

POST
/v2/customer/:id/tos-link
# Replace {customer_id} with the id of the customer you want to generate the terms of service link for
curl --location --request POST https://api.spherepay.co/v2/customer/{customer_id}/tos-link\
  -H "Authorization: Bearer {token}"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "link": "https://spherepay.co/link-to-terms-of-service"
  },
  "ts": "2024-08-22T16:15:42.707Z",
  "request": "request_cdde26b2c0534183a1aaba6baebaec1f"
}
POST/v2/customer/:id/kyc-link

This endpoint is required to generate a link to perform KYC for a customer.

Request

POST
/v2/customer/:id/kyc-link
# Replace {customer_id} with the id of the customer you want to generate the KYC link for
curl --location --request POST https://api.spherepay.co/v2/customer/{customer_id}/kyc-link\
  -H "Authorization: Bearer {token}"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "customer": "{{customer_id}}",
    "url": "https://spherepay.co/link-to-kyc",
    "expiresAt": "2025-03-25T21:27:41.984Z"
  },
  "ts": "2024-08-22T16:15:42.707Z",
  "request": "request_cdde26b2c0534183a1aaba6baebaec1f"
}
GET/v2/customer/:id/kyc-link

This endpoint is required to retrieve the KYC link for a customer.

Request

GET
/v2/customer/:id/kyc-link
# Replace {customer_id} with the id of the customer you want to retrieve the KYC link for
curl --location --request GET https://api.spherepay.co/v2/customer/{customer_id}/kyc-link\
  -H "Authorization: Bearer {token}"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "customer": "{{customer_id}}",
    "url": "https://spherepay.co/link-to-kyc",
    "expiresAt": "2025-03-25T21:27:41.984Z"
  },
  "ts": "2024-08-22T16:15:42.707Z",
  "request": "request_cdde26b2c0534183a1aaba6baebaec1f"
}

Was this page helpful?