Magento2

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

      Customers list.

      Hide items attributes Show items attributes object

      Customer entity interface for API handling.

      • 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 addresses.

        Hide addresses attributes Show addresses attributes object

        Customer address interface.

        • 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]

          Custom attributes values.

          Hide custom_attributes attributes Show custom_attributes attributes object

          Interface for custom attribute value.

          • 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]

        Custom attributes values.

        Hide custom_attributes attributes Show custom_attributes attributes object

        Interface for custom attribute value.

        • 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

        A list of filter groups.

        Hide filter_groups attribute Show filter_groups attribute object

        Groups two or more filters together using a logical OR

        • filters array[object]

          A list of filters in this group

          Hide filters attributes Show filters attributes object

          Filter which can be used by any methods from service layer.

          • field string Required

            Field

          • value string Required

            Value

          • condition_type string

            Condition type

      • sort_orders array[object]

        Sort order.

        Hide sort_orders attributes Show sort_orders attributes object

        Data object for sort order.

        • 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.

    Hide response attributes Show response attributes object
    • items array[object] Required

      Customers list.

      Hide items attributes Show items attributes object

      Customer entity interface for API handling.

      • 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 addresses.

        Hide addresses attributes Show addresses attributes object

        Customer address interface.

        • 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]

          Custom attributes values.

          Hide custom_attributes attributes Show custom_attributes attributes object

          Interface for custom attribute value.

          • 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]

        Custom attributes values.

        Hide custom_attributes attributes Show custom_attributes attributes object

        Interface for custom attribute value.

        • 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

        A list of filter groups.

        Hide filter_groups attribute Show filter_groups attribute object

        Groups two or more filters together using a logical OR

        • filters array[object]

          A list of filters in this group

          Hide filters attributes Show filters attributes object

          Filter which can be used by any methods from service layer.

          • field string Required

            Field

          • value string Required

            Value

          • condition_type string

            Condition type

      • sort_orders array[object]

        Sort order.

        Hide sort_orders attributes Show sort_orders attributes object

        Data object for sort order.

        • 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]

      Errors list

      Hide errors attributes Show errors attributes object

      Error details

      • message string

        Error message

      • parameters array[object]

        Error parameters list

        Hide parameters attributes Show parameters attributes object

        Error parameters item

        • 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 list

      Hide parameters attributes Show parameters attributes object

      Error parameters item

      • resources string

        ACL resource

      • fieldName string

        Missing or invalid field name

      • fieldValue string

        Incorrect field value

    • trace string

      Stack trace

    Hide response attributes Show response attributes object
    • message string Required

      Error message

    • errors array[object]

      Errors list

      Hide errors attributes Show errors attributes object

      Error details

      • message string

        Error message

      • parameters array[object]

        Error parameters list

        Hide parameters attributes Show parameters attributes object

        Error parameters item

        • 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 list

      Hide parameters attributes Show parameters attributes object

      Error parameters item

      • 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]

      Errors list

      Hide errors attributes Show errors attributes object

      Error details

      • message string

        Error message

      • parameters array[object]

        Error parameters list

        Hide parameters attributes Show parameters attributes object

        Error parameters item

        • 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 list

      Hide parameters attributes Show parameters attributes object

      Error parameters item

      • resources string

        ACL resource

      • fieldName string

        Missing or invalid field name

      • fieldValue string

        Incorrect field value

    • trace string

      Stack trace

    Hide response attributes Show response attributes object
    • message string Required

      Error message

    • errors array[object]

      Errors list

      Hide errors attributes Show errors attributes object

      Error details

      • message string

        Error message

      • parameters array[object]

        Error parameters list

        Hide parameters attributes Show parameters attributes object

        Error parameters item

        • 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 list

      Hide parameters attributes Show parameters attributes object

      Error parameters item

      • 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]

      Errors list

      Hide errors attributes Show errors attributes object

      Error details

      • message string

        Error message

      • parameters array[object]

        Error parameters list

        Hide parameters attributes Show parameters attributes object

        Error parameters item

        • 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 list

      Hide parameters attributes Show parameters attributes object

      Error parameters item

      • resources string

        ACL resource

      • fieldName string

        Missing or invalid field name

      • fieldValue string

        Incorrect field value

    • trace string

      Stack trace

    Hide response attributes Show response attributes object
    • message string Required

      Error message

    • errors array[object]

      Errors list

      Hide errors attributes Show errors attributes object

      Error details

      • message string

        Error message

      • parameters array[object]

        Error parameters list

        Hide parameters attributes Show parameters attributes object

        Error parameters item

        • 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 list

      Hide parameters attributes Show parameters attributes object

      Error parameters item

      • 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 \
 --request 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 (200) 
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <items type="array">
    <item>
      <id type="integer">42</id>
      <group-id type="integer">42</group-id>
      <default-billing>string</default-billing>
      <default-shipping>string</default-shipping>
      <confirmation>string</confirmation>
      <created-at>string</created-at>
      <updated-at>string</updated-at>
      <created-in>string</created-in>
      <dob>string</dob>
      <email>string</email>
      <firstname>string</firstname>
      <lastname>string</lastname>
      <middlename>string</middlename>
      <prefix>string</prefix>
      <suffix>string</suffix>
      <gender type="integer">42</gender>
      <store-id type="integer">42</store-id>
      <taxvat>string</taxvat>
      <website-id type="integer">42</website-id>
      <addresses type="array">
        <address>
          <id type="integer">42</id>
          <customer-id type="integer">42</customer-id>
          <region>
            <region-code>string</region-code>
            <region>string</region>
            <region-id type="integer">42</region-id>
            <extension-attributes>
            </extension-attributes>
          </region>
          <region-id type="integer">42</region-id>
          <country-id>string</country-id>
          <street type="array">
            <street>string</street>
          </street>
          <company>string</company>
          <telephone>string</telephone>
          <fax>string</fax>
          <postcode>string</postcode>
          <city>string</city>
          <firstname>string</firstname>
          <lastname>string</lastname>
          <middlename>string</middlename>
          <prefix>string</prefix>
          <suffix>string</suffix>
          <vat-id>string</vat-id>
          <default-shipping type="boolean">true</default-shipping>
          <default-billing type="boolean">true</default-billing>
          <extension-attributes>
          </extension-attributes>
          <custom-attributes type="array">
            <custom-attribute>
              <attribute-code>string</attribute-code>
              <value>string</value>
            </custom-attribute>
          </custom-attributes>
        </address>
      </addresses>
      <disable-auto-group-change type="integer">42</disable-auto-group-change>
      <extension-attributes>
        <company-attributes>
          <customer-id type="integer">42</customer-id>
          <company-id type="integer">42</company-id>
          <job-title>string</job-title>
          <status type="integer">42</status>
          <telephone>string</telephone>
          <extension-attributes>
          </extension-attributes>
        </company-attributes>
        <is-subscribed type="boolean">true</is-subscribed>
        <assistance-allowed type="integer">42</assistance-allowed>
      </extension-attributes>
      <custom-attributes type="array">
        <custom-attribute>
          <attribute-code>string</attribute-code>
          <value>string</value>
        </custom-attribute>
      </custom-attributes>
    </item>
  </items>
  <search-criteria>
    <filter-groups type="array">
      <filter-group>
        <filters type="array">
          <filter>
            <field>string</field>
            <value>string</value>
            <condition-type>string</condition-type>
          </filter>
        </filters>
      </filter-group>
    </filter-groups>
    <sort-orders type="array">
      <sort-order>
        <field>string</field>
        <direction>string</direction>
      </sort-order>
    </sort-orders>
    <page-size type="integer">42</page-size>
    <current-page type="integer">42</current-page>
  </search-criteria>
  <total-count type="integer">42</total-count>
</root>
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 (401) 
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <message>string</message>
  <errors type="array">
    <error>
      <message>string</message>
      <parameters type="array">
        <parameter>
          <resources>string</resources>
          <fieldName>string</fieldName>
          <fieldValue>string</fieldValue>
        </parameter>
      </parameters>
    </error>
  </errors>
  <code type="integer">42</code>
  <parameters type="array">
    <parameter>
      <resources>string</resources>
      <fieldName>string</fieldName>
      <fieldValue>string</fieldValue>
    </parameter>
  </parameters>
  <trace>string</trace>
</root>
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 (500) 
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <message>string</message>
  <errors type="array">
    <error>
      <message>string</message>
      <parameters type="array">
        <parameter>
          <resources>string</resources>
          <fieldName>string</fieldName>
          <fieldValue>string</fieldValue>
        </parameter>
      </parameters>
    </error>
  </errors>
  <code type="integer">42</code>
  <parameters type="array">
    <parameter>
      <resources>string</resources>
      <fieldName>string</fieldName>
      <fieldValue>string</fieldValue>
    </parameter>
  </parameters>
  <trace>string</trace>
</root>
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"
}
Response examples (default) 
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <message>string</message>
  <errors type="array">
    <error>
      <message>string</message>
      <parameters type="array">
        <parameter>
          <resources>string</resources>
          <fieldName>string</fieldName>
          <fieldValue>string</fieldValue>
        </parameter>
      </parameters>
    </error>
  </errors>
  <code type="integer">42</code>
  <parameters type="array">
    <parameter>
      <resources>string</resources>
      <fieldName>string</fieldName>
      <fieldValue>string</fieldValue>
    </parameter>
  </parameters>
  <trace>string</trace>
</root>