API DOCUMENTATION Last Update: Apr 2022

Manage Customer Fields - Add New Field

Create a new field used to gather customer data:


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


  field   Example   Note
API 1.6 Required
user_id john1970 Required
user_api_key 1959caadac9b13dcb3 Required
type manage_fields Required
action add Required
account_id greatwidgets Required
custom_field_#_label Marital Status Required
custom_field_#_show N optional
custom_field_#_type List Required
custom_field_#_choices Single, Married, Other optional
custom_field_#_searchable Y optional
custom_field_#_unique Y 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 [field_name_#] structure:
    • "custom_field_#" where the "#" is any integer above 1
      (because one of the per-existing fields is already "custom_field_1")
      • custom_field_2
      • custom_field_14
      • ...
    • How do know which number to use? We suggest you do a Customer Fields - List API call first, and see which 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 )
  • Currently, the only field type that can be set to be "unique" is the Text type. "Unique" fields don't allow a content entry to be a duplicate of an existing one. An example might be an ID code, etc.
  • Only Text type fields can be set to searchable. All custom fields are searchable with the Customer - Find and Customer - Search API calls. This setting applies only to certain situations, like coalition accounts, where the ability to pull up a customer record is limited by the user's permissions. This field allows to mark a field as being like an "ID" field in that a user can pull up this customer in a coaltion account even though the customer doesn't yet "belong" to that campaign. In non-coalition situations, this would enable the user of Master/Slave customer IDs that allow multiple customers (family, businesses) to earn in a single customer account.
  • 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 ",".)
  • The following default field_names can only be set to show or not. (Their type is set.)
    • card_number
    • first_name
    • last_name
    • phone
    • email
    • street1
    • street2
    • city
    • state
    • zip
    • country
    • customer_username
    • customer_PIN
    • customer_password
    • custom_date
    • custom_field_1

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_fields';
  6. $data['action'] = 'add';
  7. $data['custom_field_2_label'] = 'Middle Name'
  8. $data['custom_field_2_show'] = 'Y';
  9. $data['custom_field_2_type'] = 'Text';
  10. $data['custom_field_3_label'] = 'Tags';
  11. $data['custom_field_3_show'] = 'Y';
  12. $data['custom_field_3_type'] = 'List';
  13. $data['custom_field_3_choices'] = 'Tag A, Tag B, Tag C, Tag D, ...';
  14. $data['custom_field_4_label'] = 'Allow SMS';
  15. $data['custom_field_4_show'] = 'Y';
  16. $data['custom_field_4_type'] = 'Pick';
  17. $data['custom_field_4_choices'] = 'Yes|No';


Success XML Response (lists ALL the existing fields):

  1. <response status="success">
  2. <account>
  3. <account_id>test2009050502</account_id>
  4. <fields>
  5. <field>
  6. <name>card_number</name>
  7. <label>Member #</label>
  8. <show>Y</show>
  9. <type>Text</type>
  10. </field>
  11. <field>
  12. <name>first_name</name>
  13. <label>First Name</label>
  14. <show>Y</show>
  15. <type>Text</type>
  16. </field>
  17. ...
  18. <field>
  19. <name>custom_field_2</name>
  20. <label>Middle Name</label>
  21. <show>Y</show>
  22. <type>Text</type>
  23. </field>
  24. <field>
  25. <name>custom_field_3</name>
  26. <label>Tags</label>
  27. <show>Y</show>
  28. <type>List</type>
  29. <choices>
  30. <choice>Tag A</choice>
  31. <choice>Tag B</choice>
  32. <choice>Tag C</choice>
  33. </choice>
  34. </field>
  35. <field>
  36. <name>custom_field_4</name>
  37. <label>Allow SMS</label>
  38. <show>Y</show>
  39. <type>Pick</type>
  40. <choices>
  41. <choice>Yes</choice>
  42. <choice>No</choice>
  43. </choice>
  44. </field>
  45. </fields>
  46. </account>
  47. </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>