---
title: "Get a list of Customers of a merchant"
method: GET
path: "/v1/merchants/{merchantId}/customers"
tags: ["customers"]
---

# Get a list of Customers of a merchant

`GET /v1/merchants/{merchantId}/customers`

This endpoint allows a third party to get a list of customers of a merchant.
The list is filtered, showing only the customers that the third party system has access.
Customer id is agent-specific if the customer was created by the agent. The agent needs to be authenticated.

The endpoint will return `HTTP 404 - Not Found` if the merchant with the specified id could not be found.
It will return `HTTP 403 - Forbidden` if the agent is not authenticated or the agent doesn't have permissions.

####Request:
* **merchantId**: Identifier of the merchant
* **offset**: sets the starting element to be returned. Defaults to 0 when unset or malformed.
* **limit**: maximum number of results to be returned. Value must be between 1 and 100. Defaults to 100 when unset, malformed or outside bounds.
* **modifiedSince**: earliest date time of time window in UTC. Format: yyyy-MM-dd HH:mm:ss
* **modifiedUntil**: latest date time of time window in UTC. Format: yyyy-MM-dd HH:mm:ss

####Response:
The response contains the following data of the customer as explained below:
* **id**: The agent-dependent identifier of the customer 
* **title**: The title of the customer. _Optional_
* **firstName**: First name of the customer. _Optional_
* **lastName**: Last name of the customer. _Optional_
* **email**: The given email of this customer. _Optional_
* **gender**: The given gender of the customer (one of MALE, FEMALE, OTHER or UNDEFINED). _Optional_
* **phoneNumber**: The phone number of the customer. _Optional_
* **mobileNumber**: The mobile phone number of the customer. _Optional_
* **locale**: The locale of the customer.
* **links**: Related links that can be followed based on this response
* **subscriptions**: The newsletter subscriptions, e.g. QUANDOO, MERCHANT
* **statistics**: The customer statistics: number of successful, cancelled and no-show reservations
* **createdAt**: The date the customer was created. Format: yyyy-MM-ddTHH:mm:ssZ
* **updatedAt**: The date the customer was last updated. Format: yyyy-MM-ddTHH:mm:ssZ

Example curl:
```
curl https://{host}/v{X}/merchants/1234/customers
```

Example response: 
```
{
  "result": [
    {
      "id": "9ffb3466-3562-42cc-add1-92a46a2f0902",
      "customerRef": "9ffb3466-3562-42cc-add1-92a46a2f0902",
      "marketingFlags": [
        {
          "marketingSettingType": "NEWSLETTERS",
          "marketingSettingStatus": "INACTIVE"
        },
        {
          "marketingSettingType": "PROMO_CODES",
          "marketingSettingStatus": "ACTIVE"
        }
      ],
      "title": "Mr.",
      "firstName": "John",
      "lastName": "Doe",
      "email": "test@quandoo.de",
      "phoneNumber": "+493012345678",
      "mobileNumber": "+17712345678",
      "locale": "de_DE",
      "links": [
        {
          "href": "http://localhost:39250/v1/customers/9ffb3466-3562-42cc-add1-92a46a2f0902/reservations",
          "method": "GET",
          "rel": "get-customer-reservations"
        }
      ],
      "subscriptions": [
        {
          "id": "QUANDOO"
        }
      ],
      "statistics": {
        "reservationSuccessfulCount": 8,
        "reservationCancelledCount": 5,
        "reservationNoShowCount": 2
      },
      "createdAt": "2018-11-22T18:42:16Z",
      "updatedAt": "2018-11-30T18:16:02Z"
    }
  ],
  "offset": 0,
  "limit": 100
}
```

## Path parameters

- `merchantId` integer, required

## Query parameters

- `offset` integer
- `limit` integer
- `modifiedSince` string, date-time
- `modifiedUntil` string, date-time

## Response `200`

OK

## Other responses

- `400` — Bad request
- `403` — Access denied
- `404` — Customer not found
- `500` — Internal server error

---

[API](https://skmtc.net/quandoo/apis/quandooapidocumentation.md) · [All operations](https://skmtc.net/quandoo/apis/quandooapidocumentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/quandoo/quandooapidocumentation/revisions/6863a5956792/schema)