---
title: "List Customers"
method: GET
path: "/v5/customers"
tags: ["Customers"]
---

# List Customers

`GET /v5/customers`

## Request

- Base URL: `https://sandbox.nmi.com/api`
- URL: `https://sandbox.nmi.com/api/v5/customers`
- Auth: API key in header `Authorization`

Retrieve a list of customers for the merchant with optional filtering and cursor-based pagination.

To look up a single customer by its vault ID, use **Get Customer**; to look up a specific billing address, use **Get Billing Address**.

## Query parameters

- `first_name` string
- `last_name` string
- `email` string, email
- `account_number` string
- `date_from` string, date
- `date_to` string, date
- `cursor` string
- `per_page` integer

## Response `200`

Success

- object
  - `customers` CustomerResponse[]
    - `object` 'customer', required: Resource type identifier
    - `id` string, required: Customer vault ID
    - `created` string, date-time, nullable: Customer creation date in UTC ISO 8601 format
    - `billing` object[]: Array of billing addresses
      - `object` 'billing', required: Resource type identifier
      - `id` string, required: Billing address ID (address_name)
      - `first_name` string: First name
      - `last_name` string: Last name
      - `company` string: Company name
      - `address1` string: Address line 1
      - `address2` string: Address line 2
      - `city` string: City
      - `state` string: State or province
      - `zip` string: ZIP or postal code
      - `country` string: Country code (ISO 3166-1 alpha-2)
      - `phone` string: Phone number
      - `email` string, email: Email address
      - `fax` string: Fax number
      - `priority` integer, nullable: Priority of the billing address
      - `payment_details` union: Masked payment method on a customer vault billing record response.
        - object
          - `card_number` string, required: Masked card number
          - `card_exp` string, required: Card expiration date. Format: `MMYY`
        - object
          - `check_account` string: Masked bank account number
          - `check_aba` string: Bank routing number
          - `check_name` string: Name on the ACH account
          - `account_type` 'checking' | 'savings': ACH account type
          - `account_holder_type` 'personal' | 'business': ACH account holder type
          - `sec_code` string: Standard Entry Class code
    - `shipping` object[]: Array of shipping addresses
      - `object` 'shipping', required: Resource type identifier
      - `id` string, required: Shipping address ID (shipping_address_name)
      - `first_name` string: First name
      - `last_name` string: Last name
      - `company` string: Company name
      - `address1` string: Address line 1
      - `address2` string: Address line 2
      - `city` string: City
      - `state` string: State or province
      - `zip` string: ZIP or postal code
      - `country` string: Country code (ISO 3166-1 alpha-2)
      - `phone` string: Phone number
      - `email` string, email: Email address
      - `fax` string: Fax number
      - `priority` integer, nullable: Priority of the shipping address
    - `merchant_defined_fields` MerchantDefinedFields: Custom fields configured in the merchant control panel under Settings → Merchant Defined Fields (`field_1` through `field_20`).
      - `field_1` string: Merchant defined field 1
      - `field_2` string: Merchant defined field 2
      - `field_3` string: Merchant defined field 3
      - `field_4` string: Merchant defined field 4
      - `field_5` string: Merchant defined field 5
      - `field_6` string: Merchant defined field 6
      - `field_7` string: Merchant defined field 7
      - `field_8` string: Merchant defined field 8
      - `field_9` string: Merchant defined field 9
      - `field_10` string: Merchant defined field 10
      - `field_11` string: Merchant defined field 11
      - `field_12` string: Merchant defined field 12
      - `field_13` string: Merchant defined field 13
      - `field_14` string: Merchant defined field 14
      - `field_15` string: Merchant defined field 15
      - `field_16` string: Merchant defined field 16
      - `field_17` string: Merchant defined field 17
      - `field_18` string: Merchant defined field 18
      - `field_19` string: Merchant defined field 19
      - `field_20` string: Merchant defined field 20
  - `per_page` integer
  - `next_cursor` string, nullable: Cursor for the next page. Pass it as the `cursor` parameter on the next request. Omitted when there are no more results.

## Other responses

- `400`: Bad Request - Validation Error. For example, `date_from` or `date_to` is not a valid YYYY-MM-DD calendar date, or an unsupported query parameter was supplied.
- `401`: Unauthorized
- `422`: Unprocessable request. The request was well-formed but cannot be fulfilled as sent — for example, the search matched too many records to return. Narrow the results with filters such as a date range and try again.

---

[API](https://skmtc.dev/nmi/apis/payments-api.md) - [All operations](https://skmtc.dev/nmi/apis/payments-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nmi/apis/payments-api/revisions/c03727f27e27?raw)