Manage Customer Fields - Add New Field

Create a new field used to gather customer data:

Headers

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

NOTE:

• Headers: the user_api_key value can be included in either the header section or the body of the request. If the key is provided in both locations, the API will process and validate only the value provided in the headers.

• 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")
    Example:
    • 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>

NOTE:

• 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>