Update user by user ID
- Helen Griffith
- Martyn Frank
Owned by Helen Griffith
The PATCH /users/{userId} endpoint updates the user matching the provided user ID with provided values.
In this page
Headers
Header parameters in Requests (User Admin API) apply to this endpoint.
Authorization scopes supported:
| Scope | Access granted |
|---|---|
users:write | Entire endpoint |
Parameters
The endpoint accepts the following path parameter:
userId
Type | Required | Example |
|---|---|---|
| String | True | 8e22b1fe-d2ea-403d-8c03-50eb21188e79 |
The user ID of the user to update.
acceptArchiveInMultipleAccounts
| Type | Required | Example |
|---|---|---|
| boolean | False | true |
This flag must be set to true if user being archived is linked to multiple accounts. Otherwise error message will appear.
allowOverages
| Type | Required | Example |
|---|---|---|
| boolean | False | false |
This flag must be set to true for a user to create an agent when the number of used agent licenses exceeds the account's license limit.
Requests
Example request
curl -L -X PATCH "https://***.api.newvoicemedia.com/useradmin/users/8e22b1fe-d2ea-403d-8c03-50eb21188e79" \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.newvoicemedia.v4+json" \ -H "Authorization: Bearer <ACCESS_TOKEN>" \ --data-raw "<JSON BODY>"
The endpoint requires a user object in JSON format as in the request body.
Example request - archive a user who is linked to multiple accounts
curl -L -X PATCH "https://***.api.newvoicemedia.com/useradmin/users/8e22b1fe-d2ea-403d-8c03-50eb21188e79?acceptArchiveInMultipleAccounts=true" \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.newvoicemedia.v4+json" \ -H "Authorization: Bearer <ACCESS_TOKEN>" \ --data-raw "<JSON BODY>"
The endpoint requires a user object in JSON format as in the request body.
Example request - allow overages
curl -L -X PATCH "https://***.api.newvoicemedia.com/useradmin/users/8e22b1fe-d2ea-403d-8c03-50eb21188e79?allowOverages=true" \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.newvoicemedia.v4+json" \ -H "Authorization: Bearer <ACCESS_TOKEN>" \ --data-raw "<JSON BODY>"
The endpoint requires a user object in JSON format as in the request body.
All parameters
{
"name": "Supervisor",
"email": "supervisor@vonage.com",
"ssoExternalId": "supervisor_externalId",
"active": true,
"userAccountConfiguration": {
"role": "Supervisor",
"actAsAgent": true,
"agentConfiguration": {
"agentDisplayId": "626",
"webrtc": true,
"agentControlWebrtc": true,
"handleMultipleInteractions": true,
"enforcedDispositionCodes": true,
"transcribeCalls": true,
"screenRecording": false,
"callParking": true,
"salesCadence": false,
"outboundAutoanswer": true,
"inboundAutoanswer": true,
"outboundWrapUp": 200,
"outboundWrapUpDefault": true,
"backToReadyAfterNoAnswer": 100,
"backToReadyAfterNoAnswerDefault": true,
"backToReadyAfterLineBusy": 1000,
"backToReadyAfterLineBusyDefault": true,
"backToReadyAfterInvalidNumber": 300,
"backToReadyAfterInvalidNumberDefault": true,
"backToReadyAfterNetworkIssue": 200,
"backToReadyAfterNetworkIssueDefault": true,
"callRatingFrequency": 50,
"callRatingFrequencyDefault": true,
"video": true,
"transcribeCallsRealTime": false,
"callRecordingControls": true,
"location": "GB",
"telephonyAddress": {
"telephoneAddress": "800200",
"telephonyExtension": "44",
"outboundTelephonyRegion": "b4c6e398-ac69-4135-b3fd-64d7a6d14272",
"nationalDisplay": true,
"virtualLocation": "PL",
"preventAutoCallbackNumber" : true,
"selectedCallbackNumberId": "4c0b6793-a4c9-4075-839e-08fb99ba7efd"
},
"capacity": {
"isAgentLevel": true,
"live": 50,
"nonLive": 33,
"semiLive": 40
},
"associatedUsers": [
{
"username": "supervisor_vbc",
"applicationType": "VBC"
}
]
}
}
}
where:
name. The user’s name, used for display purposes throughout the Vonage Contact Center (VCC) platform.email. The user’s email address.active. Date and time of user’s last login to any Vonage Contact Center account.ssoExternalId. The value that the user uses to log in to Vonage Contact Center using single sign-on.userAccountConfiguration. Contains user settings.role. The user’s role, indicating the tasks that they can perform. Possible values are Admin, Supervisor, Wallboard, or Agent.actAsAgent. Indicates whether this user has agent capabilities. Possible values are true or false.agentConfiguration. Appears ifactAsAgentis true. Contains the settings for any agent or user who can act as an agent.agentDisplayId. The agent’s unique ID which acts as a display ID. This value can be set only once and at the same time as settingactAsAgentfor a supervisor or admin user to true.webrtc. Indicates whether this agent can use ContactPad with WebRTC. Possible values are true or false.agentControlWebrtc. Indicates whether this agent can control ContactPad when using WebRTC. Possible values are true or false.handleMultipleInteractions. Indicates whether this agent can handle more than one interaction. Possible values are true or false.enforcedDispositionCodes. Indicates whether this agent must provide a disposition code for an interaction. Possible values are true or false.transcribeCalls. Indicates whether this agent’s calls should be transcribed. Possible values are true or false.screenRecording. Indicates whether this agent’s screen should be recorded during calls. Possible values are true or false.callParking. Indicates whether call parking is turned on for this agent. Possible values are true or false.salesCadence. Indicates whether Cadence is turned on for this agent. Possible values are true or false.outboundAutoanswer. Indicates whether this agent’s outbound calls should be automatically answered. Possible values are true or false.inboundAutoanswer. Indicates whether this agent’s inbound calls should be automatically answered. Possible values are true or false.outboundWrapUp. The maximum time, in seconds, that the agent can remain in a Wrap Up (Auto) state after an outbound call ends. Maximum value is 7200, minimum value is 1.outboundWrapUpDefault. Resets the value ofoutboundWrapUpto its default. Cannot be used in a request along withoutboundWrapUp.backToReadyAfterNoAnswer. The maximum time, in seconds, that the agent can remain in an unexpected state if they do not answer their phone (No Answer state appears in ContactPad). Maximum value is 7200, minimum value is 1.backToReadyAfterNoAnswerDefault. ResetsbackToReadyAfterNoAnswervalue to its default. Cannot be used in a request along withbackToReadyAfterNoAnswer.backToReadyAfterLineBusy. The maximum time, in seconds, that the agent can remain in an unexpected state if their line is busy (Line Busy state appears in ContactPad). Maximum value is 7200, minimum value is 1.backToReadyAfterLineBusyDefault. ResetsbackToReadyAfterLineBusyto its default. Cannot be used in a request along withbackToReadyAfterLineBusy.backToReadyAfterInvalidNumber. The maximum time, in seconds, that the agent can remain in a fault state if they have an invalid number in their settings (Network Congestion state appears in ContactPad). Maximum value is 7200, minimum value is 1.backToReadyAfterInvalidNumberDefault. ResetsbackToReadyAfterInvalidNumberto its default. Cannot be used in a request along withbackToReadyAfterInvalidNumber.backToReadyAfterNetworkIssue. The maximum time, in seconds, that the agent can remain in a fault state due to a network issue (Fault on Line state appears in ContactPad). Maximum value is 7200, minimum value is 1.backToReadyAfterNetworkIssueDefault. ResetsbackToReadyAfterNetworkIssueto its default. Cannot be used in a request along withbackToReadyAfterNetworkIssue.callRatingFrequency. The percentage of the agent’s calls that they must rate if the Post Call Quality Rating feature is turned on. If 100, the agent must rate all calls. Maximum value is 100, minimum value is 0.video. Indicates whether agent can use VBC video calling. Possible values are true or false.transcribeCallsRealTime.Indicates whether agent can use the real-time transcription feature. Possible values are true or false.callRecordingControls. Indicates whether agent can control call recordings using ContactPad. Possible values are true or false.location. The country code for the agent’s physical location used primarily for routing. For example, GB.telephonyAddress.telephoneAddress. The agent’s phone number in national format. Vonage Contact Center routes calls to this number. Maximum length is 255. Can contain any of the following characters: \+?[0-9]+.telephonyExtension.outboundTelephonyRegion. The telephony region in which the agent is located. Vonage Contact Center uses an agent’s telephony region to determine the telephony server to use when the agent makes an outbound call.nationalDisplay. Whether telephone numbers that the agent sees in the Vonage Contact Center platform are displayed in national format. Possible values are true or false.virtualLocation. The country code for the agent’s virtual location. For example, PL.preventAutoCallbackNumber. Indicates whether the agent is allowed to override the automatically presented callback number. Possible values are true or false.selectedCallbackNumberId. The callback number's unique ID.
capacity.isAgentLevel. Indicates whether this agent’s capacity settings override the account settings. Possible values are true or false. Setting this to false will deletelive,nonliveandsemilivevalues assigned to agent.live. The percentage of this agent’s capacity that is used by a live interaction, such as a phone call. For example, 75. Maximum value is 100, minimum is 51.nonlive. The percentage of this agent’s capacity that is used by a non-live interaction, such as an email. For example, 25. Maximum value is 100, minimum is 1.semilive. The percentage of this agent’s capacity that is used by a semi-live interaction, such as a chat. For example, 33. Maximum value is 100, minimum is 1.
associatedUsers. The non-VCC users that this agent is linked to.username. The username of a non-VCC user that this agent is linked to. For example, supervisor_vbc.applicationType. The application that the non-VCC user that is linked to this agent is from. For example, VBC.
Archive user
{
"active": false
}
Make user an admin
{
"userAccountConfiguration": {
"role": "Admin"
}
}
Update user to act as an agent
{
"userAccountConfiguration": {
"actAsAgent": true,
"agentConfiguration": {
"agentDisplayId": "123456",
"telephonyAddress": {
"telephoneAddress": "0123456789"
}
}
}
}
Enable WebRTC and auto answer
{
"userAccountConfiguration": {
"agentConfiguration": {
"webrtc": true,
"outboundAutoanswer": true,
"inboundAutoanswer": true
}
}
}
}
Update name and email address
{
"name": "Supervisor",
"email": "supervisor@vonage.com"
}
Set user's phone number
{
"userAccountConfiguration": {
"agentConfiguration": {
"telephonyAddress": {
"telephoneAddress": "0123456789"
}
}
}
}
Reset call rating frequency to default
{
"userAccountConfiguration": {
"agentConfiguration": {
"callRatingFrequencyDefault": true
}
}
}
Responses
The response contains the updated user object.
Successful response
Successful requests return a 200 Success code and the updated user.
Example response
{
"userId": "06962e51-7201-e170-6b95-137a032c1b1a",
"username": "Supervisor_full_example",
"name": "Supervisor",
"email": "supervisor@vonage.com",
"ssoExternalId": "supervisor_externalId",
"active": true,
"locked": false,
"userAccountConfiguration": {
"role": "Normal",
"actAsAgent": true,
"agentConfiguration": {
"agentDisplayId": "1234",
"webrtc": true,
"agentControlWebrtc": true,
"handleMultipleInteractions": true,
"enforcedDispositionCodes": true,
"transcribeCalls": true,
"screenRecording": false,
"callParking": true,
"salesCadence": false,
"outboundAutoanswer": true,
"inboundAutoanswer": true,
"outboundWrapUp": 200,
"backToReadyAfterNoAnswer": 100,
"backToReadyAfterLineBusy": 1000,
"backToReadyAfterInvalidNumber": 300,
"backToReadyAfterNetworkIssue": 200,
"callRatingFrequency": 50,
"video": true,
"transcribeCallsRealTime": true,
"callRecordingControls": true,
"location": "GB",
"telephonyAddress": {
"telephoneAddress": "800200",
"telephonyExtension": "44",
"outboundTelephonyRegion": "b4c6e398-ac69-4135-b3fd-64d7a6d14272",
"nationalDisplay": true,
"virtualLocation": "PL",
"preventAutoCallbackNumber" : true,
"selectedCallbackNumberId": "4c0b6793-a4c9-4075-839e-08fb99ba7efd"
},
"capacity": {
"isAgentLevel": true,
"live": 50,
"nonLive": 33,
"semiLive": 40
},
"associatedUsers": [
{
"username": "supervisor_vbc",
"applicationType": "VBC"
}
]
}
}
}
where:
name. The user’s name, used for display purposes throughout the Vonage Contact Center (VCC) platform.email. The user’s email address.active. Date and time of user’s last login to any Vonage Contact Center account.ssoExternalId. The value that the user uses to log in to Vonage Contact Center using single sign-on.userAccountConfiguration. Contains user settings.role. The user’s role, indicating the tasks that they can perform. Possible values are Admin, Supervisor, Wallboard, or Agent.actAsAgent. Indicates whether this user has agent capabilities. Possible values are true or false.agentConfiguration. Appears ifactAsAgentis true. Contains the settings for any agent or user who can act as an agent.agentDisplayId. The agent’s unique ID which acts as a display ID. This value can be set only once and at the same time as settingactAsAgentfor a supervisor or admin user to true.webrtc. Indicates whether this agent can use ContactPad with WebRTC. Possible values are true or false.agentControlWebrtc. Indicates whether this agent can control ContactPad when using WebRTC. Possible values are true or false.handleMultipleInteractions. Indicates whether this agent can handle more than one interaction. Possible values are true or false.enforcedDispositionCodes. Indicates whether this agent must provide a disposition code for an interaction. Possible values are true or false.transcribeCalls. Indicates whether this agent’s calls should be transcribed. Possible values are true or false.screenRecording. Indicates whether this agent’s screen should be recorded during calls. Possible values are true or false.callParking. Indicates whether call parking is turned on for this agent. Possible values are true or false.salesCadence. Indicates whether Cadence is turned on for this agent. Possible values are true or false.outboundAutoanswer. Indicates whether this agent’s outbound calls should be automatically answered. Possible values are true or false.inboundAutoanswer. Indicates whether this agent’s inbound calls should be automatically answered. Possible values are true or false.outboundWrapUp. The maximum time, in seconds, that the agent can remain in a Wrap Up (Auto) state after an outbound call ends. Maximum value is 7200, minimum value is 1.outboundWrapUpDefault. Resets the value ofoutboundWrapUpto its default. Cannot be used in a request along withoutboundWrapUp.backToReadyAfterNoAnswer. The maximum time, in seconds, that the agent can remain in an unexpected state if they do not answer their phone (No Answer state appears in ContactPad). Maximum value is 7200, minimum value is 1.backToReadyAfterNoAnswerDefault. ResetsbackToReadyAfterNoAnswervalue to its default. Cannot be used in a request along withbackToReadyAfterNoAnswer.backToReadyAfterLineBusy. The maximum time, in seconds, that the agent can remain in an unexpected state if their line is busy (Line Busy state appears in ContactPad). Maximum value is 7200, minimum value is 1.backToReadyAfterLineBusyDefault. ResetsbackToReadyAfterLineBusyto its default. Cannot be used in a request along withbackToReadyAfterLineBusy.backToReadyAfterInvalidNumber. The maximum time, in seconds, that the agent can remain in a fault state if they have an invalid number in their settings (Network Congestion state appears in ContactPad). Maximum value is 7200, minimum value is 1.backToReadyAfterInvalidNumberDefault. ResetsbackToReadyAfterInvalidNumberto its default. Cannot be used in a request along withbackToReadyAfterInvalidNumber.backToReadyAfterNetworkIssue. The maximum time, in seconds, that the agent can remain in a fault state due to a network issue (Fault on Line state appears in ContactPad). Maximum value is 7200, minimum value is 1.backToReadyAfterNetworkIssueDefault. ResetsbackToReadyAfterNetworkIssueto its default. Cannot be used in a request along withbackToReadyAfterNetworkIssue.callRatingFrequency. The percentage of the agent’s calls that they must rate if the Post Call Quality Rating feature is turned on. If 100, the agent must rate all calls. Maximum value is 100, minimum value is 0.video. Indicates whether agent can use VBC video calling. Possible values are true or false.transcribeCallsRealTime.Indicates whether agent can use the real-time transcription feature. Possible values are true or false.callRecordingControls. Indicates whether agent can control call recordings using ContactPad. Possible values are true or false.location. The country code for the agent’s physical location used primarily for routing. For example, GB.telephonyAddress.telephoneAddress. The agent’s phone number in national format. Vonage Contact Center routes calls to this number. Maximum length is 255. Can contain any of the following characters: \+?[0-9]+.telephonyExtension.outboundTelephonyRegion. The telephony region in which the agent is located. Vonage Contact Center uses an agent’s telephony region to determine the telephony server to use when the agent makes an outbound call.nationalDisplay. Whether telephone numbers that the agent sees in the Vonage Contact Center platform are displayed in national format. Possible values are true or false.virtualLocation. The country code for the agent’s virtual location. For example, PL.preventAutoCallbackNumber. Indicates whether the agent is allowed to override the automatically presented callback number. Possible values are true or false.selectedCallbackNumberId. The callback number's unique ID.
capacity.isAgentLevel. Indicates whether this agent’s capacity settings override the account settings. Possible values are true or false. Setting this to false will deletelive,nonliveandsemilivevalues assigned to agent.live. The percentage of this agent’s capacity that is used by a live interaction, such as a phone call. For example, 75. Maximum value is 100, minimum is 51.nonlive. The percentage of this agent’s capacity that is used by a non-live interaction, such as an email. For example, 25. Maximum value is 100, minimum is 1.semilive. The percentage of this agent’s capacity that is used by a semi-live interaction, such as a chat. For example, 33. Maximum value is 100, minimum is 1.
associatedUsers. The non-VCC users that this agent is linked to.username. The username of a non-VCC user that this agent is linked to. For example, supervisor_vbc.applicationType. The application that the non-VCC user that is linked to this agent is from. For example, VBC.
Try it out
For information, see Trying out Vonage Contact Center APIs.