Invite a User to a Tenant

You can make a POST request to send a user an invitation to a tenant. The user must already be added on the platform. If the user is not already added, see Create a User on the Platform.

When the status parameter is set to invite, the user receives an email containing a link. When the user clicks the link in the email, they’re taken to page where they can activate their account. If the invitation is not accepted within 24 hours, the invitation expires and the administrator needs to send a new invitation. If the invitation is accepted within 24 hours, the user is added to the tenant with the role and permissions associated with the role.

If you don’t want an email to be sent to the user, you can configure the request with the status set to accepted.

Request

Sample request

The request below creates a new invitation:

curl -X POST -H "Content-Type: application/json" 
https://api.cxengage.net/v1/tenants/<tenantId>/users -d '
{	   
	"email":"bDq1B@email.com",
	"roleId":"d68381b1-c8fa-11e5-b38c-5347eb4882ad",
	"status":"invited",
	"defaultIdentityProvider": null,
	"noPassword": null
}'

Request parameters

The table below lists the parameters you can include in a request:

Parameter Required Type Description
tenantId yes UUID The unique identifier of the tenant.
email yes string The user’s email address.
roleId yes UUID The unique identifier of the platform role for the user.
status no string

The current state of the invitation — pending, invited, or accepted.
noPassword no boolean

This setting customizes the user's SSO access. Options include:

  • nil—Assigns the tenant’s default setting to the user.
  • false—Allows users to use their CxEngage username and password to authenticate.
  • true—Prevents users from using their CxEngage username and password to authenticate.
 

In the CxEngage configuration interface, this setting is called CxEngage Authentication.

defaultIdentityProvider no UUID

The unique identifier for the identity provider the user is configured for. If you don't specify an identity provider, the tenant's default identity provider is used.

Response

Sample response

The request returns JSON structured like the example below:

{
    "result": {
        "tenantId": "2336d1ec-c956-47e1-b3b1-fe8fde81b2b4",
        "email": "bDq1B@email.com",
        "activeExtension": {},
        "createdBy": "e05468e0-82b1-11e7-b08f-6e56a766befb",
        "sessionReason": null,
        "defaultIdentityProvider": null,
        "invitationExpiryDate": "2018-06-22T14:33:12Z",
        "updated": "2018-06-21T14:33:12Z",
        "clientLogLevel": null,
        "noPassword": null,
        "supervisorId": null,
        "created": "2018-06-21T14:33:12Z",
        "state": "offline",
        "extension": "06c0d0d0_7560_11e8_8f87_122480149985",
        "updatedBy": "e05468e0-82b1-11e7-b08f-6e56a766befb",
        "status": "accepted",
        "extensions": [
            {
                "description": "Default Twilio extension",
                "provider": "twilio",
                "region": "default",
                "sdkVersion": "default",
                "type": "webrtc",
                "value": "06c0d0d0_7560_11e8_8f87_122480149985"
            }
        ],
        "invitationToken": null,
        "capacityRuleId": null,
        "userId": "06c0d0d0-7560-11e8-8f87-122480149985",
        "sessionStarted": "2018-06-21T14:33:12Z",
        "roleId": "0c4012d0-f9fc-11e7-8bd4-d6eae5a95693",
        "workStationId": ""
    }
}

Response parameters

The response includes the following parameters:

Parameter Type Description
tenantId UUID The unique identifier of the tenant.
email string The user’s email address.
activeExtension string This parameter is null for a user with a status of pending.
createdBy UUID The unique identifier of the user who created this user.
sessionReason string N/A
defaultIdentityProvider UUID The unique identifier for the identity provider the user is configured for. If you don't specify an identity provider, the tenant's default identity provider is used.
invitationExpiryDate string The date, if one is specified, that the user's password expires.
updated string The date and time, in UTC format, when the user was last updated.
noPassword boolean

This setting customizes the user's SSO access. Options include:

  • nil—Assigns the tenant’s default setting to the user.
  • false—Allows users to use their CxEngage username and password to authenticate.
  • true—Prevents users from using their CxEngage username and password to authenticate.
 

In the CxEngage configuration interface, this setting is called CxEngage Authentication.
supervisorId UUID

The unique identifier of the CxEngage user that is supervising this user.
created string The date and time, in UTC format, when the user record was created.
state string Either offline or online.
extension string The unique ID of the extension configured for the user.
updatedBy UUID The ID of the user who last updated the invitation.
status boolean Displays pending until the user accepts the invitation.
extensions object An object contained details about all the extensions that are assigned to a user. Every user profile includes a Twilio extension of the WebRTC type in the Extensions object, regardless of whether Twilio extensions are used on your tenant. The Twilio extension is only visible in the user interface if the Twilio integration is configured and enabled.
invitationToken string The ID of the token used for invitation email links. This is for for internal use only.
capacityRuleId UUID

The unique identifier of the capacity rule assigned to the user.
userId UUID The user’s unique identifier.
sessionStarted string The date and time, in UTC format, when the user first attempted to login into CxEngage.
roleId UUID The unique identified for the role that defines the tenant permissions assigned to the user.
workStationId string

This parameter is used for screen recording integrations.