Retrieve a list of customers

Retrieve a list of customers.

SecuritySecretApiKey or JWT or ApplicationJWT
Request
query Parameters
limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

filter
string

The collection items filter requires a special format. Use "," for multiple allowed values. Use ";" for multiple fields. See the filter guide for more options and examples about this format.

q
string

The partial search of the text fields.

expand
string

Expand a response to get a full related object included inside of the _embedded path in the response. It accepts a comma-separated list of objects to expand. See the expand guide for more info.

fields
string

Limit the returned fields to the list specified, separated by comma. Note that id is always returned.

sort
Array of strings

The collection items sort field and order (prefix with "-" for descending sort).

Responses
200

A list of Customers was retrieved successfully.

Response Headers
Pagination-Total
integer

Total items count.

Example: 332
Pagination-Limit
integer

Items per page limit.

Example: 100
Pagination-Offset
integer

Pagination offset.

Example: 2
Response Schema: application/json
Array
id
string <= 50 characters

The customer identifier string.

email
string <email>

The customer's email.

firstName
string

The customer's first name.

lastName
string

The customer's last name.

websiteId
string <= 50 characters

The website's ID.

Vaulted instrument (object) or Alternative Instrument (object) or Cash (object) or Check (object) (PaymentInstrumentValueObject)
Any of:

Vaulted payment instrument.

method
required
string

The payment method supported vault. See Payment Instruments API.

Enum: "payment-card" "ach" "cash" "check" "paypal" "AdvCash" "Airpay" "Alfa-click" "Alipay" "AmazonPay" … 156 more
paymentInstrumentId
required
string <= 50 characters

The payment instrument identifier.

createdTime
string <date-time>

The customer created time.

updatedTime
string <date-time>

Read-only timestamp updates when the resource is updated.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

object (ContactObject)
firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array of objects (ContactEmails)

The list of emails.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

hash
string <= 40 characters

A hash that can be used to compare multiple contacts for identical attribute values.

object (CustomerAverageValue)
currency
string = 3 characters

Merchant's reporting currency.

amount
number <double>

Average approved payment amount in Merchant's reporting currency.

amountUsd
number <double>

Average approved payment amount in USD.

paymentCount
integer

The number of approved payments for the customer.

lastPaymentTime
string <date-time>

The most recent time of an approved payment for the customer.

object (CustomerLifetimeRevenue)
currency
string = 3 characters

Merchant's reporting currency.

amount
number <double>

Revenue amount in Merchant's reporting currency.

amountUsd
number <double>

Revenue amount in USD.

invoiceCount
integer

An auto-incrementing number based on the sequence of invoices. If set to 0, then this record is a Lead, otherwise is a Customer.

Array of objects (Tag)

A list of customer's tags.

Array
name
required
string <= 255 characters ^[@~\-\.\w\s]+$

The tag is unique name, which is case-insensitive.

type
required
string

The tag type. Tags of a specific type could only be used for the corresponding entity.

Enum: "customer" "kyc-document"
id
string <= 50 characters

The tag's identifier string.

createdTime
string <date-time>

The tag's created time.

updatedTime
string <date-time> (UpdatedTime)

Read-only timestamp updates when the resource is updated.

Array of Self (object) non-empty

The links related to resource.

revision
integer

The number of times the customer data has been modified. The revision is useful when analyzing webhook data to determine if the change takes precedence over the current representation.

isEddRequired
boolean
Default: false

Indicates if EDD is enabled for this customer.

hasFulfilledKyc
boolean

Specifies whether the customer has accepted and reviewed identity and address documents, or an accepted credit file document.

Array of Self (object) or DefaultPaymentInstrumentLink (object) or LeadSourceLink (object) or WebsiteLink (object) >= 3 items

The links related to resource.

Array (>= 3 items)
Any of:
href
required
string

The link URL.

rel
required
string

The link type.

Value: "self"
Array of LeadSourceEmbed (object) non-empty

Any embedded objects available that are requested by the expand querystring parameter.

Array (non-empty)
Any of:

Lead Source object.

object (LeadSource)
401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

get/customers
Request samples
$customers = $client->customers()->search([
    'filter' => 'firstName:John',
]);
Response samples
application/json
[
  • {
    }
]