"Get Customers" API


	"Get Customers" API
	Last Edited - 03/9/2015 8:36am PDT
	Category Path - Developer's Guide > APIs

Modular Merchant Gold (and higher) account plans have access to a "Get Customers" APIs that allow a remotely-hosted website to search for customers and/or retrieve the details of a specified set of customers.

All requests to retrieve customer data should be submitted to the "Get Customers" API URL, located in your online store. An example of the URL for this API would look something like this: http://www.mystore.com/api/get_customers.php

When searching for customers, the search criteria should be specified in the search_rule section of the XML request. See the Search Options section below for a list of all available search options.

tip

To learn more about the cart's APIs (how requests should be structured, a sample query using PHP, etc.) we recommend looking over the Introduction to APIs article.

Sample XML Request

The XML request below will match all customers that have an email address containing @modularmerchant.com. The results will start from the 3rd matched record and return 11 results.

<?xml version="1.0" encoding="utf-8"?>
<xmlrequest>
   <admin_sid>123</admin_sid>
   <admin_key>23a1c9ba51d691a74b2fd</admin_key>
   <api_key>9c1bc31e15423a1c9ba</api_key>
   <search_type>keyword</search_type>
   <start_result>3</start_result>
   <number_of_results>11</number_of_results>
   <any_vs_all>any</any_vs_all>
   <order_by>customer.id</order_by>
   <asc_vs_desc>ASC</asc_vs_desc>
   <search_rule>
       <search_field>customer.email</search_field>
       <compare_type>*LIKE*</compare_type>
       <search_string>@modularmerchant.com</search_string>
   </search_rule>
    ...The search_rule section is repeated for each rule to search by.
</xmlrequest>

urlencode the xml data

The data contained in each XML node must be urlencoded.
For example, if you wanted the "compare_type" node to be ">" (greater than):

Wrong: <compare_type>></compare_type>

Correct: <compare_type>%3E</compare_type>

search options

The following options can be used in the submitted XML query to specify the options to search the store's customer records by:

admin_sid: The SID number of the admin submitting the query.

admin_key: The personal API Key of the admin submitting the query. (Found on the Admin Account Editor page.)

api_key: The account-wide API Key. (Found on the System Settings page.)

search_type: The type of search to perform. Currently only "keyword" is supported.

start_result: The number of the result to start with. "3" would start with the third result.

number_of_results: The number of results to include in the XML response.

any_vs_all: Specifies whether the results must match "all" or "any" of the search rules.

order_by: The database field by which to order the search results. Example: "customers.id".

asc_vs_desc: Whether the results should be ordered in ascending ("ASC") or descending ("DESC") order.

SEARCH RULES
The search_rules section is repeated for each rule to match.

search_string
The content to match against. For example, to find all customers with a Modular Merchant email address, the recommended search string would be "@modularmerchant.com".

compare_type
How the search string will be compared to the search field. Options include:

1. *LIKE* (The database record must contain the search string.)

2. *NOT LIKE* (The database record must not contain the search string.)

3. = (The database record is equal to the search string.)

4. != (The database record is not equal to the search string.)

5. > (The database record is greater than the search string.)

6. < (The database record is less than the search string.)

7. LIKE* (The database record starts with the search string.)

8. *LIKE (The database record ends with the search string.)

search_field
The database field to apply the search against. Some common options include:

customer.active: The active status of the customer's account. (Y/N format)

customer.aff_approved: Affiliate Application Approved (Y/N format)

customer.aff_company: Affiliate Company Name

customer.aff_fax: Affiliate Fax Number

customer.aff_parent_tid: Affiliate Parent Tracking ID

customer.aff_url: Affiliate Website (URL format)

customer.bill_address_1: Billing Address Line 1

customer.bill_address_2: Billing Address Line 2

customer.bill_city: Billing City

customer.bill_country: Billing Country (ISO format)

customer.bill_first_name: Billing First Name

customer.bill_last_name: Billing Last Name

customer.bill_state: Billing State (ISO format)

customer.bill_zip: Billing Zip

customer.create_date: Date Created (MM/DD/YYYY format)

customer.email: Email Address

customer.email_bounces: Number of Bounced Emails

customer.email_opt_out: Email Opt In Status (Y/N format)

customer.has_tab: Has Net Terms (Y/N format)

customer.id: SID (System ID format)

customer.is_aff: Is Affiliate? (Y/N format)

customer.phone: Phone Number

customer.phone_ac: Phone Area Code

customer.reward_points: Reward Points

customer.tab_limit: Terms Limit (example: 12.34 format)

customer.tab_terms: Net Terms (in days)

customer.tax_exempt: Tax Exempt (Y/N format)

customer_group_assoc.group_id: Customer Group (SID format)

customer_ship_addr.ship_address_1: Shipping Address Line 1

customer_ship_addr.ship_address_2: Shipping Address Line 2

customer_ship_addr.ship_city: Shipping City

customer_ship_addr.ship_country: Shipping Country (ISO format)

customer_ship_addr.ship_first_name: Shipping First Name

customer_ship_addr.ship_last_name: Shipping Last Name

customer_ship_addr.ship_state: Shipping State (ISO format)

customer_ship_addr.ship_zip: Shipping Zip

email_opt_out_date: Email Opt Out Date (MM/DD/YYYY format)

note.content: Customer Notes

Sample XML Response

The response below corresponds with the sample XML request above. The XML response contains the customers that match the search criteria.

The response_status node contains a flag indicating whether the query was successful or failed.
The data node contains the customers that match the search criteria. Each customer will be encapsulated in an customer tag.

<?xml version="1.0" encoding="utf-8"?>
<response>
   <response_status>success</response_status>
   <data>
       <customer>
            <id>1476</id>
            <email>example%40modularmerchant.com</email>
            <password>123ABC</password>
            <bill_first_name>Dudley</bill_first_name>
            <bill_last_name>Heromin</bill_last_name>
            <bill_address_1>000+Paved+Road</bill_address_1>
            <bill_address_2>Suite+311</bill_address_2>
            <bill_city>Anytown</bill_city>
            <bill_state>CA_US</bill_state>
            <bill_zip>90210</bill_zip>
            <bill_country>US</bill_country>
            <phone_ac>555</phone_ac>
            <phone>555-5555</phone>
            <active>1360342757</active>
            <use_prev_cc>0</use_prev_cc>
            <reward_points>0</reward_points>
            <has_tab>0</has_tab>
            <tab_terms>0</tab_terms>
            <tab_limit>0</tab_limit>
            <tax_exempt>0</tax_exempt>
            <memo></memo>
            <is_aff>0</is_aff>
            <aff_approved>0</aff_approved>
            <aff_parent_tid>0</aff_parent_tid>
            <aff_company></aff_company>
            <aff_url></aff_url>
            <aff_fax></aff_fax>
            <aff_payable_to>I</aff_payable_to>
            <aff_tax_class>I</aff_tax_class>
            <aff_tax_id></aff_tax_id>
            <email_opt_in>0</email_opt_in>
            <email_bounces>0</email_bounces>
            <create_date>1205441357</create_date>
            <email_opt_out>1205441357</email_opt_out>
            <customer_sid>1476</customer_sid>
            <email_opt_out_date>1205441357</email_opt_out_date>
            <num_orders>1</num_orders>
            <total_spent>0.00</total_spent>
            <num_ship_addr>1</num_ship_addr>
            <num_cust_group>6</num_cust_group>
            <num_cust_review>0</num_cust_review>
            <recent_order_date>1360331130</recent_order_date>
            <recent_order_id>25106</recent_order_id>
            <subscription_id>1476</subscription_id>
            <mod_date>1360342769</mod_date>
            <login_date>1360331107</login_date>
            <num_emails>0</num_emails>
            <recent_subscription_date>1577824230</recent_subscription_date>
            <tab_due></tab_due>
            <tab_remaining>0</tab_remaining>
            <customer_ship_addr>
                <id>123</id>
                <cid>1476</cid>
                <ship_first_name>Loraine</ship_first_name>
                <ship_last_name>Gershawitz</ship_last_name>
                <ship_address_1>000+Gravel_Road</ship_address_1>
                <ship_addresss_2></ship_addresss_2>
                <ship_city>Somewhereburg</ship_city>
                <ship_state>OR_US</ship_state>
                <ship_zip>97479</ship_zip>
                <ship_country>US</ship_country>
            </customer_ship_addr>
        ...customer_ship_addr node is repeated for each customer ship address returned.
       </customer>
        ...customer node is repeated for each customer returned.
   </data>
</response>

tip

The XML data returned by the API is "url encoded". To improve its legibility, be sure to apply urldecode() or a similar function to it.

reference

The PHP website includes some tutorials on how to turn XML data into an object that PHP can use.

nodes included in the customer response xml

Below are some definitions of some of the commonly used nodes of the response XML.

CUSTOMER NODE

active: Whether the customer's account is active. No if zero, otherwise yes.

aff_approved:Whether the customer is approved to be an affiliate. No if zero, otherwise yes.

aff_company: The company name associated with the customer's affiliate account (if any).

aff_fax: The fax number associated with the customer's affiliate account (if any).

aff_parent_tid: The SID number of an Affiliate Tracking ID number that was associated with the customer when they started their customer account.

aff_payable_to: Whether affiliate payments are made to an Individual or Company.

aff_tax_class: Whether the affiliate's tax class is an Individual or Company.

aff_tax_id: The affiliate's tax ID number.

aff_url: The URL of the affiliate's home page.

bill_address_1: The first line of the customer's billing address.

bill_address_2: The second line of the customer's billing address.

bill_city: The city of the customer's billing address.

bill_country: The country of the customer's billing address.

bill_first_name: The first name from the customer's billing address.

bill_last_name: The last name from the customer's billing address.

bill_state: The state from the customer's billing address.

bill_zip: The zip code from the customer's billing address.

create_date: Unix timestamp of the date the customer's account was created.

customer_sid: The SID number of the customer's account.

email: The email address associated with the customer's account.

email_bounces: The number of emails sent to the customer using the Modular Mailer email system that have bounced back as undeliverable.

email_opt_out_date: The Unix timestamp of the date that the customer opted out of the store's Modular Mailer mailing lists. Zero if opted in.

has_tab: Whether the customer has a credit limit. If this number is greater than zero, then they do.

id: The customer's SID (System ID) number.

is_aff: Whether the customer is also an affiliate. If this number is greater than zero, then they are.

login_date: Unix timestamp of the last date the customer logged in to their Customer Account Area in the storefront.

mod_date: Unix timestamp of the most recent date the customer account was edited.

num_cust_group: The number of Customer Groups that the customer belongs to.

num_cust_review: The number of Product Reviews the customer has written.

num_emails: The number of recent emails the customer has been sent.

num_orders: The number of orders that customer has placed.

num_ship_addr: The number of shipping addresses that are associated with this customer account.

password: The password associated with the customer account.

phone: The customer's phone number.

phone_ac: The area code associated with the customer (if it was entered separately from the phone number).

recent_order_date: Unix timestamp of the customer's most recent order.

recent_order_id: SID number of the customer's most recent order.

recent_subscription_date: Unix timestamp of the customer's upcoming subscription.

reward_points: The number of Reward Points assigned to the customer account.

ship_address_1: The first line of the customer's shipping address.

ship_address_2: The second line of the customer's shipping address.

ship_city: The city of the customer's shipping address.

ship_country: The country of the customer's shipping address.

ship_first_name: The first name from the customer's shipping address.

ship_last_name: The last name from the customer's shipping address.

ship_state: The state from the customer's shipping address.

ship_zip: The zip code from the customer's shipping address.

subscription_id: The SID number of the customer's subscription.

tab_due: The dollar value of any outstanding balance on the customer's credit account.

tab_limit: The maximum dollar value of the customer's credit account.

tab_remaining: The customer's "tab_limit" minus their "tab_due".

tab_terms: The number of days in a the customer's credit terms.

tax_exempt: Whether the customer's account is tax exempt. If greater than zero, then yes.

total_spent: The total this customer has spent in your store.

use_prev_cc: Whether the secure list of the customer's previously used credit cards will be displayed on the storefront's checkout page.