API DOCUMENTATION Last Update: Apr 2022

Manage Custom Reward Fields - Update Field

Update existing custom reward fields 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 update 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.
  • [field_name]_type and [field_name]_unique will be ignored if the field to be updated already exists (as it should in an "update" API call -- however, it is allowed to be passed in case the update is done blindly without the ability to know if the field already exists or not, in which case it would be "added", and that requires the "type" to be set, and perhaps if that field is to be "unique" or not, since the these can only be set when a field is created.
  • If using this call as part of a web-based HTML form where users tick checkboxes to select which fields to show, the HTML form will only send back those fields whose boxes are checked. (ie: unchecking a box means that no data is sent back and is essentially the same as the option having never been given.) To solve that issue, either make sure to develop code to still send any "unchecked" field with its value set to "N", OR include the web_udate=Y option which will cause the API to treat any non-submitted choice (unchecked) as having been assigned the value of "N" (This works only on existing fields, because it assumes that those that are "missing" are those that are unchecked.)
  • If a field is received by the API to be updated and does not already exist, it will be created with any values provided (Default: Show=No, if it's not provided.) WARNING: This will NOT happen if a type is not provided, and you cannot change the type once it's set.
  • 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 )

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';$data['country_show'] = 'N
  7. $data['reward_custom_field_1_label'] = 'PCU'
  8. $data['reward_custom_field_1_show'] = 'Y';
  9. $data['reward_custom_field_1_type'] = 'Text';


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>PCU</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>