Create user

The POST /users endpoint creates a new user using the provided values.

In this page

Most URLs in the example code use the following values:

***. To access the API for your region, replace *** with the correct subdomain for your region:
Region URL subdomain Base URL
EMEA emea https://emea.api.newvoicemedia.com
USA nam https://nam.api.newvoicemedia.com
APAC apac https://apac.api.newvoicemedia.com
<ACCESS_TOKEN>. The value represents a bearer access token which you must use to validate every request. Replace <ACCESS_TOKEN> where used with your bearer access token. For information about getting a bearer access token, see How to authenticate with a Vonage Contact Center (VCC) API.

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:

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 POST "https://***.api.newvoicemedia.com/useradmin/users" \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.newvoicemedia.v4+json" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
--data-raw "<JSON BODY>"

Required parameters

{
  "username": "Supervisor_only_required",
  "name": "Supervisor",
  "email": "supervisor@vonage.com",
  "userAccountConfiguration": {
    "role": "Supervisor"
  }
}

All parameters

{
  "username": "Supervisor_full_example",
  "name": "Supervisor",
  "email": "supervisor@vonage.com",
  "ssoExternalId": "supervisor_externalId",
  "active": true,
  "userAccountConfiguration": {
    "role": "Supervisor",
    "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:

Properties listed as agent required are required when the user's role is set to Agent or the actAsAgent property is set to true.

username. (required) A username for the user. The username must be unique.
name. (required) The user’s name, used for display purposes throughout the Vonage Contact Center (VCC) platform.
email. (required) The user’s email address.
active. A Boolean indicating if the user account is active, false indicates archived users. Default value is true.
ssoExternalId. The value that the user uses to log in to Vonage Contact Center using single sign-on. Default is blank.
userAccountConfiguration. (required) Contains user settings.
- role. (required) The user’s role, indicating the tasks that they can perform. Possible values are;
  - Admin
  - Supervisor
  - Wallboard
  - Agent
- actAsAgent. Indicates whether this user has agent capabilities. Possible values are true or false. Default is false for all licenses other than Agent, where it can only ever be true.
- agentConfiguration. Appears if actAsAgent is true. Contains the settings for any agent or user who can act as an agent.
  - agentDisplayId. (agent required) The agent’s unique display ID. Used for display purposes throughout the Vonage Contact Center (VCC) platform.
  - webrtc. Indicates whether this agent can use ContactPad with WebRTC. Possible values are true or false. Default value depends on your account configuration.
  - agentControlWebrtc. Indicates whether this agent can control ContactPad using WebRTC. Possible values are true or false. Requires Agent level WebRTC controls feature.
  - handleMultipleInteractions. Indicates whether this agent can handle more than one interaction. Possible values are true or false. Requires Multiple interaction handling feature.
  - enforcedDispositionCodes. Indicates whether this agent must provide a disposition code for an interaction. Possible values are true or false. Default value depends on your account configuration. Requires Enforced disposition code feature.
  - transcribeCalls. Indicates whether this agent’s calls should be transcribed. Possible values are true or false. Default value is false. Requires Conversation Analyzer feature.
  - screenRecording. Indicates whether this agent’s screen should be recorded during calls. Possible values are true or false. Default value is false. Requires Screen Recording feature.
  - callParking. Indicates whether call parking is turned on for this agent. Possible values are true or false. Default value is false. Requires Call parking feature.
  - salesCadence. (deprecated)
  - outboundAutoanswer. Indicates whether this agent’s outbound calls should be automatically answered. Possible values are true or false. Default value depends on your account configuration. Requires VBC integration.
  - inboundAutoanswer. Indicates whether this agent’s inbound calls should be automatically answered. Possible values are true or false. Default value depends on your account configuration. Requires VBC integration.
  - 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. Default value depends on your account configuration.
  - 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. Default value depends on your account configuration.
  - 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. Default value depends on your account configuration.
  - 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. Default value depends on your account configuration.
  - 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. Default value depends on your account configuration.
  - 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 7200, minimum value is 1. Default value depends on your account configuration.
  - video. Indicates whether agent can use VBC video calling. Possible values are true or false. Requires Visual Engagement feature.
  - transcribeCallsRealTime. Indicates whether agent can use the real-time transcription feature. Possible values are true or false. Requires Service Cloud Voice feature.
  - callRecordingControls. Indicates whether agent can control call recordings using ContactPad. Possible values are true or false. Requires Agent level call recording controls feature.
  - location. The country code for the agent’s physical location used primarily for routing. For example, PL. Default value is GB.
  - telephonyAddress. (agent required)
    - telephoneAddress. (agent required) 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: +, and numbers 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. Default value depends on your account configuration.
    - 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. Default value is true.
    - virtualLocation. The country code for the agent’s virtual location. For example, PL. Default value is GB.
    - 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. These settings are used when an account is confiured for agents to handle multiple interactions at the same time. Requires Multiple interaction handling feature.
    - isAgentLevel. Indicates whether this agent’s capacity settings override the account settings. Possible values are true or false. Default is false.
    - 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. Default value depends on your account configuration.
    - 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. Default value depends on your account configuration.
    - 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. Default value depends on your account configuration.
  - associatedUsers. The non-VCC users that this agent is linked to. Requires VBC integration.
    - 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.

Create Agent with minimal feature set

Although location , nationalDisplay, and virtualLocation are all optional, we recommend explicitly setting them to ensure a users telephone address is confiured correctly.

{
  "username": "AgentName",
  "name": "Agent Name",
  "email": "AgentName@vonage.com",
  "userAccountConfiguration": {
    "role": "Agent",
    "agentConfiguration": {
      "agentDisplayId": "1234",
      "location": "GB",
      "telephonyAddress": {
        "telephoneAddress": "800200",
        "nationalDisplay": true,
        "virtualLocation": "PL"
      }
    }
  }
}

Create Administrator with minimal feature set

{
  "username": "AdminName",
  "name": "Admin",
  "email": "Admin@vonage.com",
  "userAccountConfiguration": {
    "role": "Admin"
  }
}

Create Agent with outbound telephony group override (global voice assurance)

{
  "username": "AgentName",
  "name": "Agent Name",
  "email": "AgentName@vonage.com",
  "userAccountConfiguration": {
    "role": "Agent",
    "agentConfiguration": {
      "agentDisplayId": "1234",
      "webrtc": true,
      "location": "GB",
      "telephonyAddress": {
        "telephoneAddress": "800200",
        "nationalDisplay": true,
        "virtualLocation": "PL",
        "outboundTelephonyRegion": "b4c6e398-ac69-4135-b3fd-64d7a6d14272"
      }
    }
  }
}

Responses

Responses contains the created user object.

Successful response

Successful requests return a 200 Success code and the created user.

Example response

{
  "userId": "e439bc44-f867-4779-a3f5-0802e3e7f816",
  "username": "wallboard",
  "name": "Wallboard",
  "email": "wallboard@vonage.com",
  "userId": "8e22b1fe-d2ea-403d-8c03-50eb21188e79",
  "lastLoginTime": "2021-08-26T07:37:55.465Z",
  "active": true,
  "locked": false,
  "ssoExternalId": "exampleSso",
  "userAccountConfiguration": {
    "role": "Wallboard",
    "chargeable": true,
    "actAsAgent": true,
    "agentConfiguration": {
      "agentDisplayId": "123",
      "webrtc": true,
      "agentControlWebrtc": true,
      "handleMultipleInteractions": true,
      "enforcedDispositionCodes": false,
      "transcribeCalls": true,
      "screenRecording": false,
      "callParking": true,
      "salesCadence": false,
      "outboundAutoanswer": true,
      "inboundAutoanswer": true,
      "outboundWrapUp": 100,
      "backToReadyAfterNoAnswer": 100,
      "backToReadyAfterLineBusy": 90,
      "backToReadyAfterInvalidNumber": 80,
      "backToReadyAfterNetworkIssue": 5,
      "callRatingFrequency": 56,
      "video": true,
      "transcribeCallsRealTime": true,
      "callRecordingControls": true,
      "location": "GB",
      "telephonyAddress": {
        "telephoneAddress": "800100",
        "telephonyExtension": "44",
        "outboundTelephonyRegion": "ab6fd03e-de5a-41fb-9ad8-0e9fcb39f827",
        "nationalDisplay": true,
        "virtualLocation": "PL",
		"preventAutoCallbackNumber" : true,
		"selectedCallbackNumberId": "4c0b6793-a4c9-4075-839e-08fb99ba7efd"  
     },
      "capacity": {
        "isAgentLevel": false,
        "live": 60,
        "nonlive": 15,
        "semilive": 75
      },
      "associatedUsers": [
        {
          "username": "supervisor_vbc",
          "applicationType": "VBC"
        }
      ]
    }
  }
}

where

username. A username for the user. The username is unique in the account.
name. The user’s name, used for display purposes throughout the Vonage Contact Center (VCC) platform.
email. The user’s email address.
userId. The unique ID of the user.
lastLoginTime. Date and time of user’s last login to any Vonage Contact Center account.
active. A Boolean indicating if the user account is active, false indicates archived users.
ssoExternalId. The value that the user uses to log in to Vonage Contact Center using single sign-on.
locked. A Boolean indicating if the user account has been locked out due to failed logins.
userAccountConfiguration. Contains user settings.
- role. The user’s role, indicating the tasks that they can perform. Possible values are Admin, Supervisor, Wallboard, or Agent.
- chargable. Indicates if you are charged for this user, Vonage employee users appear as false. Possible values are true or false.
- actAsAgent. Indicates whether this user has agent capabilities. Possible values are true or false.
- agentConfiguration. Appears if actAsAgent is true. Contains the settings for any agent or user who can act as an agent.
  - agentDisplayId. The agent’s unique ID.
  - 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.
  - 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.
  - 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.
  - 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.
  - 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.
  - 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.
    - 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.

Region	URL subdomain	Base URL
EMEA	emea	https://emea.api.newvoicemedia.com
USA	nam	https://nam.api.newvoicemedia.com
APAC	apac	https://apac.api.newvoicemedia.com