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
API 1.5 Required
user_id john1970 Required
user_api_key 1959caadac9b13dcb3 Required
account_id greatwidgets Required
type customers_batch Required
delimiter pipe or comma or tab Required
overwrite_duplicates yes or update or ignore See Note
allow_undo yes Optional: 'yes'
or don't include.
card_number_generate (# of digits) Optional - See Note
campaigns_to_include 89898989989
aaaa,bbbb, cccc
At least one is required. If more than one, separate by comma.
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



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

  field   Example   Note
profiles_header_1 card_number At least one is required

profiles_header_2 code (customer UID)
profiles_header_3 first_name
etc... last_name
custom_field_1 Note:

Use the Customer Fields - List
API call to determine the name (custom_field_##) of any added custom fields.



Import data:

  field   Example   Note
profiles_data (see below)
Data to be imported in batch:
One single (text) field with "end-of-lines" (ex: \n and/or \r) at the end of each line:






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



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>