shop.customer.search

Performs the search of customers, i.e. contacts who have at least one order. Access level 'customers' is required.

Parameters

  • hash GET Optional

    Customer search condition hash string encoded for safe use in URLs. An empty hash corresponds to the 'all' hash meaning a complete list of customers.

    Hash examples:
    - search/firstname=John: search by value 'John' of the field 'firstname' in the 'wa_contact' table. a condition operator instead of '=' in this example you can also use the following: '=' (matching value), '*=' (partial matching of a string value), '^=' (matching beginning of a string value), '=$' (matching ending of a string value), '!=' (no matching), math operators '<', '=', '>', '<=', '>='. You can perform search by several fields using the '&' character; e.g., 'search/firstname=John&birth_year>=2000'.
    - search/name*=John Peter: search by partial matching of name parts to subqueries separated by whitespace characters. In this example found will be all customers whose full names contain both words in any combinations; e.g., 'John Petersen', 'Peter Johnson'. If only one of the specified words is found in a customer’s name then such a customer is not included in the returned result.
    - search/email=ivan.petrov@domain.ru: search by full email address.
    - search/email$=@domain.ru: search by a part of an email address.
    - search/category=1: search by a customer category ID.
    - search/address:country=rus: search by a 3-letter country code from the customer address.
    - search/address:country*=United: search by the beginning of a localized country name in the address.
    - search/address:region=usa:AL: search by a country (in this example 'rus') and a region code ('AL') in the address.
    - search/address:region*=ALA: search by a part of a region name in the address.
    - search/phone=110011122333: search by a phone number.
    - search/phone.home=110011122333: search by a phone number including a number type (in this example 'home').
    - search/phone^=1100: search by a part of a phone number.
    - search/phone^=0100: search by a part of a phone number with the country code replaced with an NDD; works only if the specified NDD (in this example 0) is saved in the authorization settings of any website.

  • offset GET+POST Optional

    Offset relative to the beginning of the list of found customers. Non-negative integer. Default value: 0.

  • sort GET+POST Optional

    Description of the sort order of the returned customers by one of the 'wa_contact' or 'shop_customer' fields, optionally followed by a whitespace and 'ASC' (ascending order) or 'DESC' (descending order) identifiers. Default sort order value is 'name ASC'.

  • format GET Optional

    Sets response format. Available options: json (default), xml.

Return value

Array of values with the following keys:

  • offset int Value of the offset parameter.
  • limit int Value of the limit parameter.
  • sort string Sort order for the found list of customers in the “field direction” format.
  • customers array The list of found customers. A sub-array of each customer contains values with the following keys:
  • customers[]['id'] int Contact ID.
  • customers[]['name'] string Full name.
  • customers[]['firstname'] string First name.
  • customers[]['middlename'] string Middle name.
  • customers[]['lastname'] string Last name.
  • customers[]['title'] string Title.
  • customers[]['company'] string Company name.
  • customers[]['is_company'] int Flag (0 or 1) denoting whether a customer is saved as a company (legal entity).
  • customers[]['sex'] string Gender: 'm' — male, 'f' — female.
  • customers[]['birth_day'] int Number of day in the birth date.
  • customers[]['birth_month'] int Number of month in the birth date.
  • customers[]['birth_year'] int Number of year in the birth date.
  • customers[]['create_datetime'] datetime Contact’s creation date and time in the “yyyy-mm-dd hh-mm-dd” format.
  • customers[]['locale'] string Locale ID.
  • customers[]['contact_id'] int ID of the Webasyst account user who has added a customer.
  • customers[]['total_spent'] float Total sum of all paid orders, expressed in the main store currency.
  • customers[]['affiliate_bonus'] float Number of bonuses accrued by a loyalty program participant.
  • customers[]['number_of_orders'] int Number of placed orders.
  • customers[]['last_order_id'] int ID of the last placed order.
  • customers[]['photo_url_40'] string URL of the customer’s image with the 40x40 px dimensions.
  • customers[]['photo_url_96'] string URL of the customer’s image with the 96x96 px dimensions.
  • customers[]['email'] array Array of email addresses.
  • customers[]['address'] array Postal address list. The sub-array of each address contains a single item with the data key, which contains a sub-array with the following keys:
  • customers[]['address']['data']['country'] string 3-letter country code.
  • customers[]['address']['data']['zip'] string ZIP code.
  • customers[]['address']['data']['region'] string Region code.
  • customers[]['address']['data']['city'] string Locality name.
  • customers[]['address']['data']['street'] string Street address.
  • customers[]['phone'] array Phone number list. The sub-array of each number contains values with the following keys:
  • customers[]['phone']['value'] int Phone number containing only of digits stripped of with all other characters; e.g., 11001234567.
  • customers[]['phone']['formatted'] string Formatted phone number; e.g., +1 (100) 123-45-67.
  • customers[]['contact_type'] string Customer type: 'person' or 'company' (legal entity).
  • count int Number of found customers.

Example

https://demo1.webasyst.com/api.php/shop.customer.search?