API DOCUMENTATION Last Update: Apr 2022

Manage Custom Reward Fields - Add New Field

Create a new custom reward field used to gather rewards data:


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


  field   Example   Note
API 1.5 Required
user_id john1970 Required
user_api_key 1959caadac9b13dcb3 Required
type manage_reward_fields Required
action add Required
account_id greatwidgets Required
reward_custom_field_#_label Category Required
reward_custom_field_#_show Y optional
reward_custom_field_#_type List Required
reward_custom_field_#_choices Beverages, Food, Other 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



  • Only users with proper permissions can access this call.
  • Multiple fields can be added at the same time.
  • If a field is received by the API and is missing some of its parameters, it will be created with any such missing values set to their default: Show=No, Type=Text.
  • Additional fields have the following structure:
    • "reward_custom_field_#" where the "#" is any integer above 1
      (because one of the per-existing fields is already "custom_field_1")
      • reward_custom_field_2
      • reward_custom_field_14
      • ...
    • How do know which number to use? We suggest you do a Reward Customer Fields - List API call first, and see which reward custom fields, if any, already exist.
  • Field types are:
    • Text (up to 64000 characters, unless it's set as searchable (is ID) or unique, in which cases it's up to 255 characters.)
    • Date ("datetime" stamp. Ex: 2012-01-01 14:45:04 )
    • Pick (Requires [field_name]_choices )
    • List (Requires [field_name]_choices )
  • The difference between the List type and the Pick type is that for the Pick type, only ONE of the choices can be submitted back to the API, whereas for the List type, any number of the choices can be sent back (separated by a comma ",".)

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'] = 'manage_reward_fields';
  6. $data['action'] = 'add';
  7. $data['reward_custom_field_1_label'] = 'SKU'
  8. $data['reward_custom_field_1_show'] = 'Y';
  9. $data['reward_custom_field_1_type'] = 'Text';
  10. $data['reward_custom_field_2_label'] = 'Category';
  11. $data['reward_custom_field_2_show'] = 'Y';
  12. $data['reward_custom_field_2_type'] = 'List';
  13. $data['reward_custom_field_2_choices'] = 'Beverages,Food,Other, ...';


Success XML Response (lists ALL the existing fields):

  1. <response status="success">
  2. <account>
  3. <account_id>greatwidgets</account_id>
  4. <fields>
  5. <field>
  6. <name>reward_custom_field_1</name>
  7. <label>SKU</label>
  8. <show>Y</show>
  9. <type>Text</type>
  10. </field>
  11. <field>
  12. <name>reward_custom_field_2</name>
  13. <label>Category</label>
  14. <show>Y</show>
  15. <type>List</type>
  16. <choices>
  17. <choice>Beverages</choice>
  18. <choice>Food</choice>
  19. <choice>Other</choice>
  20. </choice>
  21. </field>
  22. </fields>
  23. </account>
  24. </response>



  • The <show> response indicates whether or not this field ought to be shown or not. Usually fields with "N" will have nothing in them. However, it is allowed to add content to any defined field through the API regardless of their <show> status.


Error XML Response:

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