/icws/connection

POST

/icws/connection

Logs a client in, creating a connection representation for a session with the Interaction Center server. See Connecting for more detailed information on how to create a session with the Interaction Center server, including how to properly handle a 503 error response.
Feature Version
connection 1

Request

Parameters
Type
Name
Comments
Header
Accept-Language

Required

The Accept-Language parameter is used by the server to determine the primary language of the client. This header determines the language for any human-readable text, as well as formats for time, dates, and money. The client must create a new connection with a different value of Accept-Language to change the primary language.

    Query
    include

    A comma-delimited list of additional fields to include in the response. Options are:

    • version
    • features
    • server-time - Added in version 4.
    • default-workstation - Added in version 5.
    • purecloud-integration - Added in version 8.
    • effective-station - Added in version 10.
    Feature Version
    connection 3

      Representations
      baseAuthConnectionRequestSettings
      Property
      Value
      Comments

      Multiple options:

      The value can be assigned any of the following options.
      __type
      "urn:inin.com:connection:authTokenConnectionRequestSettings"

      Required

      The JSON type representing this option.
      applicationName
      String

      Required

      Used by the Interaction Center and Interaction Center applications to display an association between an Interaction Center session and an application. It is part of the information that is exposed by the sessionInformation message of the Session API.
      marketPlaceApplicationLicenseName
      String

      The PureConnect MarketPlace application's license name. Only for use in MarketPlace applications. When setting this, the marketPlaceApplicationCode property should also be set. This value can be obtained from the MarketPlace application's registration information.

      marketPlaceApplicationCode
      String

      The PureConnect MarketPlace application code. Only for use in MarketPlace applications. When setting this, the marketPlaceApplicationLicenseName property should also be set. This value can be obtained from the MarketPlace application's registration information.

      authTokenSeed
      Guid

      Required

      This seed will be used in the generation of the auth token. It should be generated by the caller. The seed is encoded as a part of the returned auth token.

      authToken
      String

      Required

      The auth token is used to create a new session. This can be aquired from POST /icws/{sessionId}/connection/unique-auth-token.

      authTokenSourceSession
      String

      Required

      The Session ID of the session that was used to generate the auth token.

      disconnectSourceSession
      Boolean
      Specifies if the current source session should be disconnected. By default the value is false.
      Feature Version
      connection 3
      __type
      "urn:inin.com:connection:icAuthConnectionRequestSettings"

      Required

      The JSON type representing this option.
      applicationName
      String

      Required

      Used by the Interaction Center and Interaction Center applications to display an association between an Interaction Center session and an application. It is part of the information that is exposed by the sessionInformation message of the Session API.
      marketPlaceApplicationLicenseName
      String

      The PureConnect MarketPlace application's license name. Only for use in MarketPlace applications. When setting this, the marketPlaceApplicationCode property should also be set. This value can be obtained from the MarketPlace application's registration information.

      marketPlaceApplicationCode
      String

      The PureConnect MarketPlace application code. Only for use in MarketPlace applications. When setting this, the marketPlaceApplicationLicenseName property should also be set. This value can be obtained from the MarketPlace application's registration information.

      userID
      String

      Required

      The Interaction Center user ID to log in with.

      password
      String

      Required

      The Interaction Center password for the supplied user ID.

      __type
      "urn:inin.com:connection:singleSignOnTokenConnectionRequestSettings"

      Required

      The JSON type representing this option.
      applicationName
      String

      Required

      Used by the Interaction Center and Interaction Center applications to display an association between an Interaction Center session and an application. It is part of the information that is exposed by the sessionInformation message of the Session API.
      marketPlaceApplicationLicenseName
      String

      The PureConnect MarketPlace application's license name. Only for use in MarketPlace applications. When setting this, the marketPlaceApplicationCode property should also be set. This value can be obtained from the MarketPlace application's registration information.

      marketPlaceApplicationCode
      String

      The PureConnect MarketPlace application code. Only for use in MarketPlace applications. When setting this, the marketPlaceApplicationLicenseName property should also be set. This value can be obtained from the MarketPlace application's registration information.

      singleSignOnToken
      String

      Required

      Response

      201 - Created

      A connection has been successfully created. The URL to get the resource is specified in the Location header.

      Parameters
      Type
      Name
      Comments
      Header
      ININ-ICWS-CSRF-Token

      Required

      The ININ session token necessary for all calls that require a security or user context.

        Header
        ININ-ICWS-Session-ID

        Required

        The ININ session ID necessary for all calls that require a security or user context.

          Header
          Location

          Required

          A URL specifying where a representation of the connection can be found.

            Header
            Set-Cookie

            Required

            The session cookie. This cookie is consumed by browsers automatically. Non-browser client applications may need to manually extract this cookie and pass it as the header parameter Cookie in subsequent calls.

              connectionResponse
              Property
              Value
              Comments
              csrfToken
              String

              Required

              The CSRF Token is an ININ session token for the session that was just established. All authenticated calls must include the CSRF Token in the ININ-ICWS-CSRF-Token request header.

              sessionId
              String

              Required

              The Session ID is an ININ session identifier for the session that was just established. All authenticated calls for this session must include the Session ID in the URI.

              alternateHostList
              List [Unbounded]: String

              A list of hosts that can be used for switchovers and/or load balancing. See Connecting to a Switchover Pair or Off-Server Session Managers for more information on how to handle this list.

              Property type documentation:

              An ordered list of alternate hosts to try to connect to. See Connecting to a Switchover Pair or Off-Server Session Managers for more information on how to handle this list.

              userID
              String

              The Interaction Center user ID that was logged in.

              userDisplayName
              String

              The display name of the user that was logged in.

              icServer
              String

              The name of the IC Server for this session.

              Feature Version
              connection 2
              daysUntilPasswordExpiration
              Int
              If no value is returned, then the password is valid. If the value is returned, then the password has entered the password age warning period and the value indicates the number of day until the password will expire. If the value is less than zero, then the password has expired.
              Feature Version
              connection 3
              majorVersion
              String

              Required

              The product's two-digit release year. For the release "CIC 2015 R1" this value will be "15".
              minorVersion
              String

              Required

              The product's release number. For the release "CIC 2015 R1" this value will be "1".
              su
              String

              Required

              The patch number of the release. The value "0" indicates the release without any patches. For the release "CIC 2015 R1" this value will be "0", and for the release "CIC 2015 R1 Patch2" this value will be "2".
              build
              String

              Required

              The build number.
              productId
              String

              Required

              The product line identifier.
              codebaseId
              String

              Required

              The codebase identifier.
              productReleaseDisplayString
              String
              The display string for the release. This does not include patch information.
              Feature Version
              connection 2
              productPatchDisplayString
              String
              The display string for the release including patch information. This string is recommended for use on application "About" screens.
              Feature Version
              connection 2
              featureId
              String

              Required

              An identifier specifying a feature of the service.

              version
              Int

              Required

              A positive integer value for representing the version of a feature.

              serverUtcTime
              DateTime

              Required

              The IC server's UTC time.
              defaultWorkstationId
              String

              Represents the identifier for the default workstation assigned to the connected user. This string is as the same as the defaultWorkstation.id property provided by GET /icws/{sessionId}/configuration/users/{id} but is provided here for convenience.

              If this value is null, the user does not have an assigned default workstation.

              This property will only be included if default-workstation is specified in the include query string parameter.

              Feature Version
              connection 5

              This property can be null.

              id
              String

              Required

              The unique identifier used to reference this configuration object.
              displayName
              String
              The display name of this configuration object.

              This property can be null.

              uri
              Uri
              A URI used to access this configuration object.
              integrationEnabled
              Boolean

              Required

              Indicates whether PureCloud integration is enabled.
              webRTCIntegrationEnabled
              Boolean
              Indicates whether PureCloud WebRTC integration is enabled.
              Feature Version
              connection 11
              Associated Message
              If the server initiates a disconnect, this message will be sent to the client to inform the client of the reason.
              connectionStateChangeMessage
              Property
              Value
              Comments
              __type
              "urn:inin.com:connection:connectionStateChangeMessage"

              Required

              The JSON type representing this option.
              isDelta
              Boolean

              Required

              When true, this property indicates that some optional properties that have not changed may be omitted (all required properties will be included). In this case, the client side cache should be updated with the values for the properties provided and no change should be made for the properties not included as part of the message. This allows the API to deliver smaller messages that only represent the properties that have changed.

              When this property is false, the client side cache for this subscription should be cleared and replaced with the data provided in the message. For the initial message in response to a subscription, this property will be false to indicate the cache should be initialized with the data provided.

              none
              0
              up
              1
              down
              2
              none
              0
              up
              1
              down
              2
              reason
              String

              Required

              A description of the condition that caused the change in connection state.
              shouldReconnect
              Boolean
              A flag indicating that the condition for the connection to go down is one that the client should reconnect to the server. When newConnectionState is set to down, an unspecified value should be assumed to be false.
              Feature Version
              connection 3
              Associated Message

              This message will be sent to the stationless application, if the user is logged in to a station using another application or logs out from the station. This message is returned only if the effective-station was requested on the connection request.

              Feature Version
              connection 10
              effectiveStationChangeMessage
              Property
              Value
              Comments
              __type
              "urn:inin.com:connection:effectiveStationChangeMessage"

              Required

              The JSON type representing this option.
              isDelta
              Boolean

              Required

              When true, this property indicates that some optional properties that have not changed may be omitted (all required properties will be included). In this case, the client side cache should be updated with the values for the properties provided and no change should be made for the properties not included as part of the message. This allows the API to deliver smaller messages that only represent the properties that have changed.

              When this property is false, the client side cache for this subscription should be cleared and replaced with the data provided in the message. For the initial message in response to a subscription, this property will be false to indicate the cache should be initialized with the data provided.

              id
              String

              Required

              The unique identifier used to reference this configuration object.
              displayName
              String
              The display name of this configuration object.

              This property can be null.

              uri
              Uri
              A URI used to access this configuration object.
              400 - Bad Request
              This may indicate malformed syntax or an error validating the login request. The response body will include an error to indicate the cause of the error.

              Error Responses

              Error Identifier
              Error Type
              Error Description
              error.request.connection.unknownUser
              Type: urn:inin.com:common:error
              The logon failed because the user is unknown.
              Feature Version
              connection 2
              error.request.connection.unknownStation
              Type: urn:inin.com:common:error
              The logon failed because the station is unknown.
              Feature Version
              connection 2
              error.request.connection.unknownStatus
              Type: urn:inin.com:common:error
              The logon failed because the user's status is unknown.
              Feature Version
              connection 2
              error.request.connection.remoteAtLocal
              Type: urn:inin.com:common:error
              The logon failed because of a local/remote mismatch.
              Feature Version
              connection 2
              error.request.connection.authenticationFailure
              Type: urn:inin.com:common:error
              The authentication process failed.
              Feature Version
              connection 2
              error.request.connection.icAuthDisabled
              Type: urn:inin.com:common:error
              Interaction Center's user credentials cannot be used to log on to this server.
              Feature Version
              connection 2
              error.request.connection.integratedWindowsAuthDisabled
              Type: urn:inin.com:common:error
              This application is not allowed to automatically use the logged on user's credentials.
              Feature Version
              connection 2
              error.request.connection.alternateWindowsAuthDisabled
              Type: urn:inin.com:common:error
              This application is not allowed to use user supplied windows credentials.
              Feature Version
              connection 2
              error.request.connection.ssoAuthDisabled
              Type: urn:inin.com:common:error
              This application is not allowed to use single sign-on authentication.
              Feature Version
              connection 3
              error.request.connection.sessionId
              Type: urn:inin.com:common:error
              The logon request must not provide an existing session ID.
              Feature Version
              connection 9
              error
              Provides additional detail for an error.
              Property
              Value
              Comments
              errorId
              String
              The error identifier that describes the current error.
              message
              String

              Required

              A message that describes the current error.
              503 - Service Unavailable
              The service is unavailable at this server. This response may contain a list of alternate host names in the payload. If so, the client should attempt a new connection request to each alternate host, in the supplied order, until a connection is made or all have failed. For more information see Connecting to a Switchover Pair or Off-Server Session Managers.

              Error Responses

              Error Identifier
              Error Type
              Error Description
              error.server.notAcceptingConnections
              Type: urn:inin.com:connection:alternateHosts
              The server is not accepting connections due to maintenance or overloading.
              Feature Version
              connection 2
              error.server.unavailable
              Type: urn:inin.com:connection:alternateHosts
              The server is currently unavailable or down.
              Feature Version
              connection 2
              error.server.notAcceptingConnections.busy
              Type: urn:inin.com:connection:alternateHosts
              The server is currently experiencing a very high load, but may be able to handle logon requests in a short time.
              Feature Version
              connection 5
              alternateHosts
              Property
              Value
              Comments
              errorId
              String
              The error identifier that describes the current error.
              message
              String
              A message that describes the current error.
              alternateHostList
              List [Unbounded]: String

              Required

              Property type documentation:

              An ordered list of alternate hosts to try to connect to. See Connecting to a Switchover Pair or Off-Server Session Managers for more information on how to handle this list.

              410 - Gone
              This resource has been deprecated and removed from the API.
              error
              Provides additional detail for an error.
              Property
              Value
              Comments
              errorId
              String
              The error identifier that describes the current error.
              message
              String

              Required

              A message that describes the current error.
              500 - Internal Server Error
              An unexpected error occurred while processing the request.
              error
              Provides additional detail for an error.
              Property
              Value
              Comments
              errorId
              String
              The error identifier that describes the current error.
              message
              String

              Required

              A message that describes the current error.