Customers
The Customer object stores information about your businesses and individuals associated with your Application. Customers are people who have purchased your products or explictly registered to transfers on your Application.
Customers can be of two types:
individual
- A person.business
- An organization or entity.
The shape of the Customer object will vary depending on the type
of customer.
They can be created in one of three ways:
- Automatically via Sphere, when customers go through your ramp widget.
- Automatically via Sphere, when customers pay for a
product
viapaymentLink
. - Via API, by you, the developer.
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
orbusiness
.
- Name
kyc
- Type
- enum
- Description
A status representing the progress of the customer in Sphere's KYC process. One of
incomplete
,pending
,additionalReviewRequired
,approved
, orrejected
.
- Name
tos
- Type
- enum
- Description
A status representing the progress of the customer in accepting Sphere's TOS. One of
incomplete
,pending
, orapproved
.
- Name
msa
- Type
- enum
- Description
A status representing the progress of the customer in accepting Sphere's MSA. One of
incomplete
,pending
,approved
,declined
, orvoided
.
- Name
euAccountTos
- Type
- enum
- Description
A status representing the progress of the customer in accepting Sphere's EU Account TOS. One of
incomplete
,pending
, orapproved
.
- Name
operatingResidency
- Type
- enum
- Description
A status representing the progress of the customer in providing their operating residency. One of
incomplete
,approved
, orrejected
.
- 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
, orconvereted_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"
}
Create a customer
Parameters
- Name
type
- Type
- enum
- Description
The type of customer. Either
individual
orbusiness
.
- 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
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
email
- Type
- string
- Description
The customer's email address.
- Name
website
- Type
- string
- Description
The website of the customer.
- Name
phoneNumber
- Type
- string
- Description
The customer's phone number.
- 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
proofOfAddressDocument
- Type
- string
- Description
A base64 encoded string of the customer's proof of address document.
For Individual Customers
- Name
firstName
- Type
- string
- Description
The customer's first name.
- Name
lastName
- Type
- string
- Description
The customer's last name.
- Name
dob
- Type
- object
- Description
The customer's date of birth.
- Name
day
- Type
- number
- Description
The day of the customer's date of birth.
- Name
month
- Type
- number
- Description
The month of the customer's date of birth.
- Name
year
- Type
- number
- Description
The year of the customer's date of birth.
- Name
ssn
- Type
- string
- Description
The customer's social security number.
- Name
identityDocumentFront
- Type
- string
- Description
A base64 encoded string of the customer's identity document (front). Ex: passport, drivers license, etc.
- Name
identityDocumentBack
- Type
- string
- Description
A base64 encoded string of the customer's identity document. (back) Ex: passport, drivers license, etc.
For Business Customers
- Name
businessType
- Type
- enum
- Description
The type of business. One of
individual
,business
.
- Name
ein
- Type
- string
- Description
The business's employer identification number (EIN).
- Name
name
- Type
- string
- Description
The business's legal name.
- Name
description
- Type
- string
- Description
The business's description.
- Name
thirdParty
- Type
- boolean
- Description
Whether the business is a third party.
- Name
thirdPartyMessage
- Type
- string
- Description
The message that the business is sending to their third party. Relevant if the business is a third party.
- Name
tosAccepted
- Type
- boolean
- Description
Whether the business has accepted the TOS.
- Name
ubos
- Type
- object array
- Description
A list of ultimate beneficial owners (UBOs) for the business.
- Name
firstName
- Type
- string
- Description
The customer's first name.
- Name
lastName
- Type
- string
- Description
The customer's last name.
- Name
dob
- Type
- object
- Description
The customer's date of birth.
- Name
day
- Type
- number
- Description
The day of the customer's date of birth.
- Name
month
- Type
- number
- Description
The month of the customer's date of birth.
- Name
year
- Type
- number
- Description
The year of the customer's date of birth.
- Name
ssn
- Type
- string
- Description
The customer's social security number.
- Name
business
- Type
- string
- Description
The id of a business customer object associated with the individual customer. Relevant if the individual customer is a UBO.
- Name
identityDocumentFront
- Type
- string
- Description
A base64 encoded string of the customer's identity document (front). Ex: passport, drivers license, etc.
- Name
identityDocumentBack
- Type
- string
- Description
A base64 encoded string of the customer's identity document. (back) Ex: passport, drivers license, etc.
- Name
incorporationDocument
- Type
- string
- Description
A base64 encoded string of the customer's incorporation document.
- Name
shareholderDocument
- Type
- string
- Description
A base64 encoded string of the customer's shareholder document.
- Name
statementOfFunds
- Type
- string
- Description
A base64 encoded string of the customer's statement of funds document.
- Name
estimatedAnnualRevenueUsd
- Type
- number
- Description
The estimated annual revenue of the business in USD.
- Name
expectedMonthlyPaymentsUsd
- Type
- number
- Description
The expected monthly payments of the business.
- Name
operatesInProhibitedCountries
- Type
- boolean
- Description
Whether the business operates in prohibited countries.
- Name
highRiskActivities
- Type
- string array
- Description
The high risk activities of the business. One of
none_of_the_above
,adult_entertainment
,gambling
,hold_client_funds
,investment_activities
,lending_banking
,marijuana_or_related_services
,money_services
,operate_foreign_exchange_virtual_currencies_brokerage_otc
,safe_deposit_box_rentals
,third_party_payment_processing
, orweapons_firearms_and_explosives
.
- Name
sourceOfFundsDescription
- Type
- enum
- Description
The description of the business's source of funds.
- Name
transmitsCustomerFunds
- Type
- boolean
- Description
Whether the business transmits customer funds.
- Name
transmitsCustomerFundsDescription
- Type
- string
- Description
The description of the business transmitting customer funds.
Request
curl https://api.spherepay.co/v1/customer \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"type": "individual",
"firstName": "John",
"lastName": "Doe",
"email": "johndoe123@gmail.com",
"phoneNumber": "+12345678900",
"address": {
"line1": "123 Main St",
"city": "San Francisco",
"postalCode": "94107",
"state": "CA",
"country": "USA"
},
"dob": {
"month": 3,
"day": 23,
"year": 1990
}
}'
Response
{
"ok": true,
"object": "object",
"statusCode": 200,
"error": null,
"message": "success",
"data": {
"customer": {
"id": "customer_8444b807ac58487d9ed2001e830c9e69",
"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:13:02.026Z",
"request": "request_29562171ced84c5ea09df36ef22101e8"
}
Retrieve a customer
This endpoint allows you to retrieve a customer by id.
Request
curl -G https://api.spherepay.co/v1/customer/customer_8444b807ac58487d9ed2001e830c9e69 \
-H "Authorization: Bearer {token}"
Response
{
"ok": true,
"object": "object",
"statusCode": 200,
"error": null,
"message": "success",
"data": {
"customer": {
"id": "customer_8444b807ac58487d9ed2001e830c9e69",
"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"
}
Update a customer
This endpoint allows you to update a customer. Any parameters not provided are left unchanged. You can not update a customer that has already been KYCd.
Parameters
- Name
type
- Type
- enum
- Description
The type of customer. Either
individual
orbusiness
.
- 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
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
email
- Type
- string
- Description
The customer's email address.
- Name
website
- Type
- string
- Description
The website of the customer.
- Name
phoneNumber
- Type
- string
- Description
The customer's phone number.
- 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
proofOfAddressDocument
- Type
- string
- Description
A base64 encoded string of the customer's proof of address document.
For Individual Customers
- Name
firstName
- Type
- string
- Description
The customer's first name.
- Name
lastName
- Type
- string
- Description
The customer's last name.
- Name
dob
- Type
- object
- Description
The customer's date of birth.
- Name
day
- Type
- number
- Description
The day of the customer's date of birth.
- Name
month
- Type
- number
- Description
The month of the customer's date of birth.
- Name
year
- Type
- number
- Description
The year of the customer's date of birth.
- Name
ssn
- Type
- string
- Description
The customer's social security number.
- Name
identityDocumentFront
- Type
- string
- Description
A base64 encoded string of the customer's identity document (front). Ex: passport, drivers license, etc.
- Name
identityDocumentBack
- Type
- string
- Description
A base64 encoded string of the customer's identity document. (back) Ex: passport, drivers license, etc.
- Name
actingAsIntermediary
- Type
- boolean
- Description
Whether the customer is acting as an intermediary.
- Name
employmentStatus
- Type
- string
- Description
The customer's employment status.
- Name
expectedMonthlyPayments
- Type
- string
- Description
The customer's expected monthly payments.
- Name
mostRecentOccupation
- Type
- string
- Description
The customer's most recent occupation.
For Business Customers
- Name
businessType
- Type
- enum
- Description
The type of business. One of
individual
,business
.
- Name
ein
- Type
- string
- Description
The business's employer identification number (EIN).
- Name
name
- Type
- string
- Description
The business's legal name.
- Name
description
- Type
- string
- Description
The business's description.
- Name
thirdParty
- Type
- boolean
- Description
Whether the business is a third party.
- Name
thirdPartyMessage
- Type
- string
- Description
The message that the business is sending to their third party. Relevant if the business is a third party.
- Name
tosAccepted
- Type
- boolean
- Description
Whether the business has accepted the TOS.
- Name
ubos
- Type
- object array
- Description
A list of ultimate beneficial owners (UBOs) for the business.
- Name
firstName
- Type
- string
- Description
The customer's first name.
- Name
lastName
- Type
- string
- Description
The customer's last name.
- Name
dob
- Type
- object
- Description
The customer's date of birth.
- Name
day
- Type
- number
- Description
The day of the customer's date of birth.
- Name
month
- Type
- number
- Description
The month of the customer's date of birth.
- Name
year
- Type
- number
- Description
The year of the customer's date of birth.
- Name
ssn
- Type
- string
- Description
The customer's social security number.
- Name
business
- Type
- string
- Description
The id of a business customer object associated with the individual customer. Relevant if the individual customer is a UBO.
- Name
identityDocumentFront
- Type
- string
- Description
A base64 encoded string of the customer's identity document (front). Ex: passport, drivers license, etc.
- Name
identityDocumentBack
- Type
- string
- Description
A base64 encoded string of the customer's identity document. (back) Ex: passport, drivers license, etc.
- Name
actingAsIntermediary
- Type
- boolean
- Description
Whether the customer is acting as an intermediary.
- Name
employmentStatus
- Type
- string
- Description
The customer's employment status.
- Name
expectedMonthlyPayments
- Type
- string
- Description
The customer's expected monthly payments.
- Name
mostRecentOccupation
- Type
- string
- Description
The customer's most recent occupation.
- Name
incorporationDocument
- Type
- string
- Description
A base64 encoded string of the customer's incorporation document.
- Name
shareholderDocument
- Type
- string
- Description
A base64 encoded string of the customer's shareholder document.
- Name
statementOfFunds
- Type
- string
- Description
A base64 encoded string of the customer's statement of funds document.
- Name
estimatedAnnualRevenueUsd
- Type
- enum
- Description
The estimated annual revenue of the business. One of
_0_99999
,_100000_999999
,_1000000_9999999
,_10000000_49999999
,_50000000_249999999
,_250000000_plus
.
- Name
expectedMonthlyPaymentsUsd
- Type
- number
- Description
The expected monthly payments of the business.
- Name
operatesInProhibitedCountries
- Type
- boolean
- Description
Whether the business operates in prohibited countries.
- Name
highRiskActivities
- Type
- string array
- Description
The high risk activities of the business. One of
none_of_the_above
,adult_entertainment
,gambling
,hold_client_funds
,investment_activities
,lending_banking
,marijuana_or_related_services
,money_services
,operate_foreign_exchange_virtual_currencies_brokerage_otc
,safe_deposit_box_rentals
,third_party_payment_processing
, orweapons_firearms_and_explosives
.
- Name
sourceOfFundsDescription
- Type
- enum
- Description
The description of the business's source of funds.
- Name
transmitsCustomerFunds
- Type
- boolean
- Description
Whether the business transmits customer funds.
- Name
transmitsCustomerFundsDescription
- Type
- string
- Description
The description of the business transmitting customer funds.
Request
curl https://api.spherepay.co/v1/customer/customer_8444b807ac58487d9ed2001e830c9e69 \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"website": "https://www.example.com",
"meta": {
"key": "value"
},
"ssn": "111-11-1111"
}'
Response
{
"ok": true,
"object": "object",
"statusCode": 200,
"error": null,
"message": "success",
"data": {
"customer": {
"id": "customer_8444b807ac58487d9ed2001e830c9e69",
"meta": { "key": "value" },
"description": null,
"sourceOfFunds": null,
"thirdParty": null,
"thirdPartyMessage": null,
"lookupKey": null,
"type": "individual",
"kyc": "pending",
"tos": "incomplete",
"msa": "incomplete",
"euAccountTos": "incomplete",
"operatingResidency": "incomplete",
"isProhibitedBusinessType": null,
"website": "https://www.example.com",
"additionalReviewRequiredReason": null,
"requirements": ["customerIdentityDocument"],
"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": [
{
"name": "ach_pull",
"status": "incomplete",
"requirements": ["ipAddress", "createUserIntent"]
}
],
"created": "2024-08-22T16:13:01.227Z",
"updated": "2024-08-22T16:42:51.145Z"
}
},
"ts": "2024-08-22T16:42:51.155Z",
"request": "request_fdbd4080334249879331982e2b292e62"
}