API DOCUMENTATION Last Update: Apr 2022

Create New Campaign

Add a new campaign to an existing account and returns the campaign_id of the new campaign.


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


Fields common to all campaign types:

  field   Example   Note
user_id john1970 Required
user_password 1959caadac9b13dcb3 Required
type campaign_new Required
action campaign Required
account_id greatwidgets Required
campaign_type points or
giftcard or
events or
earned or
campaign_name Widget Rewards Required
latitude 40.000001 Optional
longitude -40.000001 Optional
description Check-in at 3rd and 5th. Optional
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



  • The ability to create new campaigns is based on the permissions of the user_id that is making the call.
  • Only one campaign can be created at a time. Loop this call in your program to create multiple campaigns at one time.
  • The latitude and longitude parameters can be used in order to create a geo-fenced campaign. They are completely optional.


Additional Fields for Points-Based Campaigns:

  field   Example   Note
points_ratio 50 Required (See Note)
reward_ratio 15 Optional (See Note)


  • The points_ratio is required in so far as for any amount entered, there has to be a ratio to convert it to points. If for some reason the points_ratio is not given or is blank, it will default to 100:1 (ie: $1.00 = 100 points, so that cents can be captured.)
  • The reward_ratio is also know as the spend-to-reward ratio, and is used to reverse-assign a value to the points accumulated. It is optional since not setting it (or setting it to a blank or null value) turns off the abilty to redeem points by their currency value. (This is the default state.) Hence it needs to be set only if this is an ability you want this campaign to provide.


Additional Fields for Earn-per-Event Campaigns:

  field   Example   Note
amount_per_event 4.95 Required (See Note)


  • The amount_per_event is a currency amount that will be added to the customer's balance for each event. If not provided or missing, it will default to 0 (zero).



Optional Fields for Coalition and Two-Tier Campaigns:

  field   Example   Note
coalition_opt_out Y Optional or don't include
two_tier_opt_out Y Optional or don't include


  • These are parameters that only apply for those campaigns that belong to a coalition or two-tier account. Include the parameters if the campaigns are to not belong to the coaltion or two-tier program. Otherwise, don't include them, and they will automatically belong.



Example PHP Requests:

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

For Giftcard, Events, or BuyX Campaigns:

  1. $data['user_id'] = 'john1970';
  2. $data['user_password'] = '1959caadac9b13dcb3';
  3. $data['type'] = 'campaign_new';
  4. $data['action'] = 'campaign';
  5. $data['campaign_name'] = 'Widget Card';
  6. $data['campaign_type'] = 'giftcard';
  7. or
  8. $data['campaign_type'] = 'events';
  9. or
  10. $data['campaign_type'] = 'buyx';


For a Points Campaign:

  1. $data['user_id'] = 'john1970';
  2. $data['user_password'] = '1959caadac9b13dcb3';
  3. $data['type'] = 'campaign_new';
  4. $data['action'] = 'campaign';
  5. $data['campaign_type'] = 'points';
  6. $data['campaign_name'] = 'Widget Rewards';
  7. $data['points_ratio'] = '50';
  8. $data['reward_ratio'] = '15';


For a Earned-per-Event Campaign:

  1. $data['user_id'] = 'john1970';
  2. $data['user_password'] = '1959caadac9b13dcb3';
  3. $data['type'] = 'campaign_new';
  4. $data['action'] = 'campaign';
  5. $data['campaign_type'] = 'earned';
  6. $data['campaign_name'] = 'Widget VIP';
  7. $data['amount_per_event'] = '4.95';



Success XML Response:

  1. <response status="success">
  2. <campaign>
  3. <id>1234567890123456</id>
  4. </campaign>
  5. </response>


Error XML Response:

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