Manage Customer Fields - Update

Update the status of fields 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 updated 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.
• 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.
• 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)
  • Date ("datetime" stamp. Ex: 2012-01-01 14:45:04 )
  • Pick (Requires [field_name]_choices )
  • List (Requires [field_name]_choices )
• 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
• 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.

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'] = 'update';
7. $data['card_number_label'] = 'Member #';
8. $data['card_number_show'] = 'Y';
9. $data['country_show'] = 'N';
10. $data['custom_field_3_label'] = 'Gender';
11. $data['custom_field_3_show'] = 'Y';
12. $data['custom_field_3_type'] = 'Pick';
13. $data['custom_field_3_choices'] = 'Male, Female, Other';
14. $data['custom_field_4_label'] = 'Allow SMS';
15. $data['custom_field_4_show'] = 'Y';
16. $data['custom_field_4_type'] = 'Text';

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>country</name>
20. <label>Country</label>
21. <show>Y</show>
22. <type>Text</type>
23. </field>
24. <field>
25. <name>custom_field_3</name>
26. <label>Gender</label>
27. <show>Y</show>
28. <type>Pick</type>
29. <choices>
30. <choice>Male</choice>
31. <choice>Female</choice>
32. <choice>Other</choice>
33. </choice>
34. </field>
35. <field>
36. <name>custom_field_4</name>
37. <label>Allow SMS</label>
38. <show>Y</show>
39. <type>Text</type>
40. </field>
41. </fields>
42. </account>
43. </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.

Example Request 2 (without any fields passed, and "web_update+ set to "Y")
(ie: All fields were unchecked -- Not likely but given as an extreme example):

1. $data['API'] = '1.5';
2. $data['user_id'] = 'john1970';
3. $data['user_api_key'] = '1959caadac9b13dcb3';
4. $data['type'] = 'manage_fields';
5. $data['action'] = 'update';
6. $data['account_id'] = 'greatwidgets';
7. $data['web_update'] = 'Y';

Success XML Response: 

1. <response status="success">
2. <account>
3. <account_id>test2009050502</account_id>
4. <fields>
5. <field>
6. <id>card_number</name>
7. <label>Card #</label>
8. <show>N</show>
9. </field>
10. <field>
11. <id>first_name</name>
12. <label>First Name</label>
13. <show>N</show>
14. </field>
15. ...
16. </fields>
17. </account>
18. </response>

Error XML Response:

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