Create New User

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

Notes:

• The user_name cannot be longer than 20 characters and must contain only alphanumeric characters and the underscore (" _ ")
• The user_PIN is an API-specific field made available for custom applications such as a physical terminal. It cannot be defined or edited in the web interface. It MUST be unique to each user within an account.
• You can find a list of language two-letter codes in the Available Languages reference page
• You can find a list of timezone codes in the Timezones reference page
• The allowed_campaigns consists of (see examples below) :
  • A single entry "all"
  • A single entry "none"
  • Multiple entries of campaign IDs separated by a comma ","
  • Administrator (A) users are not affected by this parameter and are always set to access all campaigns.
• The user_role is based on the roles listed in the User Permission Levels reference page.
• The user_custom1 field is shown on the Dashboard as "Location" and on XML results from the API as the <user_addtl_info> tag.

Example PHP Request:

If you are using PHP, the $data array would look like this:

              $data['user_id']        = 'john1970';
              $data['user_password'] 	= '1959caadac9b13dcb3';	
              $data['type'] = 'user_new';
              $data['account_id'] = 'greatwidgets';
              $data['user_name'] = 'janeclerk';
              $data['user_new_password'] = 'pa$$w0rd';
              $data['user_first_name'] = 'Jane';
              $data['user_last_name'] = 'Doe';
              $data['user_custom1'] = 'Melbourne Office';
              $data['language_selector'] = 'EN';
              $data['timezone_selector'] = '68';
              $data['user_role'] = 'K';
              $data['allowed_campaigns'] = '12971184024723,0239471023412';
              or
              $data['allowed_campaigns'] = 'all';
              or
              $data['allowed_campaigns'] = 'none';
          

Success XML Response (New / Updated User):

              <response status="success">
              </response>
          

Error XML Response:

              <response status="error">
                <error>Error message</error>
              </response>
          

Update User Information

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

Notes:

• The user_name cannot be changed, but must be provided to know which user is being updated.
• The user_PIN is an API-specific field made available for custom applications such as a physical terminal. It cannot be defined or edited in the web interface. It MUST be unique to each user in an account.
• You can find a list of language two-letter codes in the Available Languages reference page
• You can find a list of timezone codes in the Timezones reference page
• The allowed_campaigns consists of: (see examples below)
  • A single entry "all"
  • A single entry "none"
  • Multiple entries of campaign ID (see example below)
  • Administrator (A) users are not affected by this parameter and are always set to access all campaigns.
• The user_role is based on the roles listed in the User Permission Levels reference page.
• The language_custom is used only for custom applications that need a flag to indicate if the user has a custom language definition store locally (elsewhere) or not.

Example PHP Request:

If you are using PHP, the $data array would look like this:

              $data['user_id']        = 'john1970';
              $data['user_password'] 	= '1959caadac9b13dcb3';	
              $data['type'] = 'process_user';
              $data['account_id'] = 'greatwidgets';
              $data['user_action'] = 'new';
              $data['user_name'] = 'janeclerk';
              $data['user_password1'] = 'pa$$w0rd';
              $data['user_password2'] = 'pa$$w0rd';
              $data['user_first_name'] = 'Jane';
              $data['user_last_name'] = 'Doe';
              $data['user_custom1'] = 'Melbourne Office';
              $data['language_selector'] = 'EN';
              $data['timezone_selector'] = '68';
              $data['user_role'] = 'K';
              $data['allowed_campaigns'] = '12971184024723,0239471023412';
              or
              $data['allowed_campaigns'] = 'all';
              or
              $data['allowed_campaigns'] = 'none';
          
          

Success XML Response (New / Updated User):

              <response status="success">
              </response>
          

Error XML Response:

              <response status="error">
                <error>Error message</error>
              </response>
          

Users List

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

Notes:

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

              $data['API'] = '1.5';
              $data['user_id'] = 'john1970';
              $data['user_api_key'] = '1959caadac9b13dcb3'; 
              $data['account_id'] = 'greatwidgets';
              $data['type'] = 'users_list';
          

Success XML Response:

              <response status="success">
                  <pagination>
                    <total>12</total>
                  </pagination>
                  <users>
    
                    <user>
                          <user_id>janecashier</user_id>
                          <user_first_name>Jane</user_first_name>
                          <user_last_name>Cashier</user_last_name>
                          <user_api_key>p2345khkl235hkufbfdivsdf</user_api_key>
                          <user_PIN>1234</user_PIN>
                          <user_addtl_info>London</user_addtl_info>
                          <user_language>EN<user_language>
                          <user_timezone>15</user_timezone>
                          <user_role>K</user_role>
                          <user_allowed_campaigns status="some">
                              <campaign_id>1234567890123456</campaign_id>
                              <campaign_id>2345678901234567</campaign_id>
                              ...
    
                        </user_allowed_campaigns>
                      </user>
                      <user>
                          <user_id>joeclerky</user_id>
                          <user_first_name>Joe</user_first_name>
                          <user_last_name>Clerky</user_last_name>
                          <user_password>p4sf8nvrdr8vhsd98erkerte</user_password>
                          <user_PIN>9876</user_PIN>
                          <user_addtl_info>New York</user_addtl_info>
                          <user_language>EN<user_language>
                          <user_timezone>15</user_timezone>
                          <user_role>K</user_role>
                          <user_allowed_campaigns status="all">
                          </user_allowed_campaigns>
                      </user>
                      ...								
                  </users>
              </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:

              $data['API'] = '1.5';
              $data['user_id'] = 'john1970';
              $data['user_api_key'] = '1959caadac9b13dcb3'; 
              $data['account_id'] = 'greatwidgets';
              $data['type'] = 'users_list';
              $data['searchField'] = 'user_custom1';
              $data['searchOper'] = 'cn';
              $data['searchOper'] = 'London';
              $data['sortField'] = 'user_first_name';
              $data['sortOrder'] = 'ASC';
              $data['offset'] = '0';
              $data['length'] = '10';
              $data['show_permissions'] = 'Yes';
          

Success XML Response:

              <response status="success">
                  <pagination>
                      <total>5</total>
                      <offset>0</offset>
                      <length>10</length>
                  </pagination>
                  <users>
                      <user>
                          <user_id>janecashier</user_id>
                          <user_first_name>Jane</user_first_name>
                          <user_last_name>Cashier</user_last_name>
                          <user_api_key>p2345khkl235hkufbfdivsdf</user_api_key>
                          <user_PIN>1234</user_PIN>
                          <user_addtl_info>London</user_addtl_info>
                          <user_language>EN<user_language>
                          <user_timezone>15</user_timezone>
                          <user_role>K</user_role>
                          <user_permissions>
                              <view_account_info>Yes</view_account_info>
                              <view_promotions>Yes</view_promotions>
                              ...
                          </user_permissions>
                          <user_allowed_campaigns status="some">
                              <campaign_id>1234567890123456</campaign_id>
                              <campaign_id>2345678901234567</campaign_id>
                              ...
            
                          </user_allowed_campaigns>
                      </user>
                      ...
                  </users>
              </response>
          

Error XML Response:

              <response status="error">
                <error>Error message</error>
              </response>
          

User Information

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

Notes:

• The user_password to be provided is the API key, not the actual typed-in pasword on a form field. To login a user with a typed-in password, please contact us for acess to the Enterprise Level API.
• The parameter user_name is optional: It refers to the user_id of another user about whom information is requested. If it is given, then information about that user will be returned. If it is ommited, then info about the user making the call (user_id) will be returned.
  • If this seems contradictory or complicated, look at it from this scenario: To continually validate a user with the password they typed in, this password would have to be stored locally and passed back to the API with each screen or API call. This could be a security issue as the password could be gleaned from the local storage, hidden form data, or cookie. If you were to also store the permission level, a person with a low permission level could edit the stored data to give themselves a higher permission and access capabilites on your app that they shouldn't have access to. Hence this call without passing a separate user_name allows for verifying this data at any point.
• If suppress_permissions or terminal is passed with a Yes value, the list of permissions is not returned. If you ommit this parameter, the permissions list is returned by default. terminal is an alias of suppress_permissions.

Example PHP Request:

If you are using PHP, the $data array would look like this:

              $data['user_id'] = 'john1970';
              $data['user_password'] 	= '1959caadac9b13dcb3';	
              $data['type'] = 'user_info';
              $data['account_id'] = 'greatwidgets';
          

Success XML Response -- Account Owner credentials only:

              <response status="success">
                  <user>
                      <user_id>johnnyclerk</user_id>
                      <user_is_owner>true</user_is_owner>
                      <user_biz_name>Demo Co.</user_biz_name>
                      <user_language>EN</user_language>
                      <user_timzone>14</user_timezone>
                      <user_level>A</user_level>
                  </user>
              </response>
          

NOTES:

• Account Owner user accounts do not have first_name, last_name, or addtl_info fields
• Account Owners are always level "A". This is included even if not needed to simplify permission checks at the application / integration level.
• Timezone and language code tables are available on the menu on the left.

Success XML Response -- Account Users credentials:

              <response status="success">
                  <user>
                      <user_id>johnnyclerk</user_id>
                      <user_is_owner>false</user_is_owner>
                      <user_first_name>John</user_first_name>
                      <user_last_name>Smith</user_last_name>
                      <user_addtl_info>store 35</user_addtl_info>
                      <user_language>EN</user_language>
                      <user_timzone>14</user_timezone>
                      <user_level>K</user_level>
                  </user>
              </response>
          

NOTES:

• Account Users do not have a biz_name field.
• timezone , language, and user_level code tables are available on the menu on the left.

Error XML Response:

              <response status="error">
                <error>Error message</error>
              </response>
          

Delete User

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

Notes:

• ONLY users with Administrator-level permissions can make this API call.
• The action = permanent parameter is optional. Normally, this parameter is NOT passed, to prevent situations where if a user is permanently deleted and another user is created later with the same user_name, and since user_names are stored with transactions to identify the person who processed the transaction, a new user could "inherit" the transactions of a previously same-named user. (This would not be affected across accounts.) If you want to ignore this consequence, then add the action = permanent to the parameters passed.

Example PHP Request:

If you are using PHP, the $data array would look like this:

              $data['user_id'] = 'john1970';
              $data['user_password'] 	= '1959caadac9b13dcb3';	
              $data['type'] = 'user_delete';
              $data['account_id'] = 'greatwidgets';
              $data['user_name'] = 'fired_clerk';
          

Success XML Response:

              <response status="success">
              </response>
          

Error XML Response:

              <response status="error">
                <error>Error message</error>
              </response>
          

Add Users to Campaign

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

Notes:

• There must be only ONE campaign_id.
• The usernames in the users_list must be separated by a comma. Extra spaces will be trimmed, so don't worry about them.

Example PHP Request:

If you are using PHP, the $data array would look like this:

              $data['API'] = '1.5';
              $data['user_id'] = 'john1970';
              $data['user_password'] 	= '1959caadac9b13dcb3';	
              $data['account_id'] = 'greatwidgets';
              $data['type'] = 'campaign_users';
              $data['action'] = 'add';
              $data['campaign_id'] = '1234567890123456';
              $data['users_list'] = 'user1,user2,user3,user4,user5';
          

Success XML Response:

              <response status="success">
                  <users_added>
                      <user>user1</user>
                      <user>user2</user>
                      <user>user3</user>
                      <user>user5</user>
                  </users_added>
              </response>
          

NOTES:

• Only the users that were actually added that campaign's access permissions will be shown on the return XML. The following are reasons why a username is not returned:
  • The username is not valid, does not exist, or not associated with the account_id given.
  • The username already has permissions to access the campaign_id given.
  • The username is the "owner" id, which always has access to all campaigns.

Error XML Response:

              <response status="error">
                <error>Error message</error>
              </response>
          

Remove Users from Campaign

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

Notes:

• There must be only ONE campaign_id.
• The usernames in the users_list must be separated by a comma. Extra spaces will be trimmed, so don't worry about them.

Example PHP Request:

If you are using PHP, the $data array would look like this:

              $data['API'] = '1.5';
              $data['user_id'] = 'john1970';
              $data['user_password'] 	= '1959caadac9b13dcb3';	
              $data['account_id'] = 'greatwidgets';
              $data['type'] = 'campaign_users';
              $data['action'] = 'remove';
              $data['campaign_id'] = '1234567890123456';
              $data['users_list'] = 'user1,user2,user3,user4,user5';
          

Success XML Response:

              <response status="success">
                  <users_removed>
                      <user>user1</user>
                      <user>user2</user>
                      <user>user3</user>
                      <user>user5</user>
                  </users_removed>
              </response>
          

NOTES:

• Only the users that were actually removed from that campaign's permissions will be shown on the return XML. The following are reasons why a username is not returned:
  • The username is not valid, does not exist, or not associated with the account_id given.
  • The username never had permissions to access the campaign_id given.
  • The username is the "owner" id, or an "admin" level role, which always has access to all campaigns.

Error XML Response:

              <response status="error">
                <error>Error message</error>
              </response>