Most API requests require the user to be authenticated before any meaningful response data is provided. The exceptions to this are within the Customer Portal APIs (webbapp-api-findanswers). Users may browse the knowledge base, view articles, and submit questions using the built-in Ask a Question form without logging into iService. Although there are additional features available to customers that login (access to their history, subscriptions, etc.), most of the features within the customer portal are available to anonymous users.
For those API endpoints that require authentication, the user must first login to receive a cookie that contains a session ID. The webapp-api-login form contains the various endpoints used to authenticate and obtain details about logged in users. The session ID obtained during authentication is then used for all subsequent API requests keeping the user logged in during their session. iService keeps track of actions used by the session ID, and will automatically log the user out when there have not been any actions taken (page reload, etc.) for a specified time frame. The default time frame for agent inactivity is 90 minutes, but this can be overridden with new values for each agent in the Agent Settings page.
Endpoints
The endpoints within the login form include the following:
login - This is used to log a user into iService and provide the cookie and session ID.
agentlogin - This is used for MS Active Directory integration, but is deprecated in v8.
loggedin - returns details about the logged in user, including access rights from their user type.
Register - This API registers a new user by creating the contactID and contact properties.
registeropenid - This API creates the OpenID GUID value and sets it for the contact. For new users, this creates a contact and sets the OpenID GUID for that user as their login.
logout - This API logs the user out of iService.
resetsend - This API generates a password reset notification.
resetconfirm - This API creates the new password after the user clicks on the reset link sent via resetSend.
Users log into iService with either a username and password, or a Google openID GUID associated with their contact.
JSON Value Descriptions for Logged In Object
The API Response for the LoggedIn object returns the following details. These values are used within several API endpoints.
Name
|
Type
|
Description
|
accessRights
|
Array
|
An array of strings. Each item is an access rights granted to the user.
|
accessibleSegments
|
Array
|
An array of strings. Each item is a segment ID. These IDs describe the segments to which the user has been granted access in the Agent Admin page. For non-agents, the list represents the segments that are included within the website associated with the domain.
|
alsoUseDefaultCSS
|
Boolean
|
Deprecated.
|
broadcastMessage
|
String
|
The details of the broadcast message displayed on the top of the iService agent UI. This is generally HTML.
|
chats
|
Array
|
An array of strings. Each item is an interaction ID for chats that are currently assigned to the agent.
|
contactID
|
String
|
Contact ID of the logged in user.
|
contactName
|
String
|
The name of the logged in user. If there is no name (First or Last), the email or login is returned. Otherwise, the contact ID is provided.
|
isAvailable
|
Boolean
|
Shows the availability status of a logged in user to handle chat requests.
|
isLoggedIn
|
Boolean
|
Represents the status of the logged in user. True if logged in, false if not.
|
isPasswordResetConfigured
|
Boolean
|
Indicates if the website associated with the URL has password reset configured. This is set in the Websites page.
|
logins
|
Array
|
An array of login objects.
The values are described below.
|
logins[].name
|
String
|
The login email address, username, or openID identifier.
|
logins[].type
|
String
|
"" - when the value is a username
"Email" - when the value is an email address
"Bounced" - when the email address listed was marked as undeliverable.
"Google", etc. - when the value is an openID login identifier.
|
numChats
|
Number
|
Shows the number of chats assigned to the agent.
|
registrationFormID
|
String
|
Deprecated
|
spamPolicyUrl
|
String
|
This URL is displayed on the bottom of the iService agent UI and should contain terms of service details related to sending email.
|
styleSheet
|
String
|
Deprecated
|
tenantID
|
String
|
Represents the tenant ID of a logged in user.
|
Authenticating a user (api=login)
Purpose
Use the Login API to authenticate a user. The Login API is available to all user types.
UI Reference: The API is called when the login button is clicked on an iService Login page.
URI: webapp-api-login?api=login
Access Rights Required:
Request
Request Parameters
Name
|
Type
|
Description
|
emailAddress
|
String
|
The login used for authentication. The value could be any of the supported login values (except for openID).
|
password
|
String
|
Password for the login.
|
Request Payload example
Users can login with either an email address or a username. The payload is the same in both instances.
Login with user id
{
"emailAddress": "john.doe",
"password": "password"
}
|
Login with email
{
"emailAddress": "john.doe@example.com",
"password": "password"
}
|
Response
Response Parameters
Name
|
Type
|
Description
|
errors
|
Array
|
An array of strings. Returns the error message if an error is encountered, otherwise a blank array if there is no error.
|
errorDetails
|
Array
|
An array of strings. Provides detailed information about the error encountered, otherwise returns a blank array if no error is encountered.
|
loggedIn
|
Object
|
This is the loggedIn Object. See JSON Value Descriptions for Logged In Object.
|
sid
|
String
|
The session ID for the user.
|
Response Example
The API response for the login endpoint is the same for all user types. The access rights will vary depending on whether the user is an agent or customer. Agents are defined as users with access to Customer Info or the Message Queue action.
Login api response for login
{
"errors": [],
"errorDetails": [],
"loggedIn": {
"tenantID": "3",
"isLoggedIn": true,
"contactID": "55",
"contactName": "e-shop Administrator",
"logins": [
{
"name": "john.doe",
"type": ""
},
{
"name": "john.doe@example.com",
"type": "Email"
}
],
"accessRights": [
"Tab.Top.CustomerInfo",
"Tab.Top.MessageQueue",
"Tab.Top.FindAnswers",
"Tab.Top.AskAQuestion",
"Tab.Top.MyAccount",
"Chat.Broadcast",
"Chat.Answer",
"Tab.MessageQueue.SuperviseChat",
"Tab.Admin.Monitor",
"Tab.Admin.OpenID",
"Tab.Admin.AgentEmailForm"
],
"styleSheet": "",
"alsoUseDefaultCSS": true,
"isPasswordResetConfigured": true,
"spamPolicyUrl": "https://www.1to1service.com/Company/Legal/AntiSpam.html",
"registrationFormID": "1",
"broadcastMessage": "",
"isAvailable": false,
"numChats": 0,
"chats": [],
"accessibleSegments": [
"2"
]
},
"sid": "96ff68f5-fb94-474a-b9c2-21c69e909ce3"
}
|
|
Getting details for the logged in user (api=loggedin)
Purpose
The loggedin API is used to determine the logged in status of the user and obtain details about their access rights.
UI Reference: There are no UI actions associated with this API endpoint.
URI: webapp-api-login?api=loggedin
Access Rights Required:
Request
Request Parameters
There are no request parameters for this API.
Request Payload Example
There is no request payload for this API.
Response
Response Parameters
This is the loggedIn Object. See JSON Value Descriptions for Logged In Object.
Response Example
{
"tenantID": "3",
"isLoggedIn": true,
"contactID": "55",
"contactName": "e-shop Administrator",
"logins": [
{
"name": "demo-admin",
"type": ""
},
{
"name": "demo-admin@1to1service.com",
"type": "Email"
}
],
"accessRights": [
"Tab.Top.CustomerInfo",
"Tab.Top.MessageQueue",
"Tab.Top.FindAnswers",
"Tab.Top.AskAQuestion",
"Tab.Top.MyAccount",
"Tab.Top.AdminTools",
],
"styleSheet": "",
"alsoUseDefaultCSS": true,
"isPasswordResetConfigured": true,
"spamPolicyUrl": "https://www.1to1service.com/Company/Legal/AntiSpam.html",
"registrationFormID": "1",
"broadcastMessage": "",
"isAvailable": false,
"numChats": 0,
"chats": [
],
"accessibleSegments": [
"2"
]
}
|
|
Registering a new user (api=register)
Purpose
This API is used to register a new customer user with and without openID.
UI Reference: Api is called when Signup form is used from iService Customer portal. More information to configure customer portal can be found here. Agents must be created from the Agent Settings page.
URI: webapp-api-login?api=register
Access Rights Required:
Request
Request Parameters
This example shows the standard fields for registering new customer accounts. The process creates a new contact in the database, and additional contact properties can be saved. The only required field when creating a customer contact is the login / email address and password. The built in registration pages are set to require the fields shown below.
Name
|
Type
|
Description
|
inputrequiredcontactproperty1firstname
|
String
|
This parameter represents the first name field.
|
inputrequiredcontactproperty3lastname
|
String
|
This parameter represents the last name field
|
inputemailrequired
|
String
|
This parameter represents the email address field.
|
inputpasswordrequired
|
String
|
This parameter represents the password field.
|
inputpasswordrequired1
|
String
|
This parameter represents the confirm password field.
|
Request Payload example
{
"inputrequiredcontactproperty1firstname": "John",
"inputrequiredcontactproperty3lastname": "Doe",
"inputemailrequired": "john.doe@example.com",
"inputpasswordrequired": "password",
"inputpasswordrequired1": "password"
}
|
Response
The Register API response provides details about about the registered user, including the access rights associated with their user type.
Response Parameters
Name
|
Type
|
Description
|
errors
|
Array
|
An array of strings. Returns the error message if an error is encountered, otherwise a blank array if there is no error.
|
errorDetails
|
Array
|
An array of strings. Provides detailed information about the error encountered, otherwise returns a blank array if no error is encountered.
|
loggedIn
|
Object
|
This is the loggedIn Object. See JSON Value Descriptions for Logged In Object.
|
sid
|
String
|
The session ID for the user.
|
Response example
{
"errors": [],
"errorDetails": [],
"loggedIn": {
"tenantID": "3",
"isLoggedIn": true,
"contactID": "4",
"contactName": "John Doe",
"logins": [
{
"name": "john.doe@1to1service.com",
"type": "Email"
}
],
"accessRights": [
"Tab.Top.FindAnswers",
"Tab.Top.AskAQuestion",
"Tab.Top.MyAccount",
"Tab.FindAnswers.Subscribe"
],
"styleSheet": "",
"alsoUseDefaultCSS": true,
"isPasswordResetConfigured": true,
"spamPolicyUrl": "https://www.1to1service.com/Company/Legal/AntiSpam.html",
"registrationFormID": "1",
"broadcastMessage": null,
"isAvailable": false,
"numChats": 0,
"chats": [],
"accessibleSegments": []
},
"sid": "4d3a4439-dbd6-4dea-b5a0-855a56799acb"
}
|
|
Registering new user with openid (api=registeropenid)
Although Google authentication is currently supported, this method of authentication will change in v9 and this API is not recommended for use at this time.
|
Logging a user out of iService (api-logout)
Purpose
This API is used to logout the user.
UI Reference: Api is called when logout button is clicked in My Account Tab
URI: webapp-api-login?api=logout
Access Rights Required:
Request
Request Parameters
This endpoint does not require a payload.
Response
When a user is logged out of iService, the logout endpoint returns the results for an anonymous user.
Response Parameters
Name
|
Type
|
Description
|
errors
|
Array
|
An array of strings. Returns the error message if an error is encountered, otherwise a blank array if there is no error.
|
errorDetails
|
Array
|
An array of strings. Provides detailed information about the error encountered, otherwise returns a blank array if no error is encountered.
|
loggedIn
|
Object
|
This is the loggedIn Object. See JSON Value Descriptions for Logged In Object.
|
Response example
{
"errors": [],
"errorDetails": [],
"loggedIn": {
"tenantID": "3",
"isLoggedIn": false,
"contactID": "",
"contactName": "",
"logins": [],
"accessRights": [
"Tab.Top.FindAnswers",
"Tab.Top.AskAQuestion",
"Tab.FindAnswers.Subscribe"
],
"styleSheet": "",
"alsoUseDefaultCSS": true,
"isPasswordResetConfigured": true,
"spamPolicyUrl": "https://www.1to1service.com/Company/Legal/AntiSpam.html",
"registrationFormID": "1",
"broadcastMessage": null,
"isAvailable": false,
"numChats": 0,
"chats": [],
"accessibleSegments": []
}
}
|
|
Forgot/Resetting a password (api=resetSend)
Purpose
This API is used to reset the password. Using this api will generate the reset link to the email.
UI Reference: This API is called when Forgot Password link is used on the iService Log In screen.
URI: webapp-api-login?api=resetSend
Access Rights Required:
Request
Request Parameters
Name
|
Type
|
Description
|
emailAddress
|
String
|
iService registered email address to which reset link will be sent.
|
resetUrl
|
String
|
Auto-generated reset password link with guid.
|
Request Payload example
{
"emailAddress": "demo-admin@1to1service.com",
"resetUrl": "https://eshopadmin.iservicecrm.com/f/reset-password?confirm=$value -passwordreset(guid)$"
}
|
|
Response
The reset send will return error with error message when email address is not registered with iService or in case of any other error.
Response Parameters
Name
|
Type
|
Description
|
errors
|
Array
|
An array of strings. Returns the error message if an error is encountered, otherwise a blank array if there is no error.
|
errorDetails
|
Array
|
An array of strings. Provides detailed information about the error encountered, otherwise returns a blank array if no error is encountered.
|
Response Example
{
"errors": [],
"errorDetails": []
}
|
|
Confirm Reset Password (api=resetConfirm)
Purpose
This API is used to create a new password when the user clicks on the reset link sent via the resetSend api.
UI Reference: This API is called when ________ is used on the ____ page.
URI: webapp-api-login?api=resetConfirm
Access Rights Required:
Request
Request Parameters
Name
|
Type
|
Description
|
confirmGuid
|
String
|
Parameter represents a unique id of a forgotten link associated with the URL
|
newPassword
|
String
|
Parameter represents the new password
|
Request Payload example
{
"confirmGuid": "5360cb98-e665-4180-bf02-f6f536e662fc",
"newPassword": "password"
}
|
|
|
Response
The reset send will return error with error message when email address is not registered with iService or in case of any other error.
Response Parameters
Name
|
Type
|
Description
|
errors
|
Array
|
An array of strings. Returns the error message if an error is encountered, otherwise a blank array if there is no error.
|
errorDetails
|
Array
|
An array of strings. Provides detailed information about the error encountered, otherwise returns a blank array if no error is encountered.
|
Response Example
{
"errors": [],
"errorDetails": []
}
|
|
