====== CustomerQueryRq (Request) ======

The CustomerQueryRq request allows users to retrieve customer account information from the Fortune3 database. All relevant customer information will be included in the response. It can be used to retrieve all of the customers in the ecommerce database, or a single customer, or a group of customers based on certain conditions (Filters). 

===== Retrieving All Customers =====

Although Fortune3 recommends filtering your requests in order to save bandwidth and response lengths, you can retrieve the information for all of the customers on your ecommerce shopping cart. Proceed as follows:

**Sample Code**:
<code>
<sendRequestXML>
<authenticate>
<APIUsername>TWmY6WBft</APIUsername>
<APIPassword>SKW8ssAmDu6xTGDl</APIPassword>
</authenticate>
<CustomerQueryRq RequestID="1" />
</sendRequestXML>
</code>

===== Retrieving Certain Customers (Using Filters) =====

You can use Filters to limit which customers you get in the response based on certain conditions, and therefore highly optimize the response by shortening it to only include your conditions. Using the <Filters> node, you can specify as many filters as you like that must be matched in order for the Customer to be returned in the response. Since you can specify multiple filters within the same request, and each filter can have different settings, you must also specify individual <Filter> nodes for each filter you want to add to your request. Proceed as Follows:

**Sample Code** (retrieving customer with Email "martha.brady@hotmail.com"):

<code>
<sendRequestXML>
<authenticate>
<APIUsername>TWmY6WBft</APIUsername>
<APIPassword>SKW8ssAmDu6xTGDl</APIPassword>
</authenticate>
<CustomerQueryRq RequestID="1">
  <Filters>
    <Filter>
      <Email>martha.brady@hotmail.com</Email>
    </Filter>
  </Filters>
</CustomerQueryRq>
</sendRequestXML>
</code>

===== Available Filters for CategoryQueryRq =====

^ Tag Name ^ Sub-Tag Of ^ Description                      ^ Field Type ^ Can Repeat ^
| Filters | CustomerQueryRs | The Filters Activation Node | Node | False |
| Filter  | Filters | The Current Filter Node | Node | True |
| CustomerID | Filter | Matches the Customer ID | Number | True |
| CustomerIDFrom | Filter | Returns Customers where Customer ID is >= value | Number | False |
| CustomerIDTo | Filter | Returns Customers where Customer ID is <= value | Number | False |
| DateFrom | Filter | Customers created after this date using EST\\ Time Zone (New York) | Date\\ Format: "YYYY-MM-DD hh:mm:ss" \\ Sample: "2011-04-16 12:32:57" | False |
| DateTo | Filter | Customers created until this date using EST\\ Time Zone (New York) | Date\\ Format: "YYYY-MM-DD hh:mm:ss" \\ Sample: "2011-04-16 12:32:57" | False |
| Email | Filter | Matches Email Address | String | True |
| CustomerType | Filter | Matches the Customer Type | String:\\ * retail\\ * wholesale | False |
| PriceLevel | Filter | Matches the Price Level | String:\\ * Price Level 1\\ * Price Level 2\\ * Price Level 3\\ * Price Level 4\\ * Price Level 5 | True |
| OrderID | Filter | Returns Orders that match the Order ID | Number | True |
| CustomerFName | Filter | Matches the First Name | String | True |
| CustomerLName | Filter | Matches the Last Name | String | True |
| TaxID | Filter | Matches the Federal Tax ID | String | True |

===== Using Multiple Filters =====

You can use multiple filters within a single request by either adding the multiple filters to the same <Filter> node, or by adding separate <Filter> nodes for each filter. By using the same <Filter> node to list multiple filters, you cannot add filtering options and you are therefore limited to the default filtering settings, which is to do an "exact" match of the filter, and to separate each filter with an "or", so that each filter will produce a result independent of the other filters:

**Sample Code** (Customer ID matches "15735" or Customer ID matches "22338" or Customer ID matches "24132"):

<code>
<sendRequestXML>
<authenticate>
<APIUsername>TWmY6WBft</APIUsername>
<APIPassword>SKW8ssAmDu6xTGDl</APIPassword>
</authenticate>
<CustomerQueryRq RequestID="1">
  <Filters>
    <Filter>
      <CustomerID>15735</CustomerID>
      <CustomerID>22338</CustomerID>
      <CustomerID>24132</CustomerID>
    </Filter>
  </Filters>
</CustomerQueryRq>
</sendRequestXML>
</code>

===== Filtering Options =====

However, if you use multiple <Filter> nodes for each filter, you can specify the options for each Filter using Filtering Options. 

There are 2 XML tags that you can use on each filter to specify the options for that filter, <FilterMatch> and <FilterStyle>. 

The 'FilterMatch' tag allows you to specify if you would like to do an "exact" match of the filter (the default), or a "contains" match of the filter, making your condition match if the value you send partially matches the result in the databse (where Name contains "Sony"). 

The 'FilterStyle' tag is only used if you are using more than one <Filter> node and should only be used for the 2nd filter and on (not for the first). It allows you to specify if the current filter you are sending should be matched with an 'or' parameter when following the previous filter (the default), or an 'and' parameter. Using 'and' will make the current filter match in addition to the previous filter (which is why the first filter should not have it), whereas using 'or' (or omitting the 'FilterStyle' since this is the default value) will make the current filter match, whether or not the previous filter matched.

^ Tag Name ^ Sub-Tag Of ^ Description ^ Field Type ^ Allowed Values ^ Can Repeat ^
| FilterStyle | Filter | Specifies if the current filter is\\ independent from the previous filter | String | "or"\\ "and" | False | 
| FilterMatch | Filter | Specifies if the current filter must\\  be an exact match or a "like" match | String | "exact"\\ "contains" | False | 

**Sample Code** (Account Creation Starting Date "2011-03-16 23:59:59" and End Date "2011-03-17 23:59:59"):

<code>
<sendRequestXML>
<authenticate>
<APIUsername>TWmY6WBft</APIUsername>
<APIPassword>SKW8ssAmDu6xTGDl</APIPassword>
</authenticate>
<CustomerQueryRq RequestID="1">
  <Filters>
    <Filter>
      <DateFrom>2011-03-16 23:59:59</DateFrom>
    </Filter>
    <Filter>
      <DateTo>2011-03-17 23:59:59</DateTo>
      <FilterStyle>and</FilterStyle>
    </Filter>
  </Filters>
</CustomerQueryRq>
</sendRequestXML>
</code>

**Sample Code 2** (Creation Starting Date "2011-03-16 23:59:59" and Customer Type "wholesale" and Price Level "Price Level 1"):

<code>
<sendRequestXML>
<authenticate>
<APIUsername>TWmY6WBft</APIUsername>
<APIPassword>SKW8ssAmDu6xTGDl</APIPassword>
</authenticate>
<CustomerQueryRq RequestID="1">
  <Filters>
    <Filter>
      <DateFrom>2011-03-16 23:59:59</DateFrom>
    </Filter>
    <Filter>
      <CustomerType>wholesale</CustomerType>
      <FilterStyle>and</FilterStyle>
    </Filter>
    <Filter>
      <PriceLevel>Price Level 1</PriceLevel>
      <FilterStyle>and</FilterStyle>
    </Filter>
  </Filters>
</CustomerQueryRq>
</sendRequestXML>
</code>

**Sample Code 3** (Customer Name contains "Steve Miller" or Customer Name contains "Kevin Miller"):

<code>
<sendRequestXML>
<authenticate>
<APIUsername>TWmY6WBft</APIUsername>
<APIPassword>SKW8ssAmDu6xTGDl</APIPassword>
</authenticate>
<CustomerQueryRq RequestID="1">
  <Filters>
    <Filter>
      <CustomerFName>Steve</CustomerFName>
      <FilterMatch>contains</FilterMatch>
    </Filter>
    <Filter>
      <CustomerLName>Miller</CustomerLName>
      <FilterMatch>exact</FilterMatch>
      <FilterStyle>and</FilterStyle>
    </Filter>
    <Filter>
      <CustomerFName>Kevin</CustomerFName>
      <FilterMatch>contains</FilterMatch>
      <FilterStyle>or</FilterStyle>
    </Filter>
    <Filter>
      <CustomerLName>Miller</CustomerLName>
      <FilterMatch>exact</FilterMatch>
      <FilterStyle>and</FilterStyle>
    </Filter>
  </Filters>
</CustomerQueryRq>
</sendRequestXML>
</code>

Using these guidelines, you can fully filter out the CustomerQueryRq response to only provide you with the customers that you need.

Next: [[CustomerQueryRs|Reading the Response (CustomerQueryRs)]]