The iService APIs are organized around the pages you see in the user interface. For example, the endpoints used to work with customer information are contained with the webapp-api-custinfo form. Each webapp-api form may contain multiple endpoints, which are specified in the URL.
For example, the logout endpoint is contained within the webapp-api-login form, and is appended to that form as shown below.
/f/webapp-api-login?api=logout
Prepend your iService tenant URL to the path to get the full endpoint URL. For example, if your tenant URL is https://example.iservicecrm.com, then use the following endpoint URL for logout.
https://example.iservicecrm.com/f/webapp-api-login?api=logout
The response for each endpoint is described in JSON format. The values within the JSON for each endpoint are described within this API User Guide as a table that lists the properties, their data types, whether or not they're required, and a description. An example of the JSON output is provided for each endpoint.
Access to most endpoints is restricted by the user's access rights, which are determined by the user's User Type. iService includes standard user types, but each tenant can create an unlimited number of custom user types. The data returned and accepted is also limited to the iService Segments to which the user has been granted access.
Security and Authentication
Access control by User Type
Access control within iService is primarily managed by User Type. Some features, such as viewing knowledge base articles, are available to anonymous users. But the majority of the activity within an iService tenant is performed by users that have an Agent or Customer user type.
When a request is made to an iService endpoint, the response details will be limited to the access rights of the requesting user. Details that are not accessible to the requesting user will be empty within the API JSON response.
Read more about the type of users and the default user types within iService in the user guide.
Access control by Segment Access Rights
Every customer interaction within iService is associated with a Segment, which is a configuration of mailboxes and topics for interacting with your contacts. Customers are allowed to view their own interactions, but only agents have the ability to view interactions for contacts other than themselves. But, agents are only allowed to see interactions within segments to which they have been granted access in their agent configuration. For example, a user with access to a customer service segment might not be granted access to a human resources segment. When requesting interaction details from an API, the customer service user will only see interactions in the API response from their assigned segment access.
To learn more about authenticating users, see the Login API description.
|
Request Format
When using an iService API endpoint, requests are typically submitted using a JSON format. For example, the payload for a JSON request to login a user would be as follows.
{
"emailAddress": "john.doe",
"password": "password"
}
Most of the iService API endpoints support other formats such as:
URL Parameters - The values could be posted using a URL like the below.
https://example.iservicecrm.com/f/webapp-api-login?api=login&emailAddress=john.doe&password=password
Cookies - iService uses cookies to store session information, and could also contain parameters for an API request.
Form variables - iService includes a custom forms interface that allows you to create your own iService pages. These forms can be designed to trigger API requests as needed.
However, JSON is typically the method used for making iService API requests.
|
Response Format
The iService APIs provide JSON formatted responses. In case of invalid requests or errors, the APIs will return formatted JSON containing specific error information within the errors parameter.
All APIs return a status code of 200 for requests.
Response example containing error details
The iService API will return a detailed error message ready for presentation as shown below. The errorDetails value provides details on the specific API endpoint that had the error.
{
"errors":[
"The information you entered doesn\u0027t match our records. Please try again."
],
"errorDetails":[
{
"description":"Anonymous -\u003e Form Submit (webapp-api-login)"
}
],
"loggedIn":{
"tenantID":"5",
"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":[
]
},
"sid":""
}
|
|
Data Types
Most of the content within iService is derived from various interactions, like incoming customer emails, agent responses, and contact information. The iService APIs return and accepts JSON values, which can be strings in double quotes, numbers, objects, arrays, true or false, or null. Most programming languages have tools to parse this data.
Integers
Most of the numbers returned by the JSON responses, such as ID, are string values. However, the response for a contact or interaction property will return an integer or number if the property value is defined as such.
Time stamps
Time stamps use UTC time and are formatted as ISO 8601 strings. Example: 2015-04-16T09:14:57Z.
Contact and Interaction Properties
Interactions and contacts can be extended with additional information referred to as "properties." The following data types are available for use with properties.
•Text
•Integers
•Numbers
•Dates (strings in ISO 8601 format)
•Date and Time (strings in ISO 8601 format) |
