The ReviewSpotter API is the underlying interface for official ReviewSpotter features and analytics. This reference document will guide you through the API usage that helps flexible customizing in the client-side integration.

Standard API Codes

Standard API error codes

Code Description
400 Bad input parameter. Error message should indicate which one and why.
401 Unauthorized or expired token. This can happen if the user or ReviewSpotter revoked or expired an access token.
403 Forbidden.
404 File or folder not found at the specified path.
405 Request method not supported.
500 Internal server error.

Sample error response :

{
  "status": "unsuccessful",
  "results": [
    {
      "error": "",
      "message": ""
    }
  ]
}
}

Standard API success codes

Code Description
200 Success, A successful api execution is indicated with this code.
201 Created. Indicate the successful creation of a User, Application, Site or Entity.

Environment

ReviewSpotter APIs are hosted in a Sandbox environment for you to use and play around for development or testing purposes.

Environment Base URL
Sandbox Environment https://sandbox-api.reviewspotter.com

Get Started With ReviewSpotter

Under this section you will be provided with functional methods to signup and generate the Access token. It is important to be aware that a valid access token is needed to keep the system functionalities active.

Signup with a new account

Create a new ReviewSpotter account, you may create any number of Sites in an account.


URL Structure : /users

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
userData Required User details should be given in a JSON format, replace the “String” values with respective information to be modified. Body
(Parameter content type: application/json)
Model | Example Value

{ "email": "string", "firstName": "string", "password": "string", "reCaptchaToken": "string", "subscriptionKey": "string" }

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Authentication

Retrieve rs token

A successful login will provide you a ReviewSpotter token which can be later used to generate an Access Token when the APP key is given.


URL Structure : /auth/token/rs

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
signInCredentials Required The email and password given at the time of account creation should be given in a JSON format, replace the “String” values with respective information to be modified. Body
(Parameter content type: application/json)
Model | Example Value

{ "username": "string", "password": "string" }

Sample response :

{
   "rs_token": "",
   "refresh_token": "",
   "expires_in": ""
}

Retrieve an access token

You can retrieve an application specific access token here.


URL Structure : /auth/token/access

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
rs-token Required A rs-token is provided in an event of logging in to the system. Refer Retrieve rs token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. query string

Sample response :

{
  "access_token": "",
  "refresh_token": "",
  "expires_in": ""
}

Refresh the user access token

This method can be used to refresh the user access token. In such cases the user will be re-authenticated.


URL Structure : /auth/token/refresh

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
refresh-token Required A refresh token is provided in an event of logging in to the system. Refer Retrieve rs token to retrieve the token. query string

Sample response :

{
   "access_token": "",
   "refresh_token": "",
   "expires_in": ""
}

Retrieve transaction key

Retrieve a one time access token to communicate between API calls.


URL Structure : /auth/token/transaction

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
appCredentials Required The app-key can be retrieved from the Retrieve all applications method. The app secret can be derived using the Retrieve an Application method, by inserting the particular app-key. Body
(Parameter content type: application/json)
Model | Example Value

{ "appKey": "string", "appSecret": "string" }

Sample response :

 {
   "access_token": "",
   "expires_in": ""
}

Manage Application

Provides functionalities to create new applications and also modify and delete existing applications in the system.

Create an application

Creates a new application in the ReviewSpotter system.


URL Structure : /apps

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
rs-token Required A rs-token is provided in an event of logging in to the system. Refer Retrieve rs token to retrieve the token. query string
adminAppData Optional Details of the Application to be created. Body
(Parameter content type: application/json)
Model | Example Value

{ "appName": "string", "appURL": "string", "appLogo": "string", "description": "string" }

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Retrieve all applications

Gives you summarized information on all available applications


URL Structure : /apps

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
rs-token Required A rs-token is provided in an event of logging in to the system. Refer Retrieve rs token to retrieve the token. query string

Sample response :

 {
  "status": "successful",
  "results": [
    {
      "appKey": ",
      "appURL": "",
      "description": "",
      "appEdition": "",
      "appName": "",
      "appOwner": "",
      "appSettings": {
        "replyEnabled": true,
        "voteEnabled": true,
        "reportEnabled": true,
        "moderationEnabled": false,
        "publishedEmailEnabled": true,
        "autoModerationType": "",
        "badReviewDefinition": "",
        "badReviewOverallThreshold": "",
        "badReviewRatingThreshold": "",
        "badReviewSentimentThreshold": "",
        "ttl": "",
        "public": true
      }
    }
  ]
}

Retrieve an application

Gives you detailed information on a particular application, when the app-key is specified.


URL Structure : /apps/{app-key}

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string

Sample response :


{
  "status": "successful",
  "results": [
    {
      "modelVersion": "",
      "appKey": "",
      "appSecret": "",
      "appName": "",
      "description": "",
      "appURL": "",
	  "appLogo": "",
	  "headerLogo": "",
      "deleted": "",
      "status": "",
      "appEdition": "",
      "version": "",
      "buildVersion": "",
      "appOwner": "",
      "createdTime": "",
      "appSettings": {
        "replyEnabled": "",
        "voteEnabled": "",
        "reportEnabled": "",
        "moderationEnabled": "",
        "publishedEmailEnabled": "",
        "autoModerationType": "",
        "badReviewDefinition": "",
        "badReviewOverallThreshold": "",
        "badReviewRatingThreshold": "",
        "badReviewSentimentThreshold": "",
        "ttl": "",
        "public": ""
      },
      "emailServerSettings": "",
      "lastModifiedUser": "",
      "lastModifiedTime": "",
      "publicToken": "",
      "createdByUserId": ""
    }
  ]
}

Modify an application

Modifies an application when an app-key is specified.


URL Structure : /apps/{app-key}

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
app-name Optional This value will replace the current application name. query string
app-url Optional A new URL will replace the current application URL. query string
app-logo Optional URL of the new logo, the URL should be publicly hosted. query string
description Optional This may be a new description or this will replace the current description of the Application. query string
appSettings Optional Details of the application to be modified. Body
(Parameter content type: application/json)
Model | Example Value

{ "appUISettings": { "entityGalleryViewMode": "GRID" }, "attachEntitiesEnabled": true, "autoModerationType": "SWITCHED_OFF", "badReviewDefinition": "BAD_IF_OVERALL_RATING_LT_THRESHOLD", "badReviewOverallThreshold": 0, "badReviewRatingThreshold": 0, "badReviewSentimentThreshold": 0, "moderationEnabled": true, "public": true, "publishedEmailEnabled": true, "replyEnabled": true, "reportEnabled": true, "ttl": 0, "voteEnabled": true }

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Change application secret

Changes the application secret, the application secret is needed to derive the transaction key.


URL Structure : /apps/{app-key}/app-secret

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Delete an application

Deletes a specific application when the app-key is specified.


URL Structure : /apps/{app-key}

Method : DELETE

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Modify Email Settings

Modifies an application email server settings when an app-key is specified


URL Structure : /apps/{app-key}/email-setting

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
emailServerSettings Required Details of the Email server settings to be created. Body
(Parameter content type: application/json)
Model | Example Value

{ "password": "string", "senderEmail": "string", "senderName": "string", "smtpAuth": true, "smtpHost": "string", "smtpPort": "string", "smtpSSL": true, "smtpStarTLS": true, "transportProtocol": "string", "username": "string" }
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :

 {
  {
  "status": "successful",
  "results": [
    {
      "message": "App modified"
    }
  ]
}
}

Retrieve Email Settings

Gives you information on specified application email server settings


URL Structure : /apps/{app-key}/email-setting

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :

 {
  {
  "status": "successful",
  "results": [
    {
      "smtpHost": "",
      "smtpPort": "",
      "smtpAuth": true,
      "smtpStarTLS": false,
      "smtpSSL": true,
      "transportProtocol": "",
      "smtpSocketFactoryPort": "",
      "smtpSocketFactoryClass": "",
      "senderEmail": "",
      "senderName": "",
      "username": "",
      "password": ""
    }
  ]
}
}

Delete Email Settings

Deletes a specific application email server settings when the app-key is specified.


URL Structure : /apps/{app-key}/email-setting

Method : DELETE

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :

 {
  {
  "status": "successful",
  "results": [
    {
      "message": "App modified"
    }
  ]
}
}

Send Test Email

Allows you to verify the given email server settings


URL Structure : /apps/{app-key}/email-setting/test-email

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
email Required Test email query string
emailServerSettings Required Details of the Email server settings to be created. Body
(Parameter content type: application/json)
Model | Example Value

{ "password": "string", "senderEmail": "string", "senderName": "string", "smtpAuth": true, "smtpHost": "string", "smtpPort": "string", "smtpSSL": true, "smtpStarTLS": true, "transportProtocol": "string", "username": "string" }
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :

 {
  {
  "status": "successful",
  "results": [
    {
      "message": "Sent test email"
    }
  ]
}
}

Retreive level definition

Gives you information on specified user level definitions for the application


URL Structure : /apps/{app-key}/level-definitions

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :


								{
  "status": "successful",
  "results": [
    {
      "modelVersion": "DEFAULT",
      "levelDefinitions": [
        {
          "level": ,
          "levelName": "",
          "maxScorePointsToAchieve":
        }
      ]
    }
  ]
}
								

Modify level definition

Allows you to modify specified user level definitions for the application


URL Structure : /apps/{app-key}/level-definitions

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
appUserLevelDefinitions Required Details of the Email server settings to be created. Body
(Parameter content type: application/json)
Model | Example Value

{ "levelDefinitions": [ { "level": 0, "levelName": "string", "maxScorePointsToAchieve": 0 } ], "modelVersion": "DEFAULT" }

Sample response :

 {
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Manipulate User Information

This controller holds the functionality that relates to visualizing and modifying user information.

Retrieve account information

Providing the access token you can retrieve your account details such as email, first and last names, assigned user roles, and images if you have uploaded.


URL Structure : /users/me

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
rs-token Required A rs-token is provided in an event of logging in to the system. Refer Retrieve rs token to retrieve the token. query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "email": "",
      "userId": "",
      "firstName": "",
      "lastName": "",
      "imageURL": "",
      "defaultAppKey": "",
      "systemRole": "",
      "appRoles": {},
      "customRoles": {},
      "appEntityLimitationUsed": {},
      "appAllowedEntities": {},
      "provider": "",
      "emailConfirmed": ""
    }
  ]
}

Modify account details

Allows you to modify user account information. Some parameters should be provided in a JSON format.


URL Structure : /users/me

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
rs-token Required A rs-token is provided in an event of logging in to the system. Refer Retrieve rs token to retrieve the token. query string
user Required User details should be given in a JSON format, replace the “String” values with respective information to be modified. Body
(Parameter content type: application/json)
Model | Example Value

{ "firstName": "string", "imageURL": "string", "lastName": "string" }

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Change account password

Provides you with the option to change the current account password. The new password should contain minimum 8 characters.


URL Structure : /users/me/password

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
email Required This is the email provided in the signup process. query string
passwordResetData Required Insert the new password with a minimum length of 8 characters, and the old password. Body
(Parameter content type: application/json)
Model | Example Value

{ "newPassword": "string", "oldPassword": "string" }

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Delete your account

Allows you to delete the account.


URL Structure : /users/me

Method : DELETE

Parameters :

Parameters Value Description Parameter Type Data Type
rs-token Required A rs-token is provided in an event of logging in to the system. Refer Retrieve rs token to retrieve the token. query string

Sample response :

{
  "status": "successful",
  "results": []
}

Manage Application Options

Some general methods to load summarized information of the application.

Load form template components

loads all from templates mapped with an Application.


URL Structure : /apps/{app-key}/options/form-components

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string

Sample response :

{
   "status": "successful",
   "results":    [
            {
         "key": "",
         "value": ""
      }
   ]
}

Load role wise user rights

Load user role wise system privileges defined in an application.


URL Structure : /apps/{app-key}/options/roles

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string

Sample response :

 {
  "status": "successful",
  "results": [
    {
      "rights": [],
      "roleKey": "",
      "name": "",
      "roleDescription": "",
      "customRole": ""
    }
  ]
}

Manage Application Users

All functionalities related to application users are given under this section.

Retrieve user information

This method retrieves all user information attached to a specific application.


URL Structure : /apps/{app-key}/users

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Optional The type of the entity, this is defined by the user while creating the Entity Type. query string
entity-id Optional Entity id, of the entity which user need to be retrieved from. Entity ids can be retrieved by Get app mapped entities query string
group-id Optional The group-id of the Group which the users need to be retrieved from. Group IDs can be retrieved by Retrieve All Application Groups query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "email": "",
      "userId": "",
      "firstName": "",
      "lastName": "",
      "imageURL": "",
      "defaultAppKey": "",
      "systemRole": "",
      "appRoles": {},
      "customRoles": {},
      "appEntityLimitationUsed": {},
      "appAllowedEntities": {},
      "provider": "",
      "emailConfirmed": ""
    }
  ]
}

Assign user role

Assign user roles in an application.


URL Structure : /apps/{app-key}/users/{user-id}/role

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
user-id Required The id of the user. User IDs can be retrieved from the Retrieve user information method path string
role ANY of the ;
SYSTEM_ADMIN
APPLICATION_MODERATOR
APPLICATION_MANAGER
APPLICATION_ADMIN
CUSTOM_ROLE
Select the required user role form the given list. query -
custom-role-key Optional If CUSTOM_ROLE is selected as a role, then provide an appropriate role key here.
E.g. ROLE_NAME
query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "role": "",
      "customRole": ""
    }
  ]
}

Delete user from entity

Deletes a user from the application when the app-key and the username is provided.


URL Structure : /apps/{app-key}/users/{user-id}/entities

Method : DELETE

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. query string
entity-id Required Entity id, of the entity which user need to be deleted from Entity ids can be retrieved by Get app mapped entities query string
user-id Required The id of the user to be deleted. User IDs can be retrieved from the Retrieve user information method path string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Delete user from application

Deletes a user directly from the application when the app-key and the username is provided.


URL Structure : /apps/{app-key}/users/{user-id}

Method : DELETE

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
user-id Required The ID of the user to be deleted. User IDs can be retrieved from the Retrieve user information method path string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Invite users

This method holds the functionality of assigning user roles and inviting new application users.


URL Structure : /apps/{app-key}/invitees

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
email Required The email of the new system user. The user will be sent an email invitation using this. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
data Required The body parameters should be given as follows,
allowedEntities: the name of the Entity that the user is being invited.
entityType: the name of the Entity type.
Body
(Parameter content type: application/json)
Model | Example Value

{ "allowedEntities": [ "string" ], "customRoleKey": "string", "entityType": "string", "redirectSource": "CLIENT", "role": "ANY" }

valid values for the parameter 'role';
SYSTEM_ADMIN
APPLICATION_MODERATOR
APPLICATION_MANAGER
APPLICATION_ADMIN
CUSTOM_ROLE

If CUSTOM_ROLE is selected as a role, then provide an appropriate role key here.
E.g. ROLE_NAME

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Retrieve invited users

Provides you with an array of current invited users. The list will include the username, email, user image URL and information of assigned entities.


URL Structure : /apps/{app-key}/invitees

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Optional The type of the entity, this is defined by the user while creating the Entity Type. query string
entity-id Optional Entity id, of the entity which user need to be retrieved invite users. Entity ids can be retrieved by Get app mapped entities query string
group-id Optional The group-id of the Group which the entity needs to be retrieved invite users. Group IDs can be retrieved by Retrieve All Application Groups query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "email": "",
      "userId": ,
      "inviteeId": "",
      "firstName": "",
      "lastName": "",
      "imageURL": "",
      "defaultAppKey": "",
      "systemRole": "",
      "appRoles": {},
      "customRoles": {},
      "appEntityLimitationUsed": {},
      "appAllowedEntities": {},
      "provider": "",
      "emailConfirmed": "",
	  "redirectSource": ""
    }
  ]
}

Revoke user invitation

Revokes the user invitation, this function is valid until the user accept the invitation.


URL Structure : /apps/{app-key}/invitees/{invitee-id}

Method : DELETE

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
invitee-id Required The id of the invited user to be deleted.Refer Retrieve invited users to retrieve the invitee-id of the particular invited user. path string

Sample response :

 {
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Manage Application Entities

Create a review model

This will create a new review model for a particular Entity Type.


URL Structure : /apps/{app-key}/entity-types

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
entity-type Required The type that need to create as a review model. The type of the review model, this is defined by the user while creating the Entity Type. query string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string

Sample response :

 {
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Retrieve all review models

This will retrieve a summarized information array all review models in an application.


URL Structure : /apps/{app-key}/entity-types

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string

Sample response :

{
   "status":"successful",
   "results":[
      {
         "name":"",
         "imageUrl":"",
   "publicVisibility": "",
         "model":{
            "overall":{
               "key":"",
               "description":"",
               "writeEnabled":"",
               "readEnabled":"",
               "usedAsMetadata":""
            },
         }
      }
   ],
   "successful":true
}

Retrieve review model

Retrieves an array with detailed information of a review model.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/model

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
security-token Required This may be a transaction key or an access token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "key": "",
      "description": "",
      "writeEnabled": "",
      "readEnabled": "",
      "usedAsMetadata": ""
    }
]
}
	

Create an entity

Entities are created under Entity Types.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/entities

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
security-token Required This may be a transaction key or an access token. query string
entity-type Required The name of the Entity Type which you would like to include the Entity in. path string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entityData Required Details of the entity needs to be created.
The app groups can be retrieved from Retrieve All Application Groups method (given as groupId)
The form template key can be retrieved from Retrieve all form templates method (given as templateId)
Body
(Parameter content type: application/json
Model | Example Value

{ "description": "string", "entityId": "string", "entityName": "string", "formTemplateKey": "string", "groups": [ "string" ], "imageURL": "string", "props": [ { "key": "string", "type": "TEXT", "value": "string" }] }

NOTE: the entityId should not include spaces and special characters.
Refer below for accepted characters.
Letters [a-z]
Numbers [0-9]
Underscore
Hyphen

Sample values for 'props' parameter:
{
"key": "Start_Date"
"type":"DATE"
"value":"YYYY-MM-DD"
}
Values for 'key' parameter :
Start_Date
End_Date
Review_Publish_Page_URL

Valid values for 'type' parameter :
TEXT
DATE
NUMBER
URL

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Update an entity

Update details of a entity that has been already created.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/entities/update

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
security-token Required This may be a transaction key or an access token. query string
entity-type Required The name of the Entity Type which you would like to include the Entity in. path string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entityData Required Details of the entity needs to be created.
The app groups can be retrieved from Retrieve All Application Groups method (given as groupId)
The form template key can be retrieved from Retrieve all form templates method (given as templateId)
Body
(Parameter content type: application/json
Model | Example Value

{ "description": "string", "entityId": "string", "entityName": "string", "formTemplateKey": "string", "groups": [ "string" ], "imageURL": "string", "props": [ { "key": "string", "type": "TEXT", "value": "string" }] }

NOTE: the entityId should not include spaces and special characters.
Refer below for accepted characters.
Letters [a-z]
Numbers [0-9]
Underscore
Hyphen

Sample values for 'props' parameter:
{
"key": "Start_Date"
"type":"DATE"
"value":"YYYY-MM-DD"
}
Values for 'key' parameter :
Start_Date
End_Date
Review_Publish_Page_URL

Valid values for 'type' parameter :
TEXT
DATE
NUMBER
URL

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Retrieve all entities

This will provide you with summarized information of all available entities mapped with the Entity type.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/entities

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
security-token Required This may be a transaction key or an access token. query string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
from-date Optional Give the date to start filtering entities. query string
to-date Optional Set an end date to the date filter. query string
offset Optional The starting index of the entity to be retrieved. query integer
limit Optional Limit the number of entity retrievals. query integer
query Optional Search entities through key words. query string
group-key Optional The group-id of the Group which entities needs to be retrived. Group IDs can be retrieved by Retrieve All Application Groups query string
sort-commands Optional Select a predefined filter the options available are Most Rated, Most recent, Most Helpful and Least Recent. query string
suggested-entity-filter Optional This is to filter the entity as suggested or not, you can make selection from suggested, not suggested and all entities query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "modelVersion": "",
      "appKey": "",
      "globalEntityId": "",
      "globalEntityName": "",
      "entityType": "",
      "entityId": "",
      "name": "",
      "description": "",
      "currentFormTemplateKey": "",
      "currentViewTemplateKey": "",
      "props": [],
      "imageUrl": "",
      "thumbnailUrl": "",
      "deleted": "",
      "groups": [],
      "createdTime": "",
      "createdUser": "",
      "updateConversationId": "",
     "associatedEntities": [],
    "currentAttachableFormTemplateKey": "",
      "readyToProcess": "",
      "reviewSummary": {
        "readyToProcess": "",
        "ratingStats": {
           "ALL:ALL": {
           "rating": 0,
           "reviewCount": 0
           },
        }
      },
   "suggestedEntity": "",
   "suggestedEntityDetail": "",
   "publicPageVisible": ""
    }
   ],
  "pagination": {
    "totalCount": "",
    "totalPages": "",
    "currentPage": "",
    "perPage": ""
  }
}

Retrieve an entity

Retrieves detailed information on a particular Entity when entity-id is provided.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/entities/{entity-id}

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
security-token Required This may be a transaction key or an access token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
entity-id Required Entity ID of the Entity, which properties needs to be added. The Entity ID can be retrieved from Retrieve all Entities model path string

Sample response :

 {
  "status": "successful",
  "results": [
    {
      "modelVersion": "",
      "appKey": "",
      "globalEntityId": "",
      "globalEntityName": "",
      "entityType": "",
      "entityId": "",
      "name": "",
      "description": "",
      "currentFormTemplateKey": "",
      "currentViewTemplateKey": "",
      "props": [],
      "imageUrl": "",
	"thumbnailUrl": "",
      "deleted": "",
      "groups": [],
      "createdTime": "",
  	 "createdUser": "",
      "updateConversationId": "",
	   "associatedEntities": [],
      "currentAttachableFormTemplateKey": "",
      "readyToProcess": "",
  "reviewSummary": {
        "readyToProcess": "",
        "ratingStats": {
           "ALL:ALL": {
           "rating": 0,
           "reviewCount": 0
           },
        }
      },
   "suggestedEntity": "",
   "suggestedEntityDetail": "",
   "publicPageVisible": ""
    }
  ]
}

Add properties to an entity

This will add new properties to a particular entity when the entity-id is provided.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/entities/{entity-id}/properties

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
entity-id Required Entity ID of the Entity, which needs to add properties. The Entity ID can be retrieved from Retrieve all Entities model path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
props Required Body
(Parameter content type: application/json
Model | Example Value

{ "props": [ { "key": "string", "type": "TEXT", "value": "string" } ] }

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Modify an entity

Modify an existing entity.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/entities/{entity-id}/name

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
entity-id Required Entity ID of the Entity, which needs to be renamed. The Entity ID can be retrieved from Retrieve all Entities model path string
value Required This will replace the current entity name. query string
description Required Description of the entity. query string
is-public-page-visible Optional Select between True/False to enable or disable the ReviewSpotter Public Page visibility. query boolean
True/False
Default : True
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Add associated review sites

Provides an option to combine feedback forms of selected associate review sites.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/entities/{entity-id}/attach

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
entity-id Required Entity ID of the Entity, which other entities needs to be attached. The Entity ID can be retrieved from Retrieve all Entities model path string
attachedEntities Required The attached Entities holds the Site Type and the Review Site ID of all associated sites of a particular review site. Body
(Parameter content type: application/json
Model | Example Value

[ { "entityIds": [ "string" ], "entityType": "string" } ]
security-token Required This may be a transaction key or an access token. query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Retreive associated review sites

Retrieve all associated sites of a particular Review Site.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/entities/{entity-id}/attached-entities

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
entity-id Required Entity ID of the Entity, which has attached entities. The Entity ID can be retrieved from Retrieve all Entities model path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :

{
  "status": "successful",
  "results": [
    {}
  ]
}

Modify associated review sites

Modify associated sites of a particular Review Site.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/entities/{entity-id}/attach

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
entity-id Required Entity ID of the Entity, which has attached entities. The Entity ID can be retrieved from Retrieve all Entities model path string
attachedEntities Required The attached Entities holds the Site Type and the Review Site ID of all associated sites of a particular review site. Body
(Parameter content type: application/json
Model | Example Value

[ { "entityIds": [ "string" ], "entityType": "string" } ]
security-token Required This may be a transaction key or an access token. query string

Sample response :

{
  "status": "successful",
  "results": [
    {}
  ]
}

Remove associated review sites

Remove associated sites of a particular Review Site.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/entities/{entity-id}/attach

Method : DELETE

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
entity-id Required Entity ID of the Entity, which has attached entities. The Entity ID can be retrieved from Retrieve all Entities model path string
attachedEntities Required The attached Entities holds the Site Type and the Review Site ID of all associated sites of a particular review site. Body
(Parameter content type: application/json
Model | Example Value

[ { "entityIds": [ "string" ], "entityType": "string" } ]
security-token Required This may be a transaction key or an access token. query string

Sample response :

{
  "status": "successful",
  "results": [
    {}
  ]
}

Retreive suggested sites

Retrive all suggested sites of particular application


URL Structure : /apps/{app-key}/suggested-entities

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. query string
query Required This is a key word or a key phrase to filter suggested sites query string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "modelVersion": "",
      "appKey": "",
      "globalEntityId": ,
      "globalEntityName": ,
      "entityType": "",
      "entityId": "",
      "name": "",
      "description": "",
      "currentFormTemplateKey": ,
      "currentViewTemplateKey": ,
      "props": [
        {
          "key": "",
          "value": "",
          "type": ""
        }
      ],
      "imageUrl": "",
      "thumbnailUrl": "",
      "deleted": false,
      "groups": [],
      "createdTime": ,
      "createdUser": "",
      "updateConversationId": "",
      "associatedEntities": [],
      "currentAttachableFormTemplateKey": ,
      "readyToProcess": true,
      "reviewSummary": {
        "readyToProcess": true,
        "ratingStats": {
          "ALL:ALL": {
            "rating": 0,
            "reviewCount": 0
          }
        }
      },
      "suggestedEntity": true,
      "suggestedEntityDetail": {
        "currentStatus": "SUGGESTED",
        "suggestedEntityHistory": [
          {
            "performedUserId": "",
            "actionTime": ,
            "status": "SUGGESTED",
            "mergedEntity": null
          }
        ],
        "currentMergedEntity": null
      },
      "publicPageVisible": false
    }
  ],
  "pagination": {
    "totalCount": 1,
    "totalPages": 1,
    "currentPage": 1,
    "perPage": 5000
  }
}

Create suggested entity and add review

Provides an option to suggest a site and add a review


URL Structure : /apps/{app-key}/suggested-entities/suggestions

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. query string
data Required body
(Parameter content type: application/json
Model | Example Value

{ "entityData": { "description": "string", "name": "string", "props": [ { "key": "string", "type": "TEXT", "value": "string" } ] }, "reviewData": { "displayName": "string", "imageData": [ { "key": "string", "values": [ "string" ] } ], "numberData": [ { "key": "string", "value": "string" } ], "textData": [ { "key": "string", "value": "string" } ] } }
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "suggestedEntityId": "",
      "reviewId": ""
    }
  ]
}

Modify suggested entity status

Method to update specific application suggested entity status


URL Structure : /apps/{app-key}/suggested-entities/{entity-id}

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-id Required Entity ID of the Entity, which has attached entities. The Entity ID can be retrieved from Retrieve all Entities model path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. query string
created-user Required Id of the user who has suggested that entity query string
status Required The status of the suggested site,
SUGGESTED
APPROVED
MERGED
REJECTED
WAITING
query string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :

{
  "status": "successful",
  "results": [
    ""
  ]
}

Accept suggested entities

Option to accept suggested entity


URL Structure : /apps//{app-key}/suggested-entities/{entity-id}/accept

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-id Required Entity ID of the Entity, which has attached entities. The Entity ID can be retrieved from Retrieve all Entities model path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. query string
data Required body
(Parameter content type: application/json
Model | Example Value

{ "acceptedEntityData": { "createdUser": "string", "description": "string", "entityId": "string", "entityName": "string", "formTemplateKey": "string", "groups": [ "string" ], "isSuggestedEntity": true, "props": [ { "key": "string", "type": "TEXT", "value": "string" } ] }, "entityType": "string", "mergedEntities": [ { "createdUser": "string", "entityId": "string" } ] }
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :

{
  "status": "successful",
  "results": [
    "message":""
  ]
}

Modify Entity Type

Public visibility of a particular Entity Type can be modified here.


URL Structure : /apps/{app-key}/entity-types

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
entity-type Required The name of the Entity Type which you would like to include the Entity in. path string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
public-visibility Required Select between True/False to enable or disable the ReviewSpotter Public Page visibility. query boolean
True/False
Default : True

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Modify Entity Type Priority

Entity type priority can be modified according to user preference


URL Structure : /apps/{app-key}/entity-types/priorities

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
priorityItemList Required The priority item list holds the site type and priority level of the application Body
(Parameter content type: application/json
Model | Example Value

[ { "entityType": "string", "priority": 0 } ]

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Add review model parameter

This will add a new model parameter to the the Review Model.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/model/parameters

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
parameter Required Description : describe the model parameter Key : user defined key or a system generated value True is the default value of, readEnabled, usedAsMetadata and writeEnabled. Body
(Parameter content type: application/json
Model | Example Value

{ "description": "string", "key": "string", "readEnabled": true, "usedAsMetadata": true, "writeEnabled": true }

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Modify review model parameter

Modify an existing review model parameter.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/model/parameters/{parameter-key}

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
description Required Description about the parameter. query string
read-enabled Optional Select True/False to enable read. query boolean
write-enabled Optional Select True/False to enable write. query boolean
is-metadata Optional Select True/False to indicate if the parameter is metadata. query boolean
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
parameter-key Required the parameter key that need to be modified. Parameter key can be retrieve by the method Retrieve review models path string

Sample response :

 {
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Set current form template

Mapping a from template as the current from.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/entities/{entity-id}/form

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
entity-id Required Entity ID of the Entity, which needs to be set a form. The Entity ID can be retrieved from Retrieve all Entities model path string
form-template-key Required The form-template-key can be retrieved from the Retrieve all form templates method (given as templateId). query string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :

 {
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Set current sub form template

Mapping an available form as a sub form, which will be aggregated with associated review sites.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/entities/{entity-id}/attachable-form

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
entity-id Required Entity ID of the Entity, which needs to be set a form. The Entity ID can be retrieved from Retrieve all Entities model path string
form-template-key Required The form-template-key can be retrieved from the Retrieve all form templates method. query string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :

 {
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Set current view template

Set the view template of an entity.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/entities/{entity-id}/view

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
entity-id Required Entity ID of the Entity, which needs to be set a template. The Entity ID can be retrieved from Retrieve all Entities model path string
view-template-key Required The view-template-key can be retrieved from the Retrieve all view templates method (given as templateId). query string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Delete an entity

This will delete an existing Entity under an Entity Type.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/entities/{entity-id}

Method : DELETE

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
entity-id Required Entity ID of the Entity, which needs to be deleted. The Entity ID can be retrieved from Retrieve all Entities model path string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Manage Application Groups

Includes all system controls based on review site grouping in an application.

Create application groups

Create a new group that belongs to a particular site type.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/groups

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
group-name Required The name of the group query string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": "",
      "key": ""
    }
  ]
}

Retrieve all application groups

Retrieves existing groups created in a particular Site type.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/groups

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
entity-id Optional Entity ID of the Entity, groups which needs to be retrieved. The Entity ID can be retrieved from Retrieve all Entities model query string
security-token Required This may be a transaction key or an access token. query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "modelVersion": "",
      "groupId": "",
      "groupName": "",
      "entityType": "",
      "appKey": "",
      "entities": [],
      "followUpTemplates": [],
      "formTemplates": [],
      "deleted": "",
      "groupOwner": "",
      "createdTime": ""
    }
  ]
}}

Assign a review site to a group

Add review sites to existing groups in the application.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/groups/{group-id}/entities

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
group-id Required The group-id of the Group which the entity needs to be added. Group IDs can be retrieved by Retrieve All Application Groups path string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
entity-id Required Entity ID of the Entity, which needs to be assigned to a group. The Entity ID can be retrieved from Retrieve all Entities model query string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Remove review sites from group

Remove review sites from assigned groups.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/groups/{group-id}/entities

Method : DELETE

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
group-id Required The group-id of the Group which the entity needs to be removed. Group IDs can be retrieved by Retrieve All Application Groups path string
entity-id Required Entity ID of the Entity, which needs to be removed from the group. The Entity ID can be retrieved from Retrieve all Entities model query string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Delete groups from application

Delete an existing review site group from the application.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/groups/{group-id}

Method : DELETE

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
group-id Required The group-id of the Group which the entity needs to be added. Group IDs can be retrieved by Retrieve All Application Groups path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": "",
      "key": ""
    }
  ]
}

Manage User Groups

Includes controls of Customizing and managing user groups in the system.

Create user groups

Create a new user group that belongs to a particular entity.


URL Structure : /apps/{app-key}/users/groups

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
userGroup Required Body
(Parameter content type: application/json)
Model | Example Value

{ "assignedAppUsers": [ "string" ], "assignedInvitedUsers": [ "string" ], "entityType": "string", "groupName": "string" }

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": "",
      "key": ""
    }
  ]
}

Retrieve all user groups

Can be used to retrieve existing user groups created in an application.


URL Structure : /apps/{app-key}/users/groups

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "modelVersion": "",
      "groupId": "",
      "groupName": "",
      "appKey": "",
      "entityType": "",
      "assignedAppUsers": [],
      "assignedInvitedUsers": [],
      "mappedAppGroups": [],
      "mappedEntities": {},
      "deleted": false,
      "groupOwner": "",
      "createdTime": ""
    }
  ]
}

Edit user group

Edit existing user groups available an application.


URL Structure : /apps/{app-key}/users/groups/{group-id}

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
group-id Required The group-id of the Group which the entity needs to be added. Group IDs can be retrieved by Retrieve All Application Groups path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
userGroup Required Body
(Parameter content type: application/json)
Model | Example Value

{ "assignedAppUsers": [ "string" ], "assignedInvitedUsers": [ "string" ], "entityType": "string", "groupName": "string" }

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Add user to the group

Allows you to add users to an existing user group.


URL Structure : /app/{app-key}/user-group/{group-id}/user

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
group-id Required The group-id of the Group which the entity needs to be removed. Group IDs can be retrieved by Retrieve All Application Groups path string
username Required The email of the user to be added. query string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Remove user from group

Includes the feature of removing users form existing user groups.


URL Structure : /app/{app-key}/user-group/{group-id}

Method : DELETE

Parameters :

Parameters Value Description Parameter Type Data Type
group-id Required The group-id of the Group which the entity needs to be added. Group IDs can be retrieved by Retrieve All Application Groups path string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
username Required The email of the user to be added. query string
isInvited Required Select True/False to indicate if the user is invited. query boolean
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Delete user group

Delete an existing user group from the application.


URL Structure : /apps/{app-key}/users/groups/{group-id}

Method : DELETE

Parameters :

Parameters Value Description Parameter Type Data Type
group-id Required The group-id of the Group which the entity needs to be added. Group IDs can be retrieved by Retrieve All Application Groups path string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Manage Application Forms

Create a form template

Allows you to create from templates per Entity Type.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/form-templates

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
templateData Required Attributes : from attributes Component : review elements Body
(Parameter content type: application/json)
Model | Example Value

{ "data": [ { "attributes": [ { "key": "string", "value": "string" } ], "component": "DEFAULT", "description": "string", "inputId": "string", "label": "string", "options": [ { "key": "string", "value": "string" } ], "parameterKey": "string", "required": true, "usedAsMeta": true } ], "defaultAttachableFormTemplate": true, "defaultFormTemplate": true, "formDescription": "string", "formHeaderImage": "string", "templateName": "string", "thankYouNote": "string" }

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": "",
      "key": ""
    }
  ]
}

Retrieve all form templates

Retrieves a list of available from templates. This is a summarized information array of templates in an application.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/form-templates

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
security-token Required This may be a transaction key or an access token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
language Required Select a preferred language form the dropdown list. The default language is en-English.
Available languages : en-English, es-Spanish , pr-portuguese
query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "modelVersion": "",
      "templateId": "",
      "templateName": "",
      "createdUser": "",
      "createdTime": "",
      "formDescription": "",
      "thankYouNote": "",
      "formHeaderImage": "",
      "lastModifiedUser": "",
      "lastModifiedTime": "",
      "appKey": "",
      "entityType": "",
      "apiCall": "",
      "entityMappedApiCall": "",
      "embeddableScript": "",
      "deleted": "",
      "defaultFormTemplate": "",
	  "defaultAttachableFormTemplate": "",
      "mappedViewTemplateKey": "",
      "components": {
        "0": {
          "cmpId": "",
          "component": "",
          "parameterKey": "",
          "required": "",
          "label": "",
          "description": "",
          "attributes": [
            {
              "key": "",
              "value": ""
            }
          ],
          "options": [
            {
              "key": "",
              "value": ""
            }
          ],
		 "publicViewVisible": ""
        }
      },
      "embeddedEntities": [],
      "groups": []
    }
  ]
}

Modify a form template

Modifies a particular form template when a form-template-key is provided.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/form-templates/{form-template-id}

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
form-template-id Required The form-template-key can be retrieved from the Retrieve all form templates method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
templateData Required Body
(Parameter content type: application/json)
Model | Example Value

{ "data": [ { "attributes": [ { "key": "string", "value": "string" } ], "component": "DEFAULT", "description": "string", "inputId": "string", "label": "string", "options": [ { "key": "string", "value": "string" } ], "parameterKey": "string", "publicViewVisible": true, "required": true, "usedAsMeta": true } ], "defaultAttachableFormTemplate": true, "defaultFormTemplate": true, "formDescription": "string", "formHeaderImage": "string", "templateName": "string", "thankYouNote": "string" }

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Retrieve a form template

Retrieves detailed information of a particular form template.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/form-templates/{form-template-id}

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
security-token Required This may be a transaction key or an access token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
form-template-id Required The form-template-id can be retrieved from the Retrieve all form templates method. path string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "modelVersion": "",
      "templateId": "",
      "templateName": "",
      "createdUser": "",
      "createdTime": "",
      "formDescription": "",
      "thankYouNote": "",
      "formHeaderImage": "",
      "lastModifiedUser": "",
      "lastModifiedTime": "",
      "appKey": "",
      "entityType": "",
      "apiCall": "",
      "entityMappedApiCall": "",
      "embeddableScript": "",
      "deleted": "",
      "defaultFormTemplate": "",
      "mappedViewTemplateKey": "",
      "components": {
        "0": {
          "cmpId": "",
          "component": "",
          "parameterKey": "",
          "required": "",
          "label": "",
          "description": "",
          "attributes": [
            {
              "key": "",
              "value": ""
            }
          ],
          "options": [
            {
              "key": "",
              "value": ""
            }
          ],
		 "publicViewVisible": true
        }
      },
      "embeddedEntities": [],
      "groups": []
    }
  ]
}

Delete a form template

Deletes a particular form template when the from-template-key id provided.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/form-templates/{form-template-id}

Method : DELETE

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
form-template-id Required The form-template-id can be retrieved from the Retrieve all form templates method. path string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Manage Template Views

Create view template

Create a new template to visualize review models.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/view-templates

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
access-token Required TAn access-token is provided in an event of logging in to the system. Refer Retrieve rs token to retrieve the token. query string
templateData Required Body
(Parameter content type: application/json
Model | Example Value

{ "data": [ { "component": "STAR_VIEW", "label": "string", "parameterKey": "string" } ], "defaultViewTemplate": true, "deleteEnabled": true, "editEnabled": true, "editTemplateKey": "string", "replyEnabled": true, "socialShareEnabled": true, "templateName": "string", "voteEnabled": true }

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": "",
      "key": ""
    }
  ]
}

Retrieve all view templates

Provides you with a summarized information array of all available View


URL Structure : /apps/{app-key}/entity-types/{entity-type}/view-templates

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "modelVersion": "",
      "templateId": "",
      "templateName": "",
      "appKey": "",
      "entityType": "",
      "createdUser": "",
      "createdTime": "",
      "lastModifiedUser": "",
      "lastModifiedTime": "",
      "components": {
        "0": {
          "parameterKey": "",
          "component": "",
          "label": "",
		  "publicViewVisible": ""
        }
      },
      "editTemplateId": "",
      "replyEnabled": "",
      "editEnabled": "",
      "deleteEnabled": "",
      "voteEnabled": "",
      "socialShareEnabled": "",
      "apiCall": "",
      "embeddableScript": "",
      "deleted": "",
      "defaultViewTemplate": ""
    }
  ]
}
Response Code

Modify a view template

Modifies a specific template when the view-template-key is provided.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/view-templates/{view-template-id}

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
view-template-id Required The view template id of the view template that needs to be modified view template id can be retrieved from the Retrieve all view templates method. path string
template Required Body
(Parameter content type: application/json
Model | Example Value

{ "data": [ { "component": "STAR_VIEW", "label": "string", "parameterKey": "string", "publicViewVisible": "" } ], "defaultViewTemplate": true, "deleteEnabled": true, "editEnabled": true, "editTemplateKey": "string", "replyEnabled": true, "socialShareEnabled": true, "templateName": "string", "voteEnabled": true }

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Load view template

Load a particular view template when the view-template-key is provided.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/view-templates/{view-template-id}

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
view-template-id Required Put view template id of the view template needs to be retrieve information view template id can be retrieved from the Load all view templates path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string

Sample response :

 {
  "status": "successful",
  "results": [
    {
      "modelVersion": "",
      "templateId": "",
      "templateName": "",
      "appKey": "",
      "entityType": "",
      "createdUser": "",
      "createdTime": "",
      "lastModifiedUser": "",
      "lastModifiedTime": "",
      "components": {
        "0": {
          "parameterKey": "",
          "component": "",
          "label": "",
		  "publicViewVisible": ""
        }
      },
      "editTemplateId": "",
      "replyEnabled": "",
      "editEnabled": "",
      "deleteEnabled": "",
      "voteEnabled": "",
      "socialShareEnabled": "",
      "apiCall": "",
      "embeddableScript": "",
      "deleted": "",
      "defaultViewTemplate": ""
    }
  ]
}

Delete view template

Deletes an an existing view template when the view-template-key is specified.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/view-templates/{view-template-id}

Method : DELETE

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve rs token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
view-template-id Required The view template id of the view template that needs to be modified view template id can be retrieved from the Retrieve all view templates method. path string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Manage Review Invites

This section holds all features to manipulate the review invitations.

Create review invitation templates

Create review invitation templates for a given entity (Review Site), key value pairs, hidden values and metadata fields can be specified here


URL Structure : /apps/{app-key}/entity-types/{entity-type}/followup-templates

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
followUpTemplateBody Required Body
(Parameter content type: application/json
Model | Example Value

{ "emailSubject": "string", "groups": [ "string" ], "html": "string", "imageUrl": "string", "name": "string", "qrPossition": "TOP_LEFT", "qrSize": "SMALL", "requiredMetaFields": [ { "additionalData": {}, "autoFill": true, "key": "string", "meta": true, "required": true, "type": "TEXT" } ], "useCustomizeSubject": true, "useEntityImage": true }

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Retrieve follow-up templates

Provides you with a summarized information array of available review invite templates


URL Structure : /apps/{app-key}/entity-types/{entity-type}/followup-templates

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "modelVersion": "",
      "templateId": "",
      "appKey": "",
      "name": "",
      "entityType": "",
      "qrPossition": "",
      "qrSize": "",
      "imageUrl": "",
      "html": "",
      "requiredFields": [
        {
          "key": "",
          "type": "",
          "additionalData": {},
          "required": "",
          "autoFill": "",
          "meta": ""
        }
	],
      "requiredMetaFields": [],
      "deleted": "",
      "groups": [],
      "history": "",
      "useEntityImage": "",
      "useCustomizeSubject": "",
      "emailSubject": ""
    }
  ]
}

Schedule review invite

Provides the feature to schedule email invitations to be sent on a given date.


URL Structure : /apps/{app-key}/review-invitations/schedules

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
security-token Required This may be a transaction key or an access token. query string
data Required Body
(Parameter content type: application/json
Model | Example Value

{ "data": [ { "allowedReviewCount": 0, "email": "string", "entityId": "string", "expirationPeriod": 0, "noOfCopies": 0, "numberMetaData": [ { "key": "string", "value": 0 } ], "scheduleTime": "string", "sourceType": "DIRECT", "templateData": [ { "key": "string", "value": "string" } ], "textMetaData": [ { "key": "string", "value": "string" } ] } ], "entityType": "string", "followUpTemplateKey": "string", "requestKey": "string", "resend": true }

Sample response :

{
  "status": "successful",
  "results": [
    {
      "requestKey": ",
      "responseItems": [
        {
          "invitationKey": ",
          "email": "",
          "responded": "",
          "active": "",
          "item": ""
        }
      ],
      "time": "",
      "scheduledTime": "",
      "expirationPeriod":"",
      "entityId": "",
      "entityType": "",
      "entityName": "",
      "source": "",
      "createdBy": "",
      "templateId": ""
    }
  ]
}				

Retrieve review invite links

Schedule review invites and retrieve the review URL. This can be used to share invites via SMS.


URL Structure : /apps/{app-key}/review-invitations/schedules/get-url

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. query string
entity-id Required Entity id, of the entity which invitations needs to be retrived. Entity ids can be retrieved by Get app mapped entities query string
data Required Body
(Parameter content type: application/json
Model | Example Value

{ "allowMultipleReviews": true, "email": "string", "expirationPeriod": 0, "numberMetaData": [ { "key": "string", "value": 0 } ], "scheduleTime": "string", "sourceType": "DIRECT", "textMetaData": [ { "key": "string", "value": "string" } ] }
security-token Required This may be a transaction key or an access token. query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message":
    }
  ]
}

Retrieve all review invitations

Retrieve all review invites which has been scheduled in Schedule Review Invites.


URL Structure : /apps/{app-key}/review-invitations

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. query string
entity-id Optional Entity id, of the entity which invitations needs to be retrived. Entity ids can be retrieved by Get app mapped entities query string
group-key Optional The group-id of the Group which invitations needs to be retrived. Group IDs can be retrieved by Retrieve All Application Groups query string
from-date Optional Give from date to filter invitations. query string
to-date Optional Set the to-date to define the time period. query string
meta-filters Optional This is a user defined metadata value. query string
responded True/False
Default : True
Select True or False to filter invitations. The default value will filter responded invitations. query Boolean
Type ANY of the ;
EMAIL
URL
Invitation source type query string
security-token Required This may be a transaction key or an access token. query string

Sample response :

{
   "status":"successful",
   "results":[
      {
         "modelVersion":"",
         "reviewId":"",
         "version":"",
         "status":"",
         "deleted":"",
         "readyToProcess":"",
         "appKey":"",
         "appName":"",
         "createdUser":"",
         "displayName":"",
         "createdTime":,
         "entityType":"",
         "entityId":"",
         "entityName":"",
         "comment":"",
         "title":"",
         "parentReview":"",
         "childReviews":[],
         "numberData":[
            {
               "key":"",
               "value":""
            }
         ],
         "textData":[],
         "imageData":[],
         "numberMeta":[],
         "textMeta":[],
         "replies":[],
         "sentiments":[],
         "scoredComment":[],
         "rawNumberData":{
            "overall":""
			},
         "rawTextMeta":{},
         "rawNumberMeta":{},
         "rawScoredComment":{},
         "pvCount":0,
         "nvCount":0
      }
   ]
}

Create invitation QR

The QR codes are generated using this method. Generated code is embedded in printed invitation formats


URL Structure : /apps/{app-key}/review-invitations/{invitation-key}/qr

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
invitation-key Required The invitation key is a system generated parameter, refer the Schedule Review Invite method to find entity wise invitation keys path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. path string
width Optional Provide the QR code width in pixels.
Default : 350 px
query string

Sample response :

Update an invitation

Update details of a review invitation that has been already sent


URL Structure : /apps/{app-key}/review-invitations/{invitation-key}

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
invitation-key Required The invitation key is a system generated parameter, refer the Generate Invitation Key method to find entity wise invitation keys path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
followUpDet Required Body
(Parameter content type: application/json
Model | Example Value

{ "active": true, "activeInvitation": true, "appKey": "string", "createdBy": "string", "createdTime": 0, "deleted": true, "entityId": "string", "entityImageUrl": "string", "entityName": "string", "entityType": "string", "expirationPeriod": 0, "expired": true, "followUpTemplateId": "string", "followedEmail": "string", "invitationKey": "string", "modelVersion": "DEFAULT", "numberMetaData": [ { "key": "string", "value": 0 } ], "requestKey": "string", "responded": true, "scheduled": true, "scheduledTime": 0, "source": "DIRECT", "templateData": [ { "key": "string", "value": "string" } ], "textMetaData": [ { "key": "string", "value": "string" } ] }

Sample response :

{
  "status": "successful",
  "results": [
    {
      "invitationKey": ""
    }
  ]
}

Un-schedule review invite

Un-schedule a review invite which has been scheduled in Schedule Review Invite.


URL Structure : /apps/{app-key}/review-invitations/schedules/{schedule-id}

Method : DELETE

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. query string
schedule-id Required Give the schedule ID, this is a system generated value during scheduling invites. The schedule ID can be retrieved from Retrieve all review invitations model path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "Schedule Stopped"
    }
  ]
}

Remove follow-up template

Removes the follow-up template when the followup template id is specified.


URL Structure : /apps/{app-key}/entity-types/{entity-type}/followup-templates/{followup-template-id}

Method : DELETE

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. path string
followup-template-id Required Template id is auto generated while the template creation. it can be retrieved using the Retrieve Follow-up Templates method. path string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": "Done"
    }
  ]
}

Manage Reviews

Provides all functionalities to manipulate aggregated reviews.

Retrieve all reviews

A summarized information array of all available reviews in a particular Entity


URL Structure : /apps/{app-key}/reviews

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. query string
entity-id Optional Entity ID of the Entity, which needs to retrieve reviews. The Entity ID can be retrieved from Retrieve all Entities model query string
group-key Optional The group-id of the Group which needs to be retrieved all reviews. Group IDs can be retrieved by Retrieve All Application Groups query string
author Optional Email of the review author query string
display-name Optional Display name of the review author query string
from-date Optional Date to start review retrieval in YYYY-MM-DD format query string
to-date Optional Date to end review retrieval query string
query Optional Reviews can be retrieved using specific queries. Refer the query format below
"parameterKey":"condition":"parameterValue"

"parameterKey" could be ANY of the parameters recieved in the response of the Retrieve review method.
"condition" could be ANY of,
"eq" - equal
"lt" - less than
"gt"- greater than

**Seperate multiple queries by a semicolon(;).
query string
meta-filters Optional Provide parameters specified as metadata. system defined metadata can be retrieved using the Retrieve review model.
E.g. key:MetaValue;
query string
rating-filters Optional Pass the star rating value to be filtered. Multiple values should be separated using a comma. query string
sort-commands Optional Select a predefined filter the options available are Most Rated, Most recent, Most Helpful and Least Recent. query string
status Optional The states of the review,
WAITING
APPROVED
BLOCKED
query string
offset Optional The starting index of the review to be retrieved query integer
limit Optional Limit the number of review retrievals. query integer
mode Optional Limit client/public user added reviews query string
suggested-entity-filter Optional This is to filter the entity as suggested or not, you can make selection from suggested, not suggested and all entities query string
security-token Required This may be a transaction key or an access token. query string

Sample response :

 {"status": "successful",
  "results": [
  {
    "modelVersion": "",
    "reviewId": "",
    "version": "",
    "status": "",
    "deleted": "",
    "readyToProcess": "",
    "readyToView": "",
    "appKey": "",
    "appName": "",
    "createdUser": "",
    "displayName": "",
    "createdTime": "",
    "entityType": "",
    "entityId": "",
    "entityName": "",
    "comment": "",
    "title": "",
    "nps": 0,
    "parentReview": null,
    "childReviews": [],
    "numberData": [
        {
        "key": "",
        "value": ""
        }
    ],
    "textData": [],
    "imageData": [],
    "imageDets": [],
    "numberMeta": [],
    "textMeta": [],
    "suggestedReview": "",
    "mappedFormTemplateKey": "",
    "mappedViewTemplateKey": "",
    "replies": [],
    "sentiments": [],
    "scoredComment": [],
    "rawNumberData": {},
    "rawTextMeta": {},
    "rawNumberMeta": {},
    "rawScoredComment": {},
    "pvCount": 0,
    "nvCount": 0,
    "reviewerMeta": {
        "reviewerType": "",
        "appRole": "",
        "userLevel": 0,
        "additionalUserInfo": []
      },
    "reviewOrigin": ""
   }
    ],
    "pagination": {
    "totalCount": "",
    "totalPages": "",
    "currentPage": "",
    "perPage": ""
  }
}

Approve reviews

Changes the status to approve of a particular review.


URL Structure : /apps/{app-key}/reviews/approvals

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
approved Required The status of the review. query boolean
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
reviewIDContainer Required IDs of reviews to be approved. Body
(Parameter content type: application/json
Model | Example Value

{ "reviewIds": [ "string" ] }

Sample response :

{
   "status": "successful",
   "results": [[""]]
}

Retrieve review

Retrieve a particular review when the review ID is provided.


URL Structure : /apps/{app-key}/reviews/{review-id}

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
review-id Required The review-id of the review to be retrieved. The review-id can be retrieved from Retrieve all Reviews model path string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
security-token Required This may be a transaction key or an access token. query string

Sample response :

{
   "status": "successful",
   "results": [   {
    "modelVersion": "",
    "reviewId": "",
    "version": "",
    "status": "",
    "deleted": "",
    "readyToProcess": "",
    "readyToView": "",
    "appKey": "",
    "appName": "",
    "createdUser": "",
    "displayName": "",
    "createdTime": "",
    "entityType": "",
    "entityId": "",
    "entityName": "",
    "comment": "",
    "title": "",
    "nps": 0,
    "parentReview": null,
    "childReviews": [],
    "numberData": [
        {
        "key": "",
        "value": ""
        }
    ],
    "textData": [],
    "imageData": [],
    "imageDets": [],
    "numberMeta": [],
    "textMeta": [],
    "suggestedReview": "",
    "mappedFormTemplateKey": "",
    "mappedViewTemplateKey": "",
    "replies": [],
    "sentiments": [],
    "scoredComment": [],
    "rawNumberData": {},
    "rawTextMeta": {},
    "rawNumberMeta": {},
    "rawScoredComment": {},
    "pvCount": 0,
    "nvCount": 0,
    "reviewerMeta": {
        "reviewerType": "",
        "appRole": "",
        "userLevel": 0,
        "additionalUserInfo": []
      },
    "reviewOrigin": ""
   }
   ]
}

Moderate review

Moderate a particular review when the review-id is specified.


URL Structure : /apps/{app-key}/reviews/{review-id}

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
review-id Required The review-id of the review to be modarated. The review-id can be retrieved from Retrieve all Reviews model path string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve rs token to retrieve the token. query string
data Required displayName : name of the review author numberData : numeric data textData : all string values in a review Body
(Parameter content type: application/json
Model | Example Value

{ "displayName": "string", "imageData": [ { "key": "string", "values": [ "string" ] } ], "numberData": [ { "key": "string", "value": "string" } ], "textData": [ { "key": "string", "value": "string" } ] }

Sample response :

{
   "status": "successful",
   "results": [{"message": ""}]
}

Reply a particular review

Replies a particular review when the review-id is provided.


URL Structure : /apps/{app-key}/reviews/{review-id}/replies

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
review-id Required The review-id of the review to be replied. The review-id can be retrieved from Retrieve all Reviews model path string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
rs-token Required A rs-token is provided in an event of logging in to the system. Refer Retrieve rs token to retrieve the token. query string
data Required displayName : name of the review author Body
(Parameter content type: application/json
Model | Example Value

{ "content": "string", "displayName": "string" }

Sample response :

{
   "status": "successful",
   "results": [{"message": ""}]
}

Vote a review

Vote a particular review specifying the review-id


URL Structure : /apps/{app-key}/reviews/{review-id}/votes

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
review-id Required The review-id of the review to be voted. The review-id can be retrieved from Retrieve all Reviews model path string
display-name Optional Display name of the review author. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
vote Required Select the vote from the given list;
Positive
Negative
query string
rs-token Required A rs-token is provided in an event of logging in to the system. Refer Retrieve rs token to retrieve the token. query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "reviewId": "",
      "vote": "",
      "createdUser": "",
      "displayName": "",
      "createdTime": "",
      "ip": "",
      "userAgent": ""
    }
  ]
}

Retrieve review replies

Retrieves all the replies given to a particular review when the review-id is specified.


URL Structure : /apps/{app-key}/reviews/{review-id}/replies

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
review-id Required The review-id of the review to be retrieved. The review-id can be retrieved from Retrieve all Reviews model path string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
security-token Required This may be a transaction key or an access token. query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "modelVersion": "",
      "appKey": "",
      "replyId": "",
      "reviewId": "",
      "content": "",
      "deleted": "",
      "createdUser": "",
      "displayName": "",
      "createdTime": "",
      "ip": "",
      "userAgent": ""
    }
  ]
}

Delete reply

Delete a reply given for a particular review.


URL Structure : /apps/{app-key}/reviews/{review-id}/replies/{reply-id}

Method : DELETE

Parameters :

Parameters Value Description Parameter Type Data Type
reply-id Required The reply-id of the reply to be retrieved. path string
review-id Required The review-id of the review to be retrieved. The review-id can be retrieved from Retrieve all Reviews model path string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "message": ""
    }
  ]
}

Delete a review

Delete a particular review when a review-id is provided.


URL Structure : /apps/{app-key}/reviews/{review-id}

Method : DELETE

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
review-id Required The review-id of the review to be deleted. The review-id can be retrieved from Retrieve all Reviews model path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve rs token to retrieve the token. query string

Sample response :

{
   "status": "successful",
   "results": [{"message": ""}]
   }

Delete all reviews

Facilitates with the functionality to delete a selected bulk of reviews or delete all in a particular Entity.


URL Structure : /apps/{app-key}/reviews

Method : DELETE

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Load All Apps method. path string
entity-type Required The app-key can be retrieved from the Retrieve all applications method. query string
entity-id Required Entity ID of the Entity, which needs to delete all reviews. The Entity ID can be retrieved from Retrieve all Entities model query string
author Optional Email of the review author query string
from-date Optional Date to start review retrieval in YYYY-MM-DD format query string
to-date Optional Date to end review retrieval query string
status Optional The states of the review,
WAITING
APPROVED
BLOCKED
query string
meta-filters Optional Provide parameters specified as metadata. system defined metadata can be retrieved using the Retrieve review model.
E.g. key:MetaValue;
query string
sort-commands Optional Select a predefined filter the options available are Most Rated, Most recent, Most Helpful and Least Recent. query string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve rs token to retrieve the token. query string

Review Analytics

This controller contains all features and functionalities that relates with ReviewSpotter analytics.

Retrieve email invitation statistics

Loads information of generated email invitations


URL Structure : /apps/{app-key}/analytics/invitation-stats

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
entity-type Optional The type of the entity, this is defined by the user while creating the Entity Type. query string
entity-id Optional Entity id, of the entity which user need to be retrieved invitations. Entity ids can be retrieved by Get app mapped entities query string
group-key Optional The group-id of the Group which invites needs to be retrieved. Group IDs can be retrieved by Retrieve All Application Groups query string
from-date Optional Date to start invitation retrieval in YYYY-MM-DD format. query string
to-date Optional Date to end invitation retrieval in YYYY-MM-DD format. query string
meta-filter Optional Metadata values defined in the email template query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "QR": {
        "notResponded": "",
        "expired": "",
        "notActive": "",
        "responded": ""
      },
      "RCD": {
        "notResponded": "",
        "expired": "",
        "notActive": "",
        "responded": ""
      },
      "EMAIL": {
        "notResponded": "",
        "expired": "",
        "notActive": "",
        "responded": ""
      },
      "DIRECT": {
        "notResponded": "",
        "expired": "",
        "notActive": "",
        "responded": ""
      },
      "URL": {
        "notResponded": "",
        "expired": "",
        "notActive": "",
        "responded": ""
      }
    }
  ]
}

Retrieve entity rankings

Loads review site rankings (basic or sentiment) of a given entity type


URL Structure : /apps/{app-key}/analytics/entities/rankings

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
security-token Required This may be a transaction key or an access token. query string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. query string
group-key Optional The group-id of the Group which rankings need to be retrieved. Group IDs can be retrieved by Retrieve All Application Groups query string
from-date Optional Date to start statistics retrieval in YYYY-MM-DD format query string
to-date Optional Date to end statistics retrieval in YYYY-MM-DD format query string
analytic-type ANY of the;
BASIC
SENTIMENT
This is the type of sentiment, you can make a selection from any of Basic and Sentiment. query string
meta-filters Optional This is a predefined metadata value query string
rank-on Optional A predefined review element with the ranking data type. query string
sort-commands Optional Select a predefined sort command the options available are ASC and DESC. query string
limit Optional Limit the number of entity retrievals. query integer

Sample response :

{
  "status": "successful",
  "results": [
    {
      "entityId": "",
      "entityName": "",
      "score": "",
      "reviewCount": "",
      "rank": ""
    }
  ]
}

Retrieve review ratings

Gives the rating score of system derived review factors


URL Structure : /apps/{app-key}/analytics/reviews/ratings

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
security-token Required This may be a transaction key or an access token. query string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. query string
entity-id Optional Entity id, of the entity which user need to be retrieved sentiment ratings. Entity ids can be retrieved by Get app mapped entities query string
group-key Optional The group-id of the Group which ratings needs to be retrieved. Group IDs can be retrieved by Retrieve All Application Groups query string
analytic-type ANY of the;
BASIC
SENTIMENT
This is the type of sentiment, you can make a selection from any of Basic and Sentiment. query string
from-date Optional Date to start statistics retrieval in YYYY-MM-DD format query string
to-date Optional Date to end statistics retrieval in YYYY-MM-DD format query string
meta-filters Optional This is a predefined metadata value. query string

Sample response :

{
  "status": "successful",
  "results": [
    {
      "key": "",
      "name": "",
      "rating": "",
      "reviewCount": "",
      "stats": {}
    }
  ]
}

Retrieve analyzed review data

This method will retrieve review analysis information per entity, once the entity-id is specified.


URL Structure : /apps/{app-key}/analytics/reviews

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Required The type of the entity, this is defined by the user while creating the Entity Type. query string
entity-id Optional Entity id, of the entity which user need to be retrieved reviews. Entity ids can be retrieved by Get app mapped entities query string
security-token Required This may be a transaction key or an access token. query string
group-key Optional The group-id of the Group which reviews needs to be retrieved. Group IDs can be retrieved by Retrieve All Application Groups query string
from-date Optional Date to start reviews retrieval in YYYY-MM-DD format query string
to-date Optional Date to end reviews retrieval in YYYY-MM-DD format query string
meta-filters Optional A user defined metadata value query string
query Required This is a key word or a key phrase to filter reviews. query string
status Optional The states of the review,
WAITING
APPROVED
BLOCKED
query string
offset Optional The starting index of the review to be retrieved. query integer
limit Optional Limit the number of review retrievals. query integer
sort-commands Optional Select a predefined sort order, the options available are MOST_RECENT, MOST_RATED and MOST_HELPFULL.
Example: MOST_RECENT:DESC
query string
rating-filters Optional Pass the star rating value to be filtered. Multiple values should be separated using a comma. query string
polarity ANY of the ;
ALL
NEGATIVE
POSITIVE
Select negative or positive to filter reviews. query string

Sample response :

{
    "status": "successful",
    "results": [
        {
            "modelVersion": "",
            "reviewId": "",
            "status": "",
            "deleted": "",
            "readyToProcess": "",
            "appKey": "",
            "appName": "",
            "createdUser": "",
            "displayName": "",
            "createdTime": "",
            "entityType": "",
            "entityId": "",
            "entityName": "",
            "comment": "",
            "title": "",
			"parentReview": null,
			"childReviews": [],
            "numberData": [],
            "textData": [],
			"imageData": [],
            "numberMeta": [],
            "textMeta": [],
            "replies": [],
            "sentiments": [],
            "scoredComment": [],
            "rawNumberData": {
                "overall": ""
            },
            "rawTextMeta": {
                "ip": "",
                "source": "",
                "user-agent": ""
            },
            "rawNumberMeta": {},
            "rawScoredComment": {},
            "pvCount": "",
            "nvCount": "",
			 }
  ],
  "pagination": {
    "totalCount": 1,
    "totalPages": 1,
    "currentPage": 1,
    "perPage": 20
  }
}

Manage Conversations

Manage all features and functionalities combined with ReviewSpotter conversations.

Start conversation

Provide all options related with starting a new conversation.


URL Structure : /apps/{app-key}/conversations

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Optional The type of the entity, this is defined by the user while creating the Entity Type. query string
entity-id Optional Entity id, of the entity which conversation needs to be created. Entity ids can be retrieved by Get app mapped entities query string
group-key Optional The group-id of the Group which conversation needs to be created. Group IDs can be retrieved by Retrieve All Application Groups query string
title Optional The title of the new conversation. query string
priority-level ANY of the ;
CRITICAL
MEDIUM
LOW
Select the priority-level from the given list. query string
limited-to-shared True/False
Default : False
Set shared options, default value will limit access from users. query boolean
incident True/False
Default : False
Set the conversation as an incident if required. query boolean
shared-emails Optional Give a comma separated user email list of shared users query string
started-from ANY of the ;
GENERAL
UPDATES
Give the source of the conversation. Select UPDATES if the conversation is continued from an update. query string

Sample response :

{
    "status": "successful",
    "results": [
        {
            "id": "",
            "message": ""
        }
    ]
}

Retrieve all conversations

Loads all available conversations.


URL Structure : /apps/{app-key}/conversations

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Optional The type of the entity, this is defined by the user while creating the Entity Type. query string
entity-id Optional Entity id, of the entity which conversation needs to be retrived. Entity ids can be retrieved by Get app mapped entities query string
group-key Optional The group-id of the Group which conversation needs to be retrived. Group IDs can be retrieved by Retrieve All Application Groups query string
conversation-type ANY of the ;
GENERAL
UPDATES
The type of the conversation. Select UPDATES to retrieve daily updates. query string
priority-level ANY of the ;
CRITICAL
MEDIUM
LOW
Select the priority-level from the given list. This is defined when a new conversation is started. query string
from-date Optional Give from date to filter conversations. query string
is-incident True/False
Default : False
Select True or False form given options to filter conversations. query boolean
to-date Optional Set the to-date to define the time period. query string
started-from ANY of the ;
GENERAL
UPDATES
Give the source of the conversation. Select UPDATES if the conversation is continued from an update. query string

Sample response :

{
    "status": "successful",
    "results": [
        {
            "modelVersion": "",
            "conversationId": "",
            "title": "",
            "startedBy": "",
            "startedByDisplayName": "",
            "startedAt": "",
            "closedBy": "",
            "closedByDisplayName": "",
            "closedAt": "",
            "lastUpdatedAt": "",
            "status": "",
            "conversationType": "",
            "startedFromType": "",
            "priorityLevel": "",
            "markedAsIncident": "",
            "incidentStatus": "",
            "appKey": "",
            "entityType": "",
            "entityId": "",
            "groupKey": "",
            "limitedToShared": "",
            "sharedEmails": [],
            "deleted": ""
        }
    ]
}

Retrieve a conversation

Filters a specific conversation when the conversation ID is given.


URL Structure : /apps/{app-key}/conversations/{conversation-id}

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
conversation-id Required The conversation ID is a system generated value. IDs can be retrieved through the Retrieve All Conversations method. path string

Sample response :

{
    "status": "successful",
    "results": [
        {
            "modelVersion": "",
            "conversationId": "",
            "title": "",
            "startedBy": "",
            "startedByDisplayName": "",
            "startedAt": "",
            "closedBy": "",
            "closedByDisplayName": "",
            "closedAt": "",
            "lastUpdatedAt": "",
            "status": "",
            "conversationType": "",
            "startedFromType": "",
            "priorityLevel": "",
            "markedAsIncident": "",
            "incidentStatus": "",
            "appKey": "",
            "entityType": "",
            "entityId": "",
            "groupKey": "",
            "limitedToShared": "",
            "sharedEmails": [],
            "deleted": ""
        }
    ]
}

Add a conversation message

Add a new message to an existing conversation.


URL Structure : /apps/{app-key}/conversations/{conversation-id}/messages

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
conversation-id Required The conversation ID is a system generated value. IDs can be retrieved through the Retrieve All Conversations method. path string
message-date Optional The date to be added as the display date of the message. query string
message-type Optional Specify the type of the message. query string
data Optional The message body goes here. Body
(Parameter content type: application/json)
Model | Example Value

{ "message": "string" }

Sample response :

{
    "status": "successful",
    "results": [
        {
            "id": "",
            "message": ""
        }
    ]
}

Retrieve all messages

Load all messages of a conversation when the conversation ID is given.


URL Structure : /apps/{app-key}/conversations/{conversation-id}/messages

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
entity-type Optional The type of the entity, this is defined by the user while creating the Entity Type. query string
entity-id Optional Entity id, of the entity which conversation needs to be retrived. Entity ids can be retrieved by Get app mapped entities query string
group-key Optional The group-id of the Group which conversation needs to be retrived. Group IDs can be retrieved by Retrieve All Application Groups query string
conversation-type ANY of the ;
GENERAL
UPDATES
Select type of the conversation. Select UPDATES if the conversation is continued from an update. query string
conversation-id Optional
Give the ID of the conversation, this is a system generated value. Conversation IDs can be retrieved by Retrieve All Conversations path string
from-date Optional Give the date to start filtering messages. query string
to-date Optional Set an end date to the date filter. query string
offset Optional The starting index of the review to be retrieved. query integer
limit Optional Limit the number of review retrievals. query integer

Sample response :

{
    "status": "successful",
    "results": [
        {
            "modelVersion": "",
            "mbId": "",
            "parentId": "",
            "messageBubbleType": "",
            "messageBubbleStatus": "",
            "deleted": "",
            "user": "",
            "displayName": "",
            "createdTime": "",
            "message": "",
            "appKey": "",
            "files": []
        }
    ]
}

Retrieve a message

Loads a specific message of a conversation when the message ID is given.


URL Structure : /apps/{app-key}/conversations/{conversation-id}/messages/{message-id}

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
conversation-id Optional
Give the ID of the conversation, this is a system generated value. Conversation IDs can be retrieved by Retrieve All Conversations path string
message-id Required An ID of a specific message. This is a system generated value. Message ids can be retrieved by Retrieve All Messages path string

Sample response :

{
    "status": "successful",
    "results": [
        {
            "modelVersion": "",
            "mbId": "",
            "parentId": "",
            "messageBubbleType": "",
            "messageBubbleStatus": "",
            "deleted": "",
            "user": "",
            "displayName": "",
            "createdTime": "",
            "message": "",
            "appKey": "",
            "files": []
        }
    ]
}

Delete a conversation message

Deletes a specific message from a conversation when the message ID is specified


URL Structure : /apps/{app-key}/conversations/{conversation-id}/messages

Method : DELETE

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
conversation-id Required The conversation ID is a system generated value. IDs can be retrieved through the Retrieve All Conversations method. path string
message-id Required An ID of a specific message. This is a system generated value. Message ids can be retrieved by Retrieve All Messages. query string

Sample response :


								{
    "status": "successful",
    "results": [
        {
            "id": "",
            "message": ""
        }
    ]
}

Change incident status

Allows to change the status of an available conversation.


URL Structure : /apps/{app-key}/conversations/{conversation-id}/incident-status

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
conversation-id Required The conversation ID is a system generated value. Conversation IDs can be retrieved using the Retrieve All Conversations method. path string
status ANY of the;
OPEN
REOPENED
IN_PROGRESS
ON_HOLD
DONE
IN_REVIEW
VERIFIED
REJECTED
CLOSED
Select a new status form the given list. query string

Sample response :

{
    "status": "successful",
    "results": [
        {
            "message": ""
        }
    ]
}

Change conversation settings

The method can be used to modify an existing conversation.


URL Structure : /apps/{app-key}/conversations/{conversation-id}/settings

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
conversation-id Required The conversation ID is a system generated value. IDs can be retrieved through the Retrieve All Conversations method. path string
title Optional The modified title. query string
limited-to-shared True/False
Default : True
Select to change conversation shared users. query string
shared-emails Optional Give user emails to share the conversation. query string
incident True/False
Default : True
Select a given option to change the conversation status. query string
priority-level ANY of the;
CRITICAL
MEDIUM
LOW
Select the new priority-level from the given list. query string

Sample response :

{
    "status": "successful",
    "results": [
        {
            "message": ""
        }
    ]
}

Change conversation status

Can be used to change the conversation status of an existing conversation.


URL Structure : /apps/{app-key}/conversations/{conversation-id}/status

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
conversation-id Required The conversation ID is a system generated value. IDs can be retrieved through the Retrieve All Conversations method. path string
status ANY of the;
ONGOING
STOPPED
Select an option form the given list to change the status. query string

Sample response :

{
    "status": "successful",
    "results": [
        {
            "message": ""
        }
    ]
}

Delete conversation

Delets a specific conversation when the conversation ID is specified


URL Structure : /apps/{app-key}/conversations/{conversation-id}

Method : DELETE

Parameters :

Parameters Value Description Parameter Type Data Type
access-token Required An access-token is provided in an event of logging in to the system. Refer Retrieve an access token to retrieve the token. query string
app-key Required The app-key can be retrieved from the Retrieve all applications method. path string
conversation-id Required The conversation ID is a system generated value. Conversation IDs can be retrieved using the Retrieve All Conversations method. path string

Sample response :

{
    "status": "successful",
    "results": [
        {
            "message": ""
        }
    ]
}