API DOCUMENTATION Last Update: Apr 2022

Batch Import Customers

Import one or more customers at a time.

 

The data to be submitted to the API is composed of the following fields:

Basic credentials and common parameters:

  field   Example   Note
user_id john1970 Required
user_password 1959caadac9b13dcb3 Required
type customers_batch Required
account_id greatwidgets Required
delimiter pipe or comma or tab Required
overwrite_duplicates yes or update or ignore See Note
no_undo yes Optional: 'yes'
or don't include.
card_number_generate (# of digits) Optional - See Note
campaigns_to_include 89898989989
or
aaaa|,|bbbb|,|cccc
At least one is required. If more than one, separate by |,|
(pipe comma pipe)
Output Format:
output JSON or XML Optional. If not provided, defaults to XML
callback someFunctionName Optional: JSONP format
condensed yes Optional (No white space)
Applies only to JSON(P) output

 

Headers:

Determines the order of the fields, separated by the delimiter, given in the data:

  field   Example   Note
profiles_header_1 code At least one is required
profiles_header_2 card_number
profiles_header_3 first_name
profiles_header_4 last_name
profiles_header_5 email
profiles_header_6 phone
profiles_header_7 custom_date
profiles_header_8 street1
profiles_header_9 street2
profiles_header_10 city
profiles_header_11 state
profiles_header_12 postal_code
profiles_header_13 country
profiles_header_14 custom_field
profiles_header_15 customer_username
profiles_header_16 customer_password
profiles_header_17 customer_PIN
profiles_header_18 auto_add

 

Import data:

  field   Example   Note
Profiles_Data (see below)
Data to be imported in batch: single (text) field with <eol>s at the end of each line:

11223344|11223344|jane|doe|1970-07-14|555-5555

22334455|22334455|jim|mcdoe|1966-07-28|555-5556

33445566|33445566|larry|smith|1980-02-05|555-5557

 

Notes:

  • Number the profiles_header_## fields in increasing order. Do not skip more than one!
  • You can change the order of the fields, just keep the profiles_header_## numbering from 1 to the number of fields you are using.
  • The difference in the settings for overwrite_duplicates is:
    • yes (overwrite): In case of a match, this option will blank out all existing fields/data for that customer, and replace with the data given.
    • update: In case of a match, this option will only change the fields that are given, leaving any customer fields that are not part of the import untouched.
    • ignore (skip): In case of a match, the existing data will be left untouched and the data row from the import data will be ignored.
  • no_undo: When set to yes, an undo state will not be recorded (ie: you can't undo the import). By default, if this parameter is not included, an undo state will be saved. When first importing, until you know that the data structure is consistenly correct, do not include this parameter. Once the process is tested and automated, include and set the no-undo parameter to limit the list of undo states in the admin interface.
  • card_number_generate: When included, random card numbers will be generated (all numeric, of the given length) if a card_number is not included or is blank.
  • code' should be provided as the internal ID for the customer of the application that is sending the data.
    • If the application that is sending the data uses the 'card_number' as their unique Customer ID, then insert it as BOTH 'code' and 'card_number' entries.
    • If the application that is sending the data does not have an internal unique ID for a customer, do not include the 'code' entry. The API response will include our internally generated 16-digit unique id as part of the response to be recorded into your system to be transmitted back with all transactions associated with this customer.
    • If instead, you want the program to generate a random unique card number, then include the card_number_generate field with the number of digits for the card number to be generated.
  • The 'custom_date' must be in YYYY-MM-DD format. (Any other format cannot be resolved without further context. Ex: 04-03-2010 could be either April 3rd or 4th of March. Don't even get us started on inputs like 04-06-05... What the heck is THAT?)
  • The customer_username is an API-specific field made available for custom applications. It cannot be defined or edited in the web interface.
  • The customer_password field is made available for custom applications such as a customer"hotsite". It can be defined or edited in the web interface.
  • The customer_PIN is an API-specific field made available for custom applications such as a physical terminal. It cannot be defined or edited in the web interface.
  • To automatically add an amount to the FIRST campaign specified above, use the optional auto_add parameter which lets you specify the amount of points, visits, dollars, or name of product or service, depending on the campaign type, to add. For example, as a thank-you bonus for signing-up, you would specify 25 as the data in the auto_add field for that customer (which will add 25 points to the customer's account balance.)

 

Example PHP Request:

If you are using PHP, the $data array would look like this:

  1. $data['user_id'] = 'john1970';
  2. $data['user_password'] = '1959caadac9b13dcb3';
  3. $data['account_id'] = 'greatwidgets';
  4. $data['type'] = 'customers_batch';
  5. $data['delimiter'] = 'pipe';
  6. $data['overwrite_duplicates'] = 'update';
  7. or: $data['card_number_generate'] = 10; // for 10-digit number.
  8. $data['campaigns_to_include'] = '898989889|,|13234545|,|34534554';
  9. $data['profiles_header_1'] = 'code';
  10. $data['profiles_header_2'] = 'card_number';
  11. $data['profiles_header_3'] = 'first_name';
  12. $data['profiles_header_4'] = 'last_name';
  13. $data['profiles_header_5'] = 'custome_date';
  14. $data['profiles_header_6'] = 'phone';
  15. $data['Profiles_Data'] = '
  16. 11223344|11223344|jane|doe|1970-07-14|555-5555
  17. 22334455|22334455|jim|mcdoe|1966-07-28|555-5556
  18. 33445566|33445566|larry|smith|1980-02-05|555-5557
  19. ';

 

 

Success XML Response:

  1. <response status="success">
  2. <batch status="imported">
  3. <customers>
  4. <new>2<new>
  5. <updated>1<updated>
  6. <customers>
  7. </batch>
  8. </response>

 

 

Error XML Response:

  1. <response status="error">
  2. <error>Error message</error>
  3. </response>