Record or Register a New Customer

Create a customer account; Returns a unique Account ID.

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

Notes:

• '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:
  • If this is a "customer_action = new" call, the 'card_number' will be used as the 'code' and that's what will be returned in the API response. If you don't want that to happen, then include the code_new parameter set to Yes to force the generation of a 16-digit UID.
  • In either case, if your application can, record the 'code' transmitted back, and include it with all transactions associated with this customer. If not, don't worry. You can always query the API for the 'code' associated with a card_number for future transactions recording.
• If 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 parameters card_number_prefix and card_number_suffix are only applicable when the card_number_generate is passed.
• All optional fields are optional individually, but at least ONE must be passed along.
• If the customer_action tag is set to new and a customer record is sent that matches an existing record, an error will be generated.
• If the customer_action tag is set to register, the card_number field must match an existing record in the database, and the customer_password field must not have been previously set (in the database). If both these conditions are true, and both a card_number and valid customer_password are given, then the user information is recorded and the status returned will be "registered". Otherwise, an error message will be returned saying that the card has already been registered.
• The 'campaign_id' is optional, can be provided either singly or as a comma separated list.
  • If not given, a customer will be recorded into the system, but won't "belong" to any campaign (until a transaction is added for that customer to a campaign)
  • If only a single campaign ID is provided, the customer will be recorded and an "Activation" transaction recorded in the given campaign.
  • If a list of campaign_ids is given, then an "activation" transaction will be recorded for each campaign in the list.
• Notes:
  • "Activation" transactions do not affect campaign balances.
  • A customer "belongs" to a campaign when they have any sort of transaction in that campaign.
• 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?. Also this format conforms to ISO-8601.)
• 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 a customer's account in the campaign specified above, when using this call, the optional auto_add parameter 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 user auto_add = "25" (which will add 25 points to the customer's account balance.)
• The send_no_email is an API-specific field that if included will suppress the normal email that is generated and sent to the account owner letting them know about the new customer and their information (for example to send a plastic card to.)
• custom_field_## must be first defined by through the Custom Fields - Create API call, and can be listed by first calling the Custom Fields - List API call. The content of a custom field must match its type. So for example, if a custom field expects a date / time stamp, it will reject with an error anything but that format.

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['type'] = 'record_customer';
4. $data['customer_action'] = 'new';
5. $data['account_id'] = 'greatwidgets';
6. $data['campaign_id'] = '1234567890123456';
7. $data['card_number'] = '1212121212';
8. or: $data['card_number_generate'] = 10; // for 10-digit number.
9. $data['code'] = '89898989898989';
10. $data['first_name'] = 'John';
11. $data['last_name'] = 'Doe';
12. $data['phone'] = '555-555-2455';
13. $data['email'] = 'test@yourdomain.com';
14. $data['custom_date'] = '1970-07-14';
15. $data['street1'] = '123 Main St.';
16. $data['street2'] = 'Apt 3G';
17. $data['city'] = 'Anytown';
18. $data['state'] = 'ZZ';
19. $data['postal_code'] = '55555';
20. $data['country'] = 'NZ';
21. $data['custom_field'] = 'John likes cheese.';
22. $data['customer_username'] = 'jdoe1970';
23. $data['customer_password'] = 'ilovecheese';
24. $data['customer_PIN'] = '1234';
25. $data['custom_field_2'] = 'Single';

Success XML Response (New Customer):

1. <response status="success">
2. <customer status="new">
3. <code>1234567890123456</code>
4. //only when card_number_generate is set:
5. <card_number>1234567890</card_number>
6. </customer>
7. </response>

Error XML Response:

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