# List all customers

Return a list of customers. For single-merchant partners, this returns customers belonging to your sub-merchants. For marketplace partners, this returns customers belonging to your marketplace.

Endpoint: GET /customers
Version: partners-v1
Security: bearerAuth, basicAuth

## Query parameters:

  - `limit` (integer)
    Limit the number of customers returned.

  - `page` (string)
    Specify the page of customers returned.

  - `filter` (object)
    Filter customers by the specified fields.

Filter semantics: `filter[field][operator]=value`.

Available filter operators:
- `eq` - equal (=)
- `ne` - not equal (!=)
- `gt` - greater than (>)
- `gte` - greater than or equal (>=)
- `lt` - less than (<)
- `lte` - less than or equal  (<=)

Filtering is allowed by the following fields:
  - `merchant_id` (`eq`) — only available for single-merchant partners
  - `external_id` (`eq`)
  - `email` (`eq`)
  - `business_name` (`eq`)
  - `created_at` (`eq`, `gt`, `lt`, `gte`, `lte`)
  - `amount_approved` (`eq`, `gt`, `lt`, `gte`, `lte`)
  - `amount_available` (`eq`, `gt`, `lt`, `gte`, `lte`)
  - `amount_authorized` (`eq`, `gt`, `lt`, `gte`, `lte`)
  - `amount_balance` (`eq`, `gt`, `lt`, `gte`, `lte`)
  - `amount_unapplied_payments` (`eq`, `gt`, `lt`, `gte`, `lte`)
  - `advance_rate` (`eq`, `gt`, `lt`, `gte`, `lte`)
  - `archived` (`eq`, `ne`)

Example: `filter[email][eq]=test@resolvepay.com`
Example: `filter[external_id][eq]=CUS-123456`

Note: filter with the `eq` operator is equivalent to the following filter `filter[field]=value`

  - `sort` (string)
    Sort customers by the specified fields.

The sort order for each sort field is ascending unless it is prefixed with a minus,
in which case it is descending.

Multiple sort fields supported by allowing comma-separated sort fields. Sort fields will be applied in the order specified.

Sorting is allowed by the following fields: `id`, `created_at`, `amount_approved`, `amount_available`, `business_name`.

Example: `sort=business_name,-created_at`

## Response 200 fields (application/json):

  - `count` (integer)
    Example: 1

  - `limit` (integer)
    Example: 25

  - `page` (integer)
    Example: 1

  - `results` (array)

  - `results.id` (string)
    Example: PMMlaE5wbg0

  - `results.merchant_id` (string)
    ID of the sub-merchant this customer belongs to. Only present for single-merchant partners.
    Example: MER456789

  - `results.external_id` (string)
    Optional customer identifier from your system. This value is not required to be unique and can be used with the `external_id` list filter.
    Example: CUS-123456

  - `results.created_at` (string)
    Date the customer was created.
    Example: 2020-01-01T00:00:00.750Z

  - `results.updated_at` (string)
    Date the customer was last updated.
    Example: 2020-01-01T00:00:00.750Z

  - `results.source` (string)
    Enum: "QUICKBOOKS", "MERCHANT_USER", "ADMIN_USER", "APPLICATION", "CUSTOMER_USER", "API"

  - `results.business_address` (string)
    Street address of the business' primary location.
    Example: 111 Main Street

  - `results.business_city` (string)
    City of the business' primary location.
    Example: San Francisco

  - `results.business_state` (string)
    State or province of the business' primary location.
    Example: CA

  - `results.business_zip` (string)
    US zip code of the business' primary location.
    Example: 94104

  - `results.business_country` (string)
    Country of the business' primary location according to the **ISO 3166-1 alpha 2** standard.
    Example: US

  - `results.business_age_range` (string)
    String indicating age of the business in years.
    Enum: "0-2", "2-5", "5-10", "10+"

  - `results.business_ap_email` (string)
    Email address of the business' accounts payable person or department.
    Example: ap@example.com

  - `results.business_ap_phone` (string)
    Phone number of the business' accounts payable person or department.
    Example: (202) 456-1414

  - `results.business_ap_phone_extension` (string)
    Phone number extension of the business' accounts payable person or department.
    Example: 123

  - `results.business_name` (string)
    Full legal name of the business being applied for.
    Example: Example, Inc.

  - `results.business_trade_name` (string)
    Trade name of the business, if different than `business_name.`
    Example: Example Trading Company

  - `results.business_phone` (string)
    Phone number of the business' primary location.
    Example: (202) 456-1414

  - `results.business_type` (string)
    String indicating the business' type of legal entity.
    Enum: "sole_prop_or_partnership", "llc", "corporation", "nonprofit", "government"

  - `results.email` (string)
    Email of the customer applying for terms.
    Example: user@example.com

  - `results.personal_name_first` (string)
    First name of the person applying on behalf of the business.
    Example: James

  - `results.personal_name_last` (string)
    Last name of the person applying on behalf of the business.
    Example: Bond

  - `results.personal_phone` (string)
    Personal phone number of the customer representative applying for terms.
    Example: (202) 456-1414

  - `results.amount_approved` (integer)
    Total amount of the credit approved.
    Example: 10000

  - `results.amount_authorized` (integer)
    Amount of the credit line reserved for authorized charges.
    Example: 10000

  - `results.amount_available` (integer)
    Current amount of the credit line available for purchases.
    Example: 10000

  - `results.amount_balance` (integer)
    Current balance on the customer's credit line.
    Example: 2000

  - `results.amount_unapplied_payments` (integer)
    Current amount of a customer's unapplied payments.
    Example: 1000

  - `results.default_terms` (string)
    Set default terms that will apply to this customer's invoices. Can be overridden when requesting an advance.
    Enum: "net7", "net10", "net10th", "net15", "net20", "net30", "net45", "net60", "net75", "net90", "net120", "net180", null

  - `results.advance_rate` (number)
    The advance rate that will be used to determine the amount advanced for this customer's invoices.
    Example: 0.75

  - `results.credit_status` (string)
    Current credit status of this customer. See #request-a-credit-check for more details.
    Enum: "approved", "hold", "declined", "pending", "deactivated", null

  - `results.net_terms_status` (string)
    Current net terms enrollment status of this customer. See #fetchCustomer for more details.
    Enum: "enrolled", "pending_enrollment", "enrollment_expired", null

  - `results.net_terms_enrollment_url` (string)
    The URL for a customer to complete enrollment requirements when net_terms_status is pending_enrollment. See #fetchCustomer for more details.
    Example: www.app.resolvepay.com/merchant-id/activate/123456

  - `results.net_terms_enrollment_expires_at` (string)
    The date by which the customer must be enrolled in this net terms offer, not null when net_terms_status is pending_enrollment.
    Example: 2020-01-01T00:00:00.750Z

  - `results.credit_check_requested_at` (string)
    The date a credit check was requested.
    Example: 2020-01-01T00:00:00.750Z

  - `results.archived` (boolean)
    Boolean indicating if customer is archived.
    Example: false

  - `results.duns_number` (string)
    Dun & Bradstreet unique nine-digit identifier for businesses that is associated with a business's Live Business Identity
    Example: 00-123-4567

  - `results.credit_decisions` (array)
    Array of credit decisions made for this customer.

  - `results.credit_decisions.id` (string)
    Unique identifier for the credit decision.
    Example: abc123

  - `results.credit_decisions.created_at` (string)
    Date the credit decision was created.
    Example: 2020-01-01T00:00:00.750Z

  - `results.credit_decisions.decision` (string)
    The credit decision outcome.
    Enum: "approved", "declined", "hold", "line_adjustment", "deactivate"

  - `results.credit_decisions.amount` (integer)
    The credit amount approved.
    Example: 10000

  - `results.credit_decisions.advance_rate` (number)
    The advance rate for this credit decision.
    Example: 0.75

  - `results.credit_decisions.decline_code` (string)
    Code indicating reason for decline, if applicable.
    Enum: "no_business_found", "thin_file", "failing_credit", "not_approved_need_more_info", "sole_prop", "applicant_business_association", "merchant_risk", "fraud", "no_us_address", "duplicate", "test_account", "email_verification_freemail", "email_verification_domain", "address_verification", "poor_cash_flow", "additional_info_not_provided", "other"

  - `results.credit_decisions.hold_code` (string)
    Code indicating reason for hold, if applicable.
    Enum: "past_due", "failed_payment", "requested_by_customer", "requested_by_merchant", "dispute", "fraud", "churned", "payment_plan", "inactive", "other"

## Response 400 fields (application/json):

  - `error` (object)

  - `error.message` (string)
    A short string, describing error details
    Example: Validation error

  - `error.type` (string)
    A short string, describing error type
    Enum: "validation_error"

  - `error.details` (array)

  - `error.details.path` (string)
    Path to the field failed validation
    Example: path.to.field

  - `error.details.message` (string)
    Detailed description of the error
    Example: `[field]` is required

## Response 401 fields (application/json):

  - `error` (object)

  - `error.message` (string)
    A short string, describing error details
    Example: Invalid merchant credentials

  - `error.type` (string)
    A short string, describing error type
    Enum: "authentication_error"

## Response 429 fields (application/json):

  - `error` (object)

  - `error.message` (string)
    A short string, describing error details
    Example: Too many requests

  - `error.type` (string)
    A short string, describing error type
    Enum: "rate_limit_error"