logo

Retrieve a customer

Retrieve a customer with specified identifier string.

SecuritySecretApiKey or JWT or ApplicationJWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

query Parameters
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.

Responses
200

Customer was retrieved successfully.

Response Schema: application/json
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
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

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.

404

Resource was not found.

get/customers/{id}
Request samples
$customers = $client->customers()->load('myCustomerId');
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "email": "user@example.com",
  • "firstName": "string",
  • "lastName": "string",
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "defaultPaymentInstrument": {
    },
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "customFields": {
    },
  • "primaryAddress": {
    },
  • "averageValue": {
    },
  • "paymentCount": 0,
  • "lastPaymentTime": "2019-08-24T14:15:22Z",
  • "lifetimeRevenue": {
    },
  • "invoiceCount": 0,
  • "tags": [
    ],
  • "revision": 0,
  • "isEddRequired": false,
  • "hasFulfilledKyc": true,
  • "_links": [
    ],
  • "_embedded": [
    ]
}
➔ Next to Upsert a customer with predefined ID