Retrieve customers which match a specified criteria

GET /V1/customers/search

Retrieve customers which match a specified criteria. This call returns an array of objects, but detailed information about each object’s attributes might not be included. See https://developer.adobe.com/commerce/webapi/rest/attributes#CustomerRepositoryInterface to determine which call to use to get detailed information about all attributes for an object.

Query parameters

searchCriteria[filterGroups][0][filters][0][field] string

Field
searchCriteria[filterGroups][0][filters][0][value] string

Value
searchCriteria[filterGroups][0][filters][0][conditionType] string

Condition type
searchCriteria[sortOrders][0][field] string

Sorting field.
searchCriteria[sortOrders][0][direction] string

Sorting direction.
searchCriteria[pageSize] integer

Page size.
searchCriteria[currentPage] integer

Current page.

Responses

200

200 Success.
Hide response attributes Show response attributes object
- items array[object] Required
  
  Customer entity interface for API handling.
  
  Hide items attributes Show items attributes object
  
  id integer
  
  Customer id
  
  group_id integer
  
  Group id
  
  default_billing string
  
  Default billing address id
  
  default_shipping string
  
  Default shipping address id
  
  confirmation string
  
  Confirmation
  
  created_at string
  
  Created at time
  
  updated_at string
  
  Updated at time
  
  created_in string
  
  Created in area
  
  dob string
  
  In keeping with current security and privacy best practices, be sure you are aware of any potential legal and security risks associated with the storage of customers’ full date of birth (month, day, year) along with other personal identifiers (e.g., full name) before collecting or processing such data.
  
  email string Required
  
  Email address
  
  firstname string Required
  
  First name
  
  lastname string Required
  
  Last name
  
  middlename string
  
  Middle name
  
  prefix string
  
  Prefix
  
  suffix string
  
  Suffix
  
  gender integer
  
  Gender
  
  store_id integer
  
  Store id
  
  taxvat string
  
  Tax Vat
  
  website_id integer
  
  Website id
  
  addresses array[object]
  
  Customer address interface.
  
  Hide addresses attributes Show addresses attributes object
  
  id integer
  
  ID
  
  customer_id integer
  
  Customer ID
  
  region object
  
  Customer address region interface.
  
  Hide region attributes Show region attributes object
  
  region_code string Required
  
  Region code
  
  region string Required
  
  Region
  
  region_id integer Required
  
  Region id
  
  extension_attributes object
  
  ExtensionInterface class for @see \Magento\Customer\Api\Data\RegionInterface
  
  region_id integer
  
  Region ID
  
  country_id string
  
  Country code in ISO_3166-2 format
  
  street array[string]
  
  Street
  
  company string
  
  Company
  
  telephone string
  
  Telephone number
  
  fax string
  
  Fax number
  
  postcode string
  
  Postcode
  
  city string
  
  City name
  
  firstname string
  
  First name
  
  lastname string
  
  Last name
  
  middlename string
  
  Middle name
  
  prefix string
  
  Prefix
  
  suffix string
  
  Suffix
  
  vat_id string
  
  Vat id
  
  default_shipping boolean
  
  If this address is default shipping address.
  
  default_billing boolean
  
  If this address is default billing address
  
  extension_attributes object
  
  ExtensionInterface class for @see \Magento\Customer\Api\Data\AddressInterface
  
  custom_attributes array[object]
  
  Interface for custom attribute value.
  
  Hide custom_attributes attributes Show custom_attributes attributes object
  
  attribute_code string Required
  
  Attribute code
  
  value string Required
  
  Attribute value
  
  disable_auto_group_change integer
  
  Disable auto group change flag.
  
  extension_attributes object
  
  ExtensionInterface class for @see \Magento\Customer\Api\Data\CustomerInterface
  
  Hide extension_attributes attributes Show extension_attributes attributes object
  
  company_attributes object
  
  Extended customer custom attributes interface.
  
  Hide company_attributes attributes Show company_attributes attributes object
  
  customer_id integer
  
  Customer ID.
  
  company_id integer
  
  Company ID.
  
  job_title string
  
  Get job title.
  
  status integer
  
  Customer status.
  
  telephone string
  
  Get telephone.
  
  extension_attributes object
  
  ExtensionInterface class for @see \Magento\Company\Api\Data\CompanyCustomerInterface
  
  is_subscribed boolean
  
  assistance_allowed integer
  
  custom_attributes array[object]
  
  Interface for custom attribute value.
  
  Hide custom_attributes attributes Show custom_attributes attributes object
  
  attribute_code string Required
  
  Attribute code
  
  value string Required
  
  Attribute value
- search_criteria object Required
  
  Search criteria interface.
  
  Hide search_criteria attributes Show search_criteria attributes object
  
  filter_groups array[object] Required
  
  Groups two or more filters together using a logical OR
  
  Hide filter_groups attribute Show filter_groups attribute object
  
  filters array[object]
  
  Filter which can be used by any methods from service layer.
  
  Hide filters attributes Show filters attributes object
  
  field string Required
  
  Field
  
  value string Required
  
  Value
  
  condition_type string
  
  Condition type
  
  sort_orders array[object]
  
  Data object for sort order.
  
  Hide sort_orders attributes Show sort_orders attributes object
  
  field string Required
  
  Sorting field.
  
  direction string Required
  
  Sorting direction.
  
  page_size integer
  
  Page size.
  
  current_page integer
  
  Current page.
- total_count integer Required
  
  Total count.
401

401 Unauthorized
Hide response attributes Show response attributes object
- message string Required
  
  Error message
- errors array[object]
  
  Error details
  
  Hide errors attributes Show errors attributes object
  
  message string
  
  Error message
  
  parameters array[object]
  
  Error parameters item
  
  Hide parameters attributes Show parameters attributes object
  
  resources string
  
  ACL resource
  
  fieldName string
  
  Missing or invalid field name
  
  fieldValue string
  
  Incorrect field value
- code integer
  
  Error code
- parameters array[object]
  
  Error parameters item
  
  Hide parameters attributes Show parameters attributes object
  
  resources string
  
  ACL resource
  
  fieldName string
  
  Missing or invalid field name
  
  fieldValue string
  
  Incorrect field value
- trace string
  
  Stack trace
500

Internal Server error
Hide response attributes Show response attributes object
- message string Required
  
  Error message
- errors array[object]
  
  Error details
  
  Hide errors attributes Show errors attributes object
  
  message string
  
  Error message
  
  parameters array[object]
  
  Error parameters item
  
  Hide parameters attributes Show parameters attributes object
  
  resources string
  
  ACL resource
  
  fieldName string
  
  Missing or invalid field name
  
  fieldValue string
  
  Incorrect field value
- code integer
  
  Error code
- parameters array[object]
  
  Error parameters item
  
  Hide parameters attributes Show parameters attributes object
  
  resources string
  
  ACL resource
  
  fieldName string
  
  Missing or invalid field name
  
  fieldValue string
  
  Incorrect field value
- trace string
  
  Stack trace
default

Unexpected error
Hide response attributes Show response attributes object
- message string Required
  
  Error message
- errors array[object]
  
  Error details
  
  Hide errors attributes Show errors attributes object
  
  message string
  
  Error message
  
  parameters array[object]
  
  Error parameters item
  
  Hide parameters attributes Show parameters attributes object
  
  resources string
  
  ACL resource
  
  fieldName string
  
  Missing or invalid field name
  
  fieldValue string
  
  Incorrect field value
- code integer
  
  Error code
- parameters array[object]
  
  Error parameters item
  
  Hide parameters attributes Show parameters attributes object
  
  resources string
  
  ACL resource
  
  fieldName string
  
  Missing or invalid field name
  
  fieldValue string
  
  Incorrect field value
- trace string
  
  Stack trace

GET /V1/customers/search

curl \
 -X GET https://magento2.winkelstraat.mac/rest/all/V1/customers/search

Response examples (200)

{
  "items": [
    {
      "id": 42,
      "group_id": 42,
      "default_billing": "string",
      "default_shipping": "string",
      "confirmation": "string",
      "created_at": "string",
      "updated_at": "string",
      "created_in": "string",
      "dob": "string",
      "email": "string",
      "firstname": "string",
      "lastname": "string",
      "middlename": "string",
      "prefix": "string",
      "suffix": "string",
      "gender": 42,
      "store_id": 42,
      "taxvat": "string",
      "website_id": 42,
      "addresses": [
        {
          "id": 42,
          "customer_id": 42,
          "region": {
            "region_code": "string",
            "region": "string",
            "region_id": 42,
            "extension_attributes": {}
          },
          "region_id": 42,
          "country_id": "string",
          "street": [
            "string"
          ],
          "company": "string",
          "telephone": "string",
          "fax": "string",
          "postcode": "string",
          "city": "string",
          "firstname": "string",
          "lastname": "string",
          "middlename": "string",
          "prefix": "string",
          "suffix": "string",
          "vat_id": "string",
          "default_shipping": true,
          "default_billing": true,
          "extension_attributes": {},
          "custom_attributes": [
            {
              "attribute_code": "string",
              "value": "string"
            }
          ]
        }
      ],
      "disable_auto_group_change": 42,
      "extension_attributes": {
        "company_attributes": {
          "customer_id": 42,
          "company_id": 42,
          "job_title": "string",
          "status": 42,
          "telephone": "string",
          "extension_attributes": {}
        },
        "is_subscribed": true,
        "assistance_allowed": 42
      },
      "custom_attributes": [
        {
          "attribute_code": "string",
          "value": "string"
        }
      ]
    }
  ],
  "search_criteria": {
    "filter_groups": [
      {
        "filters": [
          {
            "field": "string",
            "value": "string",
            "condition_type": "string"
          }
        ]
      }
    ],
    "sort_orders": [
      {
        "field": "string",
        "direction": "string"
      }
    ],
    "page_size": 42,
    "current_page": 42
  },
  "total_count": 42
}

Response examples (401)

{
  "message": "string",
  "errors": [
    {
      "message": "string",
      "parameters": [
        {
          "resources": "string",
          "fieldName": "string",
          "fieldValue": "string"
        }
      ]
    }
  ],
  "code": 42,
  "parameters": [
    {
      "resources": "string",
      "fieldName": "string",
      "fieldValue": "string"
    }
  ],
  "trace": "string"
}

Response examples (500)

{
  "message": "string",
  "errors": [
    {
      "message": "string",
      "parameters": [
        {
          "resources": "string",
          "fieldName": "string",
          "fieldValue": "string"
        }
      ]
    }
  ],
  "code": 42,
  "parameters": [
    {
      "resources": "string",
      "fieldName": "string",
      "fieldValue": "string"
    }
  ],
  "trace": "string"
}

Response examples (default)

{
  "message": "string",
  "errors": [
    {
      "message": "string",
      "parameters": [
        {
          "resources": "string",
          "fieldName": "string",
          "fieldValue": "string"
        }
      ]
    }
  ],
  "code": 42,
  "parameters": [
    {
      "resources": "string",
      "fieldName": "string",
      "fieldValue": "string"
    }
  ],
  "trace": "string"
}