Download PDF
Download page .Users API Method vU11.
.Users API Method vU11
"Users" refers to all non-Agent users of the LiveVox platform. Currently, the Configuration API supports Create, Read, Update, Delete, List, and Get List Info methods for LiveVox user objects. There is also a Find Matching LiveVox Users method that returns a list of LiveVox Users that match specific criteria.
In order to use the methods listed that perform operations on LiveVox User objects, the user of the API must belong to either the Sysadmin or Superuser role. These roles are defined in the LiveVox Configuration Manager and correspond to users who can administer Users through the LiveVox user interfaces. Members of the Superuser role will not be able to perform operations on users that are members of the Sysadmin role, nor will Sysadmin users appear in the results of the List methods described below, when performed by Superusers.
Create LiveVox User
Description: Creates a new LiveVox User.
User Roles: Sysadmin or Superuser
Method: POST /configuration/lvusers
Parameters:
None
Body:
| Key | Type | Mandatory? | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| clientId | Integer (ID) | No | The ID of the Client under which the LiveVox User will be created. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| userName | String | Yes | Username the LiveVox User will use when logging onto the LiveVox platform | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| firstName | String | Yes | First name of the LiveVox User | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| lastName | String | Yes | Last name of the LiveVox User | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| password | String | Yes | Password of the LiveVox User. The password must comply with the same rules as when a User is created or updated through the LVP GUI. Specifically, the password must be a minimum of 8 characters, containing at least 1 digit and cannot match any of the previous 3 passwords. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| String | No | Email address of the LiveVox User | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| role | Enum | Yes | The security role to assign to the new LiveVox User. Possible values are:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| service | Array | No | An array of Service IDs to assign to the LiveVox User.
Note: The user making the request to create the LiveVox User will only be able to assign Services for which he has permission. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| optionalManagerPowers | Object | No | Allows the user to define the "optional powers" for a LiveVox User, when that User is assigned the
Note: If a value for an optional power is not provided when creating a new LiveVox |
Response Code: 201 Created
Body:
| Key | Type | Mandatory? | Description |
|---|---|---|---|
| id | Integer (ID) | Yes | The ID of the newly created LiveVox User. |
Create a new LiveVox User
#Request (JSON)
POST /configuration/lvusers/
Host: localhost.com
Content-Type: application/json
Accept: application/json
{
"firstName": "Manager_User",
"lastName": "Documentation",
"userName": "manager_user",
"service": [
{
"id": 85304
},
{
"id": 87284
}
],
"optionalManagerPowers": {
"editDoNotCallLists": true,
"dialCellPhones": true,
"administerAgents": true,
"dialingStrategies": false,
"campaignTemplates": false,
"uploadCampaigns": false,
"modifyServices": true,
"callRecordingReport": true,
"downloadCallRecording": false,
"readContactEditor": false,
"listenCallRecording": true,
"accessCampaignTemplates": true,
"downloadScreenRecording": true,
"accessAccounts": false,
"downloadVoicemailRecording": true,
"streamVoicemailRecording": true,
"accessTicketing": false,
"voicemailRecordingReport": false
},
"password": "password123",
"email": "abc@gmail.com",
"clientId": "85276",
"role": "MANAGER"
}
#Response (JSON)
201 Created
Content-Type: application/json
{
"id": 161420
}
Example of request to create a LiveVox User, with an invalid password
#Request (JSON)
POST /configuration/lvusers/
Host: localhost.com
Content-Type: application/json
Accept: application/json
{
"firstName": "Manager_User1",
"lastName": "Documentation",
"userName": "manager_user1",
"service": [
{
"id": 85304
},
{
"id": 87284
}
],
"optionalManagerPowers": {
"editDoNotCallLists": true,
"dialCellPhones": true,
"administerAgents": true,
"dialingStrategies": false,
"campaignTemplates": false,
"uploadCampaigns": false,
"modifyServices": true,
"callRecordingReport": true,
"downloadCallRecording": false,
"readContactEditor": false,
"listenCallRecording": true,
"accessCampaignTemplates": true,
"downloadScreenRecording": true,
"accessAccounts": false,
"downloadVoicemailRecording": true,
"streamVoicemailRecording": true,
"accessTicketing": false,
"voicemailRecordingReport": false
},
"password": "",
"email": "abc1@gmail.com",
"clientId": "85276",
"role": "MANAGER"
}
#Response
400 Bad Request
Content-Type: application/json
{
"code": 202,
"message": "Missing required field [password]"
}
Delete LiveVox User
Description: Deletes a LiveVox User.
User Roles: Sysadmin or Superuser
Parameters:
| Path/Query Parameter Name | Variable Name | Type | Mandatory? | Description |
|---|---|---|---|---|
| id | userId | Integer (ID) | True | ID of the LiveVox User you want to delete |
Body:
None
Response Code: 204 No Content
Body:
None
Delete an existing LiveVox User
#Request
DELETE /configuration/lvusers/123662
Host: localhost.com
#Response
204 No Content
Attempt to delete a LiveVox User that does not exist
#Request
DELETE /configuration/lvusers/12345
Host: localhost.com
#Response
404 Not Found
Find Matching LiveVox Users
Description: Retrieves list of LiveVox Users who match either a supplied Username or Last Name and, optionally, role. Searches are case-insensitive, and partial matches are supported.
User Roles: Sysadmin or Superuser
Method: POST /configuration/lvusers/search?[client={clientId}&]count={n}&offset={n}
Parameters:
| Path/Query Parameter Name | Variable Name | Type | Mandatory? | Description |
|---|---|---|---|---|
| client | clientId | Integer (ID) | No | Specifies the Client for which you want to retrieve the list of matching Agents. |
| count | n | Integer | Yes | Specifies the number of items to return in the list. There is a hard cap of 1000 items. |
| offset | n | Integer | Yes | Specifies the offset from 0, based on count, to start listing from. |
Body:
| Key or Attribute | Type | Mandatory? | Description |
|---|---|---|---|
| username | String | Yes* | Username of the LV User to search for |
| lastName | String | Yes* | Last name of LV User(s) to search for |
| role | String | No | Filters the results so that only matching Users with the specified role are returned. |
*Only one of the two elements (username or lastName) can be used as the primary search criterion for this request.
- It is the responsibility of the client application to ensure that only one type of primary search criterion is included in the query. The LiveVox API does not provide this validation logic on the server. If more than one type of primary search criterion is included in the query, the result is unpredictable.
- Partial matches are supported, and the search is case-insensitive. That is, if
jamis provided for thelastNameparameter, it could return matches such as Jamison, James, Rajam, etc.
Response Code: 200 OK
Body:
| Key | Type | Mandatory? | Description | ||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| next | URI | No | A URI for the next page of entries. If next is not present, or blank, then there are no pages after this one. | ||||||||||||||||||||||||||||||||
| user | Array | No | A container for a page of LiveVox User entries. The page size is controlled via count and offset in the request.
|
Retrieve the LiveVox User(s) who match the provided username and role
#Request (JSON)
POST /configuration/lvusers/search?count=10&client=49551&offset=0
Host: localhost.com
Content-Type: application/json
Accept: application/json
{
"username":"manager1",
"role":"MANAGER"
}
#Response (JSON)
200 OK
Content-Type: application/json
{
"user": [
{
"firstName": "Manager",
"lastName": "One",
"userName": "manager1",
"lastLogin": 1549386919000,
"lastLoginIp": "201.103.105.141",
"id": 117368,
"role": "MANAGER"
}
]
}
Retrieve the LV User(s) who match the provided last name
#Request (JSON)
POST /configuration/lvusers/search?count=10&client=4199&offset=0
Host: localhost.com
Content-Type: application/json
Accept: application/json
{
"lastName":"Smith"
}
#Response (JSON)
200 OK
Content-Type: application/json
{
"user": [
{
"id": 97747,
"userName": "admin_jsmith",
"firstName": "Jerry",
"lastName": "Smith",
"lastLogin": null,
"role": "MANAGER"
},
{
"id": 97853,
"userName": "report_Todd",
"firstName": "Todd",
"lastName": "Smith",
"lastLogin": null,
"role": "AUDITOR"
},
{
"id": 98784,
"userName": "asmith1",
"firstName": "Alison",
"lastName": "Smith",
"lastLogin": null,
"role": "MANAGER"
},
{
"id": 99748,
"userName": "janice_smith",
"firstName": "Janice",
"lastName": "Smithsonian",
"lastLogin": null,
"role": "SYS_ADMIN"
},
{
"id": 113766,
"userName": "asmith2",
"firstName": "Adrienne",
"lastName": "Smithers",
"lastLogin": null,
"role": "AUDITOR"
},
{
"id": 114967,
"userName": "abel_smith",
"firstName": "Abel",
"lastName": "Smith",
"lastLogin": null,
"role": "SYS_ADMIN"
}
],
"next": null
}
Invalid FindMatchingLiveVoxUsers request
#Request (JSON)
POST /configuration/lvusers/search?count=10&client=4199&offset=0
Host: localhost.com
Content-Type: application/json
Accept: application/json
{
"lastName":"Smith",
"username":"jsmith"
}
#Response (JSON)
400 Bad Request
Content-Type: application/json
{
"errorCode": 202,
"errorMessage": "Invalid input [exactly one of username or lastName is required]"
}
Get LiveVox User List Info
Description: Gets metadata for a list of Users.
User Roles: Sysadmin or Superuser
Method: GET /configuration/lvusers/info[?client={clientId}]
Parameters:
| Path/Query Parameter Name | Variable Name | Type | Mandatory? | Description |
|---|---|---|---|---|
| client | clientId | Integer (ID) | No | Restricts the list to entries that are specifically associated with this particular Client. |
Body:
None
Response Code: 200 OK
Body:
| Key or Attribute | Type | Mandatory? | Description |
|---|---|---|---|
| size | Integer | Yes | Total number of entries in the list. |
| lastModified | DateTime | No | The last date & time that the list was updated. This information might not be available. This is formatted according to the definition of dateTime in the XML Schema specification. For JSON responses, it is represented as the number of milliseconds since midnight on January 1, 1970 (GMT). |
If a user with a Superuser role makes this request, the size of the list returned in the response will not take into account any users belonging to the Sysadmin role.
Get the metadata for a list of Users, filtered by a Client
#Request (JSON)
GET /configuration/lvusers/info?client=4199
Host: localhost.com
Content-Type: application/json
Accept: application/json
#Response (JSON)
200 OK
Content-Type: application/json
{
"size": 117,
"lastModified": 1245152417000
}
List LiveVox Users
Description: Lists Users configured for a Client.
User Roles: Sysadmin or Superuser
Method: GET /configuration/lvusers?[client={clientId}&]count={n}&offset={n}
Parameters:
| Path/Query Parameter Name | Variable Name | Type | Mandatory? | Description |
|---|---|---|---|---|
| client | clientId | Integer (ID) | No | Specifies the Client for which you want to retrieve the list of Users |
| count | n | Integer | Yes | Specifies the number of items to return in the list. There is a hard cap of 1000 items. |
| offset | n | Integer | Yes | Specifies the offset from 0, based on count, to start listing from. |
Body:
None
Response Code: 200 OK
Body:
| Key | Type | Mandatory? | Description | ||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| next | URI | No | A URI for the next page of entries. If next is not present, or blank, then there are no pages after this one. | ||||||||||||||||||||||||||||||||
| user | Array | No | A container for a page of User entries. The page size is controlled via count and offset in the request.
|
If a user with a Superuser role makes this request, the response will not include any users belonging to the Sysadmin role.
Get a list of Users for a Client
#Request (JSON)
GET /configuration/lvusers?count=5&client=49551&offset=10
Host: localhost.com
Content-Type: application/json
Accept: application/json
#Response (JSON)
200 OK
Content-Type: application/json
{
"user": [
{
"firstName": "livevox",
"lastName": "lvqapass1",
"userName": "LV_ATG",
"lastLogin": 1551088892000,
"lastLoginIp": "52.2.171.102",
"id": 157924,
"role": "SYS_ADMIN"
},
{
"firstName": "DO NOT DELETE",
"lastName": "ATG USER",
"userName": "LV_ATG_DEMO",
"lastLogin": 1538640002000,
"lastLoginIp": "184.72.85.204",
"id": 161821,
"role": "SYS_ADMIN"
},
{
"firstName": "DO NOT DELETE",
"lastName": "ATG USER",
"userName": "LV_ATG_DEV",
"lastLogin": 1551081601000,
"lastLoginIp": "54.84.56.43",
"id": 161820,
"role": "SYS_ADMIN"
},
{
"firstName": "DO NOT DELETE",
"lastName": "ATG USER",
"userName": "LV_ATG_STG",
"id": 159105,
"role": "SYS_ADMIN"
},
{
"firstName": "H",
"lastName": "P",
"userName": "LV_HPTEST",
"lastLogin": 1515938173000,
"lastLoginIp": "67.191.138.103",
"id": 158020,
"role": "SYS_ADMIN"
}
],
"next": "configuration/lvusers/?client=49551&offset=15&count=5"
}
Read LiveVox User
Description: Gets information about a User.
User Roles: All users, however users other than sysadmin or superuser can only read their own details
Method: GET /configuration/lvusers/{id}
Parameters:
| Path/Query Parameter Name | Variable Name | Type | Mandatory? | Description |
|---|---|---|---|---|
| id | userId | Integer (ID) | Yes | The ID of the User you want to query |
Body:
None
Response Code: 200 OK
Body:
| Key | Type | Mandatory? | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| userName | String | Yes | Name used by the User when logging into the LiveVox platform | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| firstName | String | Yes | First name of the User | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| lastName | String | Yes | Last name of the User | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| String | Yes | Email address of the User. Used to provide alerts to the User. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| role | Enum | Yes | The security role of the LiveVox User. Possible values are:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| clientId | Integer (ID) | No | ID of the Client under which the User is registered | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| lastLogin | DateTIme | No | Date & Time of the last successful login by the User | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| lastLoginIp | String | No | The IP address from which the agent logged in the last time | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| locked | Boolean | Yes | Indicates whether the User's account is locked, which can occur when the User exceeds the maximum number of allowable invalid login attempts. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| passwordLastModified | DateTime | No | Indicates the last date/time the User's password was changed. Will only display if password management is enabled. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| service | Array | No | Array of Service IDs the User has permission to access.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| alert | Array | No | Array of Alerts configured for the User to receive.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| optionalManagerPowers | Object | No | Specifies the additional security privileges assigned to this User. Only applies when the User is a "Manager".
|
- A user with a
Superuserrole will not be able to use this request to retrieve information about a user belonging to theSysadminrole. If this is attempted, the response will be a403error. - The list of Services in the response will only include Service IDs to which the requesting user has permission.
Read configuration properties of an existing LiveVox User
#Request (JSON)
GET /configuration/lvusers/161420
Host: localhost.com
Content-Type: application/json
Accept: application/json
#Response (JSON)
200 OK
Content-Type: application/json
{
"firstName": "Manager_User",
"lastName": "Documentation",
"userName": "manager_user",
"lastLogin": 1602837878000,
"lastLoginIp": "10.40.234.107",
"service": [
{
"id": 85304
},
{
"id": 87284
}
],
"alert": [],
"optionalManagerPowers": {
"editDoNotCallLists": true,
"dialCellPhones": true,
"administerAgents": true,
"dialingStrategies": false,
"campaignTemplates": false,
"uploadCampaigns": false,
"modifyServices": true,
"callRecordingReport": true,
"downloadCallRecording": false,
"readContactEditor": false,
"listenCallRecording": true,
"accessCampaignTemplates": true,
"downloadScreenRecording": true,
"accessAccounts": false,
"downloadVoicemailRecording": true,
"streamVoicemailRecording": true,
"accessTicketing": false,
"voicemailRecordingReport": false
},
"email": "abc@gmail.com",
"clientId": 85276,
"role": "MANAGER"
"locked": false,
"passwordLastModified": 1602765060000
}
Update LiveVox User
Description: Updates the properties of a LiveVox User.
Services cannot be assigned or removed with this method. To perform those updates, you need to use the discrete methods Update LiveVox User Add Service and Update LiveVox User Remove Service.
User Roles: Sysadmin or Superuser
Method: PUT /configuration/lvusers/{id}
Parameters:
| Path/Query Parameter Name | Variable Name | Type | Mandatory? | Description |
|---|---|---|---|---|
| id | userId | Integer (ID) | Yes | The ID of the LiveVox User you want to update |
Body:
| Key | Type | Mandatory? | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| firstName | String | No | Updated first name of the LiveVox User | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| lastName | String | No | Updated last name of the LiveVox User | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| password | String | No | New password for the LiveVox User. The password must comply with the same rules as when a User is created or updated through the LVP GUI. Specifically, the password must be a minimum of 8 characters, containing at least 1 digit and cannot match any of the previous 4 passwords. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| String | No | Updated email address of the LiveVox User | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| role | Enum | No | Updated security role of the LiveVox User. Possible values are:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| unlock | Boolean | No | When set to true, you can unlock a LiveVox User whose account has been locked out by the system–for example when the User has exceeded the maximum number of allowable invalid login attempts. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| optionalManagerPowers | Object | No | Allows the user to updated the "optional powers" for a LiveVox User, when that User is assigned the
Note: If a value for a particular optional power is omitted when updating a LiveVox |
The body of your request must contain at least one key (or attribute) that you want to update. Keys (or attributes) that you don't want to update can be omitted from the request.
Response Code: 204 No Content
Body:
None
Update properties of a LiveVox User
#Request (JSON)
PUT /configuration/lvusers/122935
Host: localhost.com
Content-Type: application/json
Accept: application/json
{
"optionalManagerPowers": {
"editDoNotCallLists": false
},
"firstName": "Manager1",
"email": "manager1@livevox.com"
}
#Response (JSON)
204 No Content
Unlock a LiveVox User whose account has been locked
#Request (JSON)
PUT /configuration/lvusers/122935
Host: localhost.com
Content-Type: application/json
Accept: application/json
{
"unlock": true
}
#Response (JSON)
204 No Content
Example of request to update a LiveVox User, with an invalid password
#Request (JSON)
PUT /configuration/lvusers/122935
Host: localhost.com
Content-Type: application/json
Accept: application/json
{
"password": "123"
}
#Response (JSON)
400 Bad Request
Content-Type: application/json
{
"code": 202,
"message": "Invalid password [Password must be at least 8 characters long]"
}
Update LiveVox User Add Service
Description: Assigns a Service to an existing LiveVox User.
After using this method to give a User access to a Service you can either create a new session id using the login method or wait 5 min for the permissions of the current session id to update.
User Roles: Sysadmin or Superuser
Method: PUT /configuration/lvusers/{user}/services/{id}
Parameters:
| Path/Query Parameter Name | Variable Name | Type | Mandatory? | Description |
|---|---|---|---|---|
| user | userId | Integer (ID) | Yes | ID of the LiveVox User to whom you want to assign the Service |
| id | serviceId | Integer (ID) | Yes | ID of the Service you want to assign to the LiveVox User |
Body:
None
Response Code: 204 No Content
Body:
None
Assign a Service to an existing LiveVox User
#Request (JSON)
PUT /configuration/lvusers/122935/Services/17885
Host: localhost.com
Content-Type: application/json
Accept: application/json
#Response
204 No Content
Update LiveVox User Remove Service
Description: Removes a Service assignment from an existing LiveVox User.
User Roles: Sysadmin or Superuser
Method: DELETE /configuration/lvusers/{user}/services/{id}
Parameters:
| Path/Query Parameter Name | Variable Name | Type | Mandatory? | Description |
|---|---|---|---|---|
| user | userId | Integer (ID) | Yes | ID of the LiveVox User from whom you want to remove the Service assignment |
| id | serviceId | Integer (ID) | Yes | ID of the Service you want to unassign from the LiveVox User |
Body:
None
Response Code: 204 No Content
Body:
None
Remove a Service assignment from an existing LiveVox User
#Request (JSON)
DELETE /configuration/lvusers/122935/services/17885
Host: localhost.com
Content-Type: application/json
Accept: application/json
#Response
204 No Content