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

# List customers

`GET /customers`

## Request

- Base URL: `https://api.gocardless.com`
- URL: `https://api.gocardless.com/customers`
- Auth: HTTP bearer

Returns a [cursor-paginated](https://docs.gocardless.com/docs/api-reference/data-conventions#cursor-pagination) list of your customers.

## Query parameters

- `before` string, nullable
- `after` string, nullable
- `limit` union
  - integer
  - string
- `created_at` object
  - `gt` string, date-time: Limit to records created after the specified date-time.
  - `lt` string, date-time: Limit to records created before the specified date-time.
  - `gte` string, date-time: Limit to records created on or after the specified date-time.
  - `lte` string, date-time: Limit to records created on or before the specified date-time.
- `sort_field` 'name' | 'company_name' | 'created_at': Field by which to sort records. One of: - `name` - `company_name` - `created_at`
- `sort_direction` 'asc' | 'desc': The direction to sort in. One of: - `asc` - `desc`
- `currency` 'AUD' | 'CAD' | 'DKK' | 'EUR' | 'GBP' | 'NZD' | 'SEK' | 'USD': [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.
- `action_required` 'true' | 'false'

## Headers

- `GoCardless-Version` string, required

## Response `200`

Successful response

- CustomerMultiResourceResponse
  - `customers` Customer[]
    - `id` string: Unique identifier, beginning with "CU".
    - `created_at` string, date-time: Fixed [timestamp](https://docs.gocardless.com/docs/api-reference/data-conventions#dates-and-times), recording when this resource was created.
    - `email` string, nullable: Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer.
    - `given_name` string, nullable: Customer's first name. Required unless a `company_name` is provided.
    - `family_name` string, nullable: Customer's surname. Required unless a `company_name` is provided.
    - `company_name` string, nullable: Customer's company name. Required unless a `given_name` and `family_name` are provided. For Canadian customers, the use of a `company_name` value will mean that any mandate created from this customer will be considered to be a "Business PAD" (otherwise, any mandate will be considered to be a "Personal PAD").
    - `address_line1` string, nullable: The first line of the customer's address.
    - `address_line2` string, nullable: The second line of the customer's address.
    - `address_line3` string, nullable: The third line of the customer's address.
    - `city` string, nullable: The city of the customer's address.
    - `region` string, nullable: The customer's address region, county or department. For US customers a 2 letter [ISO3166-2:US](https://en.wikipedia.org/wiki/ISO_3166-2:US) state code is required (e.g. `CA` for California).
    - `postal_code` string, nullable: The customer's postal code.
    - `country_code` string, nullable: [ISO 3166-1 alpha-2 code.](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)
    - `language` string, nullable: [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see [compliance requirements](https://docs.gocardless.com/docs/api-reference/compliance-requirements)). Currently only "en", "fr", "de", "pt", "es", "it", "nl", "da", "nb", "sl", "sv" are supported. If this is not provided, the language will be chosen based on the `country_code` (if supplied) or default to "en".
    - `phone_number` string, nullable: [ITU E.123](https://en.wikipedia.org/wiki/E.123) formatted phone number, including country code.
    - `swedish_identity_number` string, nullable: For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer's bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.
    - `danish_identity_number` string, nullable: For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer's bank account is denominated in Danish krone (DKK).
    - `metadata` CustomerMetadata: Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
  - `meta` CustomerPaginationMeta: Cursor pagination information
    - `limit` integer, required
    - `cursors` object, required
      - `before` string, nullable, required: Cursor pointing to the end of the desired set.
      - `after` string, nullable, required: Cursor pointing to the start of the desired set.

## Other responses

- `400`: Bad Request
- `401`: Unauthorised
- `404`: Not found
- `422`: Validation Error
- `500`: Internal Error

---

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