# Search customers

Find all customer information using specific filters.

**GET** `/v1/customers/search`

## Request parameters

### Query

- `email` (string, required)
  Customer's email.

## Response parameters

- `paging` (object, optional)
  Information for pagination of search results.

  - `paging.limit` (number, optional)
  The maximum number of entries to return.

  - `paging.offset` (number, optional)
  The offset of the first item in the collection to return.

  - `paging.total` (number, optional)
  The total number of items in the collection.

- `results` (array, optional)
  The page of items. This will be an empty array if there are no results.

  - `results[].address` (object, optional)
  Default address's information.

  - `results[].address.id` (string, optional)
  Address ID.

  - `results[].address.street_name` (string, optional)
  Street name.

  - `results[].address.street_number` (number, optional)
  Street number.

  - `results[].address.zip_code` (string, optional)
  Zip code.

  - `results[].addresses` (array, optional)
  Customer's addresses.

  - `results[].cards` (array, optional)
  Customer's cards.

  - `results[].date_created` (string, optional)
  Customer's date created.

  - `results[].date_last_updated` (string, optional)
  Last modified date.

  - `results[].date_registered` (string, optional)
  Customer's registration date.

  - `results[].default_address` (string, optional)
  Customer's default address.

  - `results[].default_card` (string, optional)
  Customer's default card.

  - `results[].description` (string, optional)
  Customer's description.

  - `results[].email` (string, optional)
  Customer's email.

  - `results[].first_name` (string, optional)
  Customer's name.

  - `results[].id` (string, optional)
  Customer ID.

  - `results[].identification` (object, optional)
  Customer identification's information.

  - `results[].identification.number` (string, optional)
  Identification number.

  - `results[].identification.type` (string, optional)
  Identification type.

  - `results[].last_name` (string, optional)
  Customer's last name.

  - `results[].live_mode` (boolean, optional)
  Whether the customers will be in sandbox or in production mode.

  - `results[].metadata` (object, optional)
  metadata

  - `results[].phone` (object, optional)
  Customer phone's information.

  - `results[].phone.area_code` (string, optional)
  Phone's area code.

  - `results[].phone.number` (string, optional)
  Phone number.

## Errors

| Status | Error | Description |
| ------- | ------- | ----------- |
| 400 | 100 | the credentials are required. |
| 400 | 101 | the customer already exist. |
| 400 | 102 | missing customer id. |
| 400 | 103 | parameter must be an object |
| 400 | 104 | parameter length is too large. |
| 400 | 105 | the customer id is invalid. |
| 400 | 106 | the email format is invalid. |
| 400 | 107 | the first_name is invalid. |
| 400 | 108 | the last_name is invalid. |
| 400 | 109 | the phone.area_code is invalid. |
| 400 | 110 | the phone.number is invalid. |
| 400 | 111 | the identification.type is invalid. |
| 400 | 112 | the identification.number is invalid. |
| 400 | 113 | the address.zip_code is invalid. |
| 400 | 114 | the address.street_name is invalid. |
| 400 | 115 | the date_registered format is invalid. |
| 400 | 116 | the description is invalid. |
| 400 | 117 | the metadata is invalid. |
| 400 | 118 | the body must be a Json Object. |
| 400 | 119 | the card is required. |
| 400 | 120 | card not found. |
| 400 | 121 | the card is invalid. |
| 400 | 122 | the card data is invalid. |
| 400 | 123 | the payment_method_id is required. |
| 400 | 124 | the issuer_id is required. |
| 400 | 125 | invalid parameters. |
| 400 | 126 | invalid parameter. You cannot update the email. |
| 400 | 127 | invalid parameter. Cannot resolve the payment method of card, check the payment_method_id and issuer_id. |
| 400 | 128 | the email format is invalid. Use 'test_payer_[0-9]{1,10}@testuser.com'. |
| 400 | 129 | the customer has reached the maximum allowed number of cards. |
| 400 | 140 | invalid card owner. |
| 400 | 150 | invalid users involved. |
| 400 | 200 | invalid range format (range=:date_parameter:after::date_from,before::date_to). |
| 400 | 201 | range attribute must belong to date entity. |
| 400 | 202 | invalid 'after' parameter. It should be date[iso_8601]. |
| 400 | 203 | invalid 'before' parameter. It should be date[iso_8601]. |
| 400 | 204 | invalid filters format. |
| 400 | 205 | invalid query format. |
| 400 | 206 | attributes to sort must belong to 'customer' entity. |
| 400 | 207 | order filter must be 'asc' or 'desc'. |
| 400 | 208 | invalid 'sort' parameter format. |
| 400 | 214 | invalid zip code. |
| 401 | unauthorized | unauthorized. |
| 404 | not_found | not_found. |

## Request example

### cURL

```bash
curl -X GET \
  'https://api.mercadopago.com/v1/customers/search?email=<EMAIL>' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
```

## Response example

```json
{
  "paging": {
  "limit": 10,
  "offset": 0,
  "total": 1
  },
  "results": [
  {
  "address": {
  "id": "1162600213",
  "street_name": "Caetano Poli, 12",
  "street_number": 0,
  "zip_code": "05187010"
  },
  "addresses": [
  {}
  ],
  "cards": [
  {}
  ],
  "date_created": "2017-05-05T04:00:00.000Z",
  "date_last_updated": "2017-05-05T13:23:25.021Z",
  "date_registered": "string",
  "default_address": "1162600213",
  "default_card": 1493990563105,
  "description": "string",
  "email": "test@testuser.com",
  "first_name": "Customer",
  "id": "123456789-jxOV430go9fx2e",
  "identification": {
  "number": "19119119100",
  "type": "DNI"
  },
  "last_name": "Tester",
  "live_mode": true,
  "metadata": {},
  "phone": {
  "area_code": "11",
  "number": "987654321"
  }
  }
  ]
}
```