Users List

Returns a list of the users for an account.

Headers

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

Notes:

• 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 Admin-level users or account "owner" credentials can make this call.
• The field "user_full_name" allows for restricting the list of users based on the first and last name together. The field "user_name" is the username of the user for login credentials. For example:
  • First Name: John
  • Last name: Smith
  • Therefore, user_full_name = "John Smith"
  • The user_name on the other hand, could be "jsmith123"
• The user_role is based on the roles listed in the User Permission Levels reference page.
• To also return the list of permissions the user is subject to, include the show_permissions parameter and set it to Yes. It will only include the entries that user has permissions for, not the full list of permissions. If the parameter is not included, the permissions list will not be returned. Note: The resulting XML file can be quite long if you have a lot of users.

Example PHP Request for a full, unordered list of all users without permissions details:

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'] = 'users_list';

Success XML Response:

1. <response status="success">
2. <pagination>
3. <total>12</total>
4. </pagination>
5. <users>
6. <user>
7. <user_id>janecashier</user_id>
8. <user_first_name>Jane</user_first_name>
9. <user_last_name>Cashier</user_last_name>
10. <user_api_key>p2345khkl235hkufbfdivsdf</user_api_key>
11. <user_PIN>1234</user_PIN>
12. <user_addtl_info>London</user_addtl_info>
13. <user_language>EN<user_language>
14. <user_timezone>15</user_timezone>
15. <user_role>K</user_role>
16. <user_allowed_campaigns status="some">
17. <campaign_id>1234567890123456</campaign_id>
18. <campaign_id>2345678901234567</campaign_id>
19. ...
20. </user_allowed_campaigns>
21. </user>
22. <user>
23. <user_id>joeclerky</user_id>
24. <user_first_name>Joe</user_first_name>
25. <user_last_name>Clerky</user_last_name>
26. <user_password>p4sf8nvrdr8vhsd98erkerte</user_password>
27. <user_PIN>9876</user_PIN>
28. <user_addtl_info>New York</user_addtl_info>
29. <user_language>EN<user_language>
30. <user_timezone>15</user_timezone>
31. <user_role>K</user_role>
32. <user_allowed_campaigns status="all">
33. </user_allowed_campaigns>
34. </user>
35. ...
36. </users>
37. </response>

Notes:

• The user_allowed_campaigns status can consisting of:
  • "all" to indicated that all campaigns are allowed access
  • "none" to indicate no access to none of the account campaigns (rare)
  • "some" to indicate multiple entries of campaign IDs (as in example above)

Example PHP Request for a partial, ordered list matching users with permissions details:

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'] = 'users_list';
6. $data['searchField'] = 'user_custom1';
7. $data['searchOper'] = 'cn';
8. $data['searchOper'] = 'London';
9. $data['sortField'] = 'user_first_name';
10. $data['sortOrder'] = 'ASC';
11. $data['offset'] = '0';
12. $data['length'] = '10';
13. $data['show_permissions'] = 'Yes';

Success XML Response:

1. <response status="success">
2. <pagination>
3. <total>5</total>
4. <offset>0</offset>
5. <length>10</length>
6. </pagination>
7. <users>
8. <user>
9. <user_id>janecashier</user_id>
10. <user_first_name>Jane</user_first_name>
11. <user_last_name>Cashier</user_last_name>
12. <user_api_key>p2345khkl235hkufbfdivsdf</user_api_key>
13. <user_PIN>1234</user_PIN>
14. <user_addtl_info>London</user_addtl_info>
15. <user_language>EN<user_language>
16. <user_timezone>15</user_timezone>
17. <user_role>K</user_role>
18. <user_permissions>
19. <view_account_info>Yes</view_account_info>
20. <view_promotions>Yes</view_promotions>
21. ...
22. </user_permissions>
23. <user_allowed_campaigns status="some">
24. <campaign_id>1234567890123456</campaign_id>
25. <campaign_id>2345678901234567</campaign_id>
26. ...
27. </user_allowed_campaigns>
28. </user>
29. ...
30. </users>
31. </response>

Error XML Response:

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