Introduction

Welcome to SmartKarrot! Look up the features and SDKs you can integrate into your apps.

1. Usage analytics
2. App analytics
3. Survey and feedback
4. Custom health score ratings
5. Financial data

There are a number of different APIs you can use to integrate with a SmartKarrot Platform. But sometimes it’s difficult to know what each API is for and when to use it. This document explains the APIs that are available.

Probably the most well-known API format/structure is the REST API. As its name implies, it uses REST as a wrapper (point-to-point call) for API operations. Probably the bulk of our API traffic is from the REST API because it has become the de facto standard for microservices across industries.

To start with, we’ve got a series of APIs, about seven of them now. While they all achieve a similar purpose – in one sense – of accessing data from your application (user & event data to measure product and customer success) or from the third-party integrations that you use, but there are some key differences among them which are worth explaining. First, it’s important to note that all of these APIs operate identically across SmartKarrot.

The four API’s categories that make up SmartKarrot Platform are:

Usage Analytics

The APIs in this section are core to SmartKarrot Platform and are used to gather User, Device & Event Information. For example, through the use of these APIs, we gather information about the events that are fired by users of your application along with the user and device information so that you can get a comprehensive understanding of the stickiness of your product for your users.

App Analytics

These are a set of default information related to your users' behavior that our SDK captures on your behalf. For example, if you want to know the average session length of users for a given period of time, or your app page load performance, or the users that visited your app recently, then our SDK captures this analytics data out of the box for you.

Survey and Feedback

If you have integrated our Survey SDK, then you can send surveys (multiple input question) and pulses (single input question) to your end users or to your Key Stakeholders for your customer accounts.

Custom Health Score Ratings

This push API helps you to send define custom health score parameters for your customers as well as define the rating standard for these custom parameters. In a way, you get the choice out of the box to measure your customer the way you have been measuring them till date on SmartKarrot Platform. Thereby, reduces the overload of learning and behavioral change on your part.

Financial Data

The financial information about your customer (ARR, MRR, churn, etc.) all form an integral part of gauging Customer and Product Success. So at SmartKarrot, we realized the need to have a push API in place through which you can send in your customer financial information that will help you understand the different financial metrics for each customer account.

Option A: SDK Integration

Follows these steps to integrate the SmartKarrot SDK:

1. Get your App ID.
2. Integrate REST API.
3. Add our SDK to your app.
4. Configure the SmartKarrot integration.
5. Configure User and Event attributes.

Get Your App ID

Get your App ID from SmartKarrot Support Team (email: [email protected]).

Note: All Parameters are case sensitive

Add our SDK to Your App

SmartKarrot provides iOS, Android and Web (JavaScript) SDKs.

iOS App

You can install the SDK using CocoaPods.

For installing using CocoaPods, add the line pod 'UsageAnalytics' to your Podfile and install it with pod install. The current version of the SDKs is 6.0.0.

Android App

allprojects {
  repositories {
    // add this repository at the bottom of the repositories list
    maven { 
      url "https://s3.amazonaws.com/smartkarrot-android-repo/"
    }
  }
}

The Android SDK comes as a Java library. Installing it is simple. Just add the lines to the right to your project-level build.gradle file.

Then add these lines to your App's build.gradle file:

implementation 'com.smartkarrot:usageanalytics:6.0.0'

Proguard Configuration

If you are using proguard in your app, add this configuration in your proguard-rules.pro file:

-keep class com.smartkarrot.** { *; }

-keepclassmembers class com.smartkarrot.** { *; }

Web - JavaScript

Add the following code in head tag of your HTML page.

<script src="https://docs.smartkarrot.com/frameworks/web/v4/multi-product/UsageAnalytics.js"></script>

Angular: Declare declare var UsageAnalytics; to access UsageAnalytics from the Angular component.

Hybrid - Cordova/PhoneGap/Ionic Plugin

1. Download SmartKarrot Plugin, download.

2. Add SmartKarrot plugin to your app.
   
   Cordova plugin add SmartKarrot

   After adding you will see an entry in config.xml

   <plugin name="SmartKarrot" spec="SmartKarrot" />

3. Declare the Cordova plugin in the app page where this has to be used.

declare let cordova:any;

Configure the SmartKarrot Integration

The SmartKarrot SDK must be initialized before using any of its functions.

iOS App

Import the SDK into the AppDelegate.swift file with

import UsageAnalytics

Add this to your AppDelegate.swift file

UsageAnalytics.shared.configure(appId: String, userId: String? = nil, customerAccountId: String? = nil, productId: String? = nil, organizationId: String? = nil, autoCapture: Bool = true)

Only the appId is mandatory. You could set the userId, customerAccountId, and the productId if it is available with you.

Android App

Add this line to the onCreate method of your activity or Application class.

UsageAnalytics.init(Context this,String appId,String customerAccountId,String productId,Boolean autoCapture);

Only the appId is mandatory. You could set the userId, customerAccountId, and the productId if it is available with you. Auto capture screen view events by setting autoCapture to true.

Web - JavaScript

Add the following JavaScript line to your HTML page to initialize the SDK.

UsageAnalytics.configure("app_api_key", "customer-account-id", "option-a", "product-id")

Hybrid - Cordova/PhoneGap/Ionic Plugin

The plugin has to be initialized in the code after the view is loaded i.e. in the life cycle event ionViewDidEnter

ionViewDidEnter() { this.configureSmartKarrot(); }

configureSmartKarrot() { let appId = "your-app-id"; let userId = "your-app-user-id";

var successCallBack = function (successResult) { console.log(successResult); }

var failureCallBack = function (errorResult) { console.log(errorResult); }

cordova.plugins.SmartKarrot.configure(appId, userId, successCallBack, failureCallBack); }

Replace the appId & userId with actual values

This section describes how you can send usage analytics data to SmartKarrot. SmartKarrot helps you collect three types of usage data:

1. User information
2. Device information
3. Event information

The SDK caches events when an Internet connection is not available. The SDK uses a store-and-forward buffer to send events and user and device information every 120 seconds to minimize the impact on power usage.

Set User Id

UsageAnalytics.shared.set(userId: "your-app-user-id", "customer-account-id")

UsageAnalytics.getInstance().setUserId("your-app-user-id", "customer-account-id");

UsageAnalytics.setUser("your-app-user-id", "customer-account-id");

cordova.plugins.SmartKarrot.setUserId(“your-user-id”, successCallback(), failureCallback());

SmartKarrot treats a user as a "guest" user - with an internally generated user ID, until you set a user ID. Once you set the user ID, the guest user is considered as having logged in as that user. Events logged of the guest user are transferred to the logged-in user.

Set Product Id (SDK)

UsageAnalytics.shared.set(productId: "product-id")

UsageAnalytics.getInstance().setProductId("product-id");

Set the product ID when the user switches to another product.

Find your product id here: Product Configuration

Reset User Id

UsageAnalytics.shared.resetUserId()

UsageAnalytics.getInstance().resetUserId();

UsageAnalytics.resetUser();

cordova.plugins.SmartKarrot.resetUserId(successCallback(), failureCallBack());

Reset the user Id when the user has logged out of the system. SmartKarrot logs events generated after the reset as a guest user.

Set User Attributes

UsageAnalytics.shared.set(value: "en-us", for: .language)

UsageAnalytics.getInstance().setUserAttribute(UserAttribute.language, "en-us");

// Using Standard UserAttribute "language".
UsageAnalytics.setUserAttribute(UsageAnalytics.UserAttribute.language, "en-us");

// Standard UserAttributes:
//
//    UsageAnalytics.UserAttribute {
//        userId,
//        name,
//        emailId,
//        mobileNumber,
//        dateOfBirth,
//        gender,
//        country,
//        language,
//        designation
//    }

# Using Standard UserAttribute "Language".

cordova.plugins.SmartKarrot.setUserAttribute("Language", "en-us", successCallback(), failureCallback());

# Standard UserAttributes

# UsageAnalytics.UserAttribute { userId, name, emailId, mobileNumber, dateOfBirth, gender, country, language, designation }

# User Id (“User Id”)
# Name - (“Name”)
# Email Id - (“Email Id”)   
# Mobile Number - (“Mobile Number”)
# Date Of Birth - (“Date Of Birth”)
# Gender - (“Gender”)
# Country - (“Country”)
# Language - (“Language”)
# Designation - (“Designation”)

User attributes can be the user's language preference, zip code, city, or country. User attributes are useful in segmenting users. SmartKarrot has a set of standard user attributes:

1. userId
2. name
3. emailId
4. mobileNumber
5. dateOfBirth
6. gender
7. country
8. language
9. designation

UsageAnalytics.shared.set(value: 096, for: "Employee Id") // Custom Attriute

UsageAnalytics.shared.set(value: "John Doe", for: UserAttribute.name) // Standard User Attribute

UsageAnalytics.shared.set(value: "HR", for: "Designation") // Standard User Attribute

UsageAnalytics.getInstance().setUserAttribute("Employee Id", 096);

//  Custom UserAttribute.
UsageAnalytics.setUserAttribute("Employee Id", 096);

# Using Custom UserAttribute "Employee Id".

cordova.plugins.SmartKarrot.setUserAttribute("Employee Id", 096, successCallback(), failureCallback());

You can set custom user attributes when your app needs a specific one. The attribute value can be a string, number (int, float, or double), boolean, or date.

Log Events

// Log without event attributes.
UsageAnalytics.shared.log(event: "Signed In")

// Log with event attributes.
UsageAnalytics.shared.log(event: "Screen View", with: ["Screen Name": "News List Screen"])

// Log with event attributes.
UsageAnalytics.shared.log(event: "Signed In", with: [
    "Module" : "Login", // Standard Event Attribute
    "Type": "Email Login", 
    "Day": "Monday",
    "Discount Applied": true
])

// Log without event attributes.
UsageAnalytics.getInstance().logEvent("Signed In");

// Log with event attributes.
EventParameters params = new EventParameters.Builder()
    .addParameter("Module", "Login") // Standard Event Attribute
    .addParameter("Type", "Email Login")
    .addParameter("Day", "Monday")
    .addParameter("Discount Applied", true)
    .build();
UsageAnalytics.getInstance().logEvent("Signed In", params);

// Log without event attributes.
UsageAnalytics.logEvent("Signed In");

// Log with event attributes.
var eventParams = {
    "Module" : "Login", // Standard Event Attribute
    "Type": "Email Login",
    "Day": "Monday",
    "Discount Applied": true
}
UsageAnalytics.logEvent("Signed In", eventParams); 

cordova.plugins. SmartKarrot.logEvent("Signed In", ”value”, successCallback(), failureCallback())

 # Where “value” is a string and can also accept stringify(d) JSON object. 

You can log screen views and other events to SmartKarrot. Examples of app events are the user opening a screen, purchasing a product, or logging in. The SDK automatically logs events like the user opening the app and closing it. You can add your events using our SDK.

Events may have attributes associated with them. For example, a “Purchased Product” event may have attributes like “Product ID” with a value “B01M3TD8CF” and “Deliver to ZIP Code” as “07120-4719". An event can have up to five attributes.

A good place to add the screen view event is the viewDidAppear method of the view controller.

The SDK sends events to the server in a low priority queue, so user functionality is not affected. Events are buffered and sent every 120 seconds to reduce constant network traffic. When an internet connection is not available, the SDK automatically stores and forwards events.

SmartKarrot has a standard event attribute.

1. Module

Device Attributes

The SmartKarrot SDK automatically collects these device attributes. No action is required from your end.

1. App Name: The display name of the app.
2. App Bundle Identifier
3. App Build: The build version in the iOS project settings (in the Info.plist).
4. App Version: The app version in the iOS project settings. This is not the version in the App Store.
5. Device Id: This is an alphanumeric string that uniquely identifies a device to the app’s vendor as provided by iOS.
6. Device Name: This is the device name as set in the iOS device settings at General > About settings.
7. Device Make: Set as "Apple" for iOS devices.
8. Device Model
9. OS: The device operating system.
10. OS Version
11. System Language: The language set in the iOS device settings at General > Language & Region > iPhone Language. The data collected is in the two-letter ISO 693-1 format.
12. System Currency: The currency set in the iOS device settings at General > Language & Region > Region. The currency is derived from the region and is in the three-letter alphabetic code in the ISO 4217 format.
13. System Region: The currency set in the iOS device settings at General > Language & Region > Region. This is typically the user's country and is in the two-letter alphabetic code in the ISO 3166-1 format.

Update Device Token

Android

If you are not already using Firebase Cloud Messaging in your app you need to add FCM in your app. Follow this guide to add firebase to your app: Firebase Android Setup..

Then change your Notification Receiver service class (with intent filter com.google.firebase.MESSAGING_EVENT ) as follows,

public class MyFirebaseNotificationService extends FirebaseMessagingService {
    @Override
    public void onNewToken(String s) {
        super.onNewToken(s);
        UsageAnalytics.updateDeviceToken(s);
        // Handle token if you are implementing FCM in your app.
    }
    // Rest of your code
}

Setting up auto token refresh

Add this after initializing the core SDK:

UsageAnalytics.getInstance().setTokenFactory(new FirebaseTokenFactory() {
    @Override
    public void updateToken() {
        FirebaseInstanceId.getInstance().getInstanceId().addOnCompleteListener(new OnCompleteListener<InstanceIdResult>() {
            @Override
            public void onComplete(@NonNull Task<InstanceIdResult> task) {
                if(task.isSuccessful())
                    UsageAnalytics.updateDeviceToken(task.getResult().getToken());
            }
        });
    }
});

Option B: REST API Integration

Get Your App ID

Add an app in the Settings section of the SmartKarrot portal, and locate the App ID under App Configuration. Every app has two API keys: one for the sandbox and one for production. The sandbox key is used for development and testing, and the production one for live transactions.

Get the separate REST API Key from SmartKarrot Support Team (email: [email protected]).

Note: All Parameters are case sensitive

API Reference

SmartKarrot offers private REST API for its SaaS services. The API makes it easier to quickly configure and integrate your Web app directly with our server.

The API supports Cross-origin resource sharing (CORS).

URL

The SmartKarrot API is available at:

Environment	URL
Production	https://api.smartkarrot.com/v4

Authentication

SmartKarrot uses the Basic Authentication mechanism with an API key to authenticate requests. For example, if your API key is daced09f-8ade-48dc-b1d8-506204530ce3, you can log an event with a simple HTTP POST request:

curl -v -u apikey:daced09f-8ade-48dc-b1d8-506204530ce3 -H "Content-Type: application/json" -d '{"appId": "4ed062f1-fc38-4f32-a714-b63dc5399626","platform":"iOS","deviceId": "53e11019-8034-496b-a484-fa978918873c","loginMechanism" : "AUTH","bundleId": "com.smartkarrot.tasks","lastLoggedInUserId": "f1d0c16d-f9e0-4eb4-8739-45574c43f508","userId": "8f2dfb97-fe4b-49b3-a5d5-a671335cde00","sessionId": "234240-234-234-234-234-234237B891079-A302-4DDD-8860-2672B9682A3B","status": "Active","customerAccountId": "de8327c8-ece7-427a-ba8f-e4c7809ea716"}' 'https://api.smartkarrot.com/v4/usageanalytics/user'

Data Types

The SDK uses the following data types.

Type	Description
String	A simple quoted string, following standard JSON rules; see the JSON spec for details.
Integer	A whole number, transmitted as a JSON number.
Boolean	A JSON boolean, the literal string true or false.
Array	A JSON array. Each element contains a payload that will be described.
Timestamp	Time in UTC stored in the ISO 8601 format with millisecond precision. (Example: 2018-09-29T09:58:44.635Z)
UUID	A UUID string. Preferably a version 4 UUID. Example: f30ccccf-54a8-49bf-b3e4-6eee274810ab.
Decimal	A decimal value, encoded in a JSON string. The contents will be a series of digits, followed by an optional decimal point and additional digits.

Create or Update Parent Account Endpoint

Use this endpoint to create a new parent customer account or update an existing one.

HTTPS Request

POST /usageanalytics/customer

Complete URL

https://api.smartkarrot.com/v4/usageanalytics/customer

Sample Request

{
  "accountId": "de8327c8-ece7-427a-ba8f-e4c7809ea716",
  "appId": "4ed062f1-fc38-4f32-a714-b63dc5399626",
  "name" : "SmartKarrot",
  "accountType": "PARENT",
  "createTime": "2022-05-20",
  "userEmailId": "[email protected]",
  "userRole": "customer success manager",
  "typeOfAssignment": "primary",
   "base64EncodedLogoImage" : "iVBORw0KGgoAAAANSUhEUgAAADAAAAAwCAYAAABXAvmHAAAAAXNSR0IArs4c6QAAAVlpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IlhNUCBDb3JlIDUuNC4wIj4KICAgPHJ",
  "productIds":["91ed7505-f106-4e03-b88b-63b76693f391"],
  "status": "Active", 
  "variationType": "ACCOUNT",
}

Request Body

Parameter	Type	Required	Description
accountId	String	required	The customer account ID in your system.
appId	String	required	SmartKarrot App ID.
name	String	required	Name of the customer account.
accountType	String	required	Enum: PARENT
createTime	String	optional	Date of creation 'yyyy-mm-dd' format.
userEmailId	String	optional	CSM email ID to be tagged.
userRole	String	optional	Enum: customer success manager, CSM Leader, Account Executive, Implementation Manager
typeOfAssignment	String	optional	Enum: primary, secondary
base64EncodedLogoImage	String	optional	Image in base64 encoded string. The image size should be less than 3 MB.
productIds	Array	optional	You will get your product Ids from the Settings: Configure Products.
status	String	required	Enum: Active, Inactive
variationType	String	optional	Enum: ACCOUNT Configure mapping by account or by product.

Sample Output

{
  "status": "SUCCESS"
}

Response Body

Use this endpoint to create a new customer account or update an existing one.

Log customer account response.

Parameter	Type	Description
status	String	Enum SUCCESS, ERROR, INVALID_INPUT

Create or Update Child Account Endpoint

Use this endpoint to create a new child customer account or update an existing one.

HTTPS Request

POST /usageanalytics/customer

Complete URL

https://api.smartkarrot.com/v4/usageanalytics/customer

Sample Request

{

  "accountId": "de8327c8-ece7-427a-ba8f-e4c7809ea716",
  "appId": "4ed062f1-fc38-4f32-a714-b63dc5399626",
  "name" : "SmartKarrot",
  "accountType": "CHILD",
  "createTime": "2022-05-20", 
  "userEmailId": "[email protected]",
  "userRole": "customer success manager",
  "typeOfAssignment": "primary",
  "parentAccountId":"ye8627c8-ece7-424a-ba8f-e3c7809ea715",
  "base64EncodedLogoImage" : "iVBORw0KGgoAAAANSUhEUgAAADAAAAAwCAYAAABXAvmHAAAAAXNSR0IArs4c6QAAAVlpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IlhNUCBDb3JlIDUuNC4wIj4KICAgPHJ",
  "productIds":["91ed7505-f106-4e03-b88b-63b76693f391"],
  "status": "Active",
  "variationType": "PRODUCT"
}

Request Body

Parameter	Type	Required	Description
accountId	String	required	The customer account ID in your system.
appId	String	required	SmartKarrot App ID.
name	String	required	Name of the customer account.
accountType	String	required	Enum: CHILD
createTime	String	optional	Date of creation 'yyyy-mm-dd' format.
userEmailId	String	optional	CSM email ID to be tagged.
userRole	String	optional	Enum: customer success manager, CSM Leader, Account Executive, Implementation Manager
typeOfAssignment	String	optional	Enum: primary, secondary
parentAccountId	String	optional	To link with parent account.
base64EncodedLogoImage	String	optional	Image in base64 encoded string. The image size should be less than 3 MB.
productIds	Array	optional	You will get your product Ids from the Settings: Configure Products.
status	String	required	Enum: Active, Inactive
variationType	String	optional	Enum: PRODUCT, ACCOUNT Configure mapping by account or by product.

Sample Output

{
  "status": "SUCCESS"
}

Response Body

Use this endpoint to create a new customer account or update an existing one.

Log customer account response.

Parameter	Type	Description
status	String	Enum SUCCESS, ERROR, INVALID_INPUT

Create or Update Singular Account Endpoint

Use this endpoint to create a new child customer account or update an existing one.

HTTPS Request

POST /usageanalytics/customer

Complete URL

https://api.smartkarrot.com/v4/usageanalytics/customer

Sample Request

{
  "accountId": "de8327c8-ece7-427a-ba8f-e4c7809ea716",
  "appId": "4ed062f1-fc38-4f32-a714-b63dc5399626",
  "name" : "SmartKarrot",
  "accountType": "CHILD",
  "createTime": "2022-05-20", 
  "userEmailId": "[email protected]",
  "userRole": "customer success manager",
  "typeOfAssignment": "primary",
  "base64EncodedLogoImage" : "iVBORw0KGgoAAAANSUhEUgAAADAAAAAwCAYAAABXAvmHAAAAAXNSR0IArs4c6QAAAVlpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IlhNUCBDb3JlIDUuNC4wIj4KICAgPHJ",
  "productIds":["91ed7505-f106-4e03-b88b-63b76693f391"],
  "status": "Active",
  "variationType": "PRODUCT",
}

Request Body

Parameter	Type	Required	Description
accountId	String	required	The customer account ID in your system.
appId	String	required	SmartKarrot App ID.
name	String	required	Name of the customer account.
accountType	String	required	Enum: CHILD
createTime	String	optional	Date of creation 'yyyy-mm-dd' format.
userEmailId	String	optional	CSM email ID to be tagged.
userRole	String	optional	Enum: customer success manager, CSM Leader, Account Executive, Implementation Manager
typeOfAssignment	String	optional	Enum: primary, secondary
base64EncodedLogoImage	String	optional	Image in base64 encoded string. The image size should be less than 3 MB.
productIds	Array	optional	You will get your product Ids from the Settings: Configure Products.
status	String	required	Enum: Active, Inactive
variationType	String	optional	Enum: PRODUCT, ACCOUNT Configure mapping by account or by product.

Sample Output

{
  "status": "SUCCESS"
}

Response Body

Use this endpoint to create a new customer account or update an existing one.

Log customer account response.

Parameter	Type	Description
status	String	Enum SUCCESS, ERROR, INVALID_INPUT

Update Customer Account’s Segment Attributes

Use this endpoint to update a customer account segment.

HTTPS Request

POST /account-view/update-segment-attributes

Complete URL

https://api.smartkarrot.com/v4/account-view/update-segment-attributes

Sample Request

{
     "appId": "1d7b1062-106a-4f95-a136-a2eec114b6f0",
     "customerSegments": [
    {
      "customerAccountId": "123456",
      "segmentValues": {
        "Subscription": "Enterprise",
        "Countries": "India",
        "Verticals": "Banking"
      },
      "phase":"Advocacy"
    }
    ]
}

Request Body

Parameter	Type	Required	Description
appId	String	required	SmartKarrot App ID.
customerAccountId	String	required	The customer account ID as in your system.
Subscription	String	optional	Range of services.
Countries	String	optional	Place of business.
Verticals	String	optional	Business sector.
phase	String	optional	Stages of account.

Sample Output

{
  "status": "SUCCESS"
}

Response Body

Use this endpoint to update customer account segment .

Log customer account segment response.

Parameter	Type	Description
status	String	Enum SUCCESS, ERROR,

Create Custom Attribute/ Metadata

Use this endpoint to create a new custom attribute.

HTTPS Request

POST /account-view/attributes

Complete URL

https://api.smartkarrot.com/smart-dashboard/v4/account-view/attributes

Sample Request

{
 "appId": "1d7b1062-106a-4f95-a136-a2eec114b6f0",
 "accountData": [
  {
   "accountId": "123456",
   "data": [
    {
      "category": "Smart",
      "attributes": {
       "key1": "value1",
      "key2": "value2"
     }
    }

   ]
  }
 ]
} 

Request Body

Parameter	Type	Required	Description
appId	String	required	SmartKarrot App ID.
accountId	String	required	The customer account ID as in your system.
category	String	optional	Provide category of meta data.
attributes	String	optional	Provide attributes of that specific category .

Sample Output

{
  "status": "SUCCESS"
}

Response Body

Use this endpoint to create a new custom attribute.

Log custom attribute response.

Parameter	Type	Description
status	String	Enum SUCCESS, ERROR,

Update Utilization at Subscription Level

It's the value between maximum available utilization licenses and the actual usage of the available licenses.

HTTPS Request

POST /platform-setting/customer-account-configuration

Complete URL

https://api.smartkarrot.com/dashboards/v4/platform-setting/customer-account-configuration

Sample Request

{
  "accountDetail": [
    {
      "appId": "1d7b1062-106a-4f95-a136-a2eec114b6f0",
      "customerAccountId": "123456",
      "orderId": "abcd8765",
      "licenseCreatedOn": "2022-06-17",
      "productId": "26f4b204-fec5-47a8-a891-cbba18987ff1",
      "licenseList": [
        {
          "licenseTypeId": "A",
          "licenseTypeName": "A",
          "maxLicences": 600,
          "licences":500
        }
      ]
    }
  ]
}

Request Body

Parameter	Type	Required	Description
appId	String	required	SmartKarrot App ID.
customerAccountId	String	required	The customer account ID as in your system.
orderId	String	optional	Id of existing order.
licenseCreatedOn	String	optional	Created date of license .
productId	String	required	You will get your product Ids from the Settings: Configure Products.
licenseTypeId	String	optional	Id of license.
licenseTypeName	String	optional	Name of license.
maxLicences	String	optional	Maximun number of licenses user have.
licences	String	optional	utilized number of licenses.

Sample Output

{
  "status": "SUCCESS"
}

Response Body

Use this endpoint to update utilization licences.

Log update response.

Parameter	Type	Description
status	String	Enum SUCCESS, ERROR,

Update Utilization at Account Level

It's the value between maximum available utilization licenses and the actual usage of the available licenses.

HTTPS Request

POST /platform-setting/customer-account-configuration

Complete URL

https://api.smartkarrot.com/dashboards/v4/platform-setting/customer-account-configuration

Sample Request

{
  "accountDetail": [
    {
      "appId": "1d7b1062-106a-4f95-a136-a2eec114b6f0",
      "customerAccountId": "123456",
      "licenseCreatedOn": "2022-06-17",
      "productId": "26f4b204-fec5-47a8-a891-cbba18987ff1",
      "licenseList": [
        {
          "licenseTypeId": "A",
          "licenseTypeName": "A",
          "maxLicences": 600,
          "licences":500
        }
      ]
    }
  ]
}

Request Body

Parameter	Type	Required	Description
appId	String	required	SmartKarrot App ID.
customerAccountId	String	required	The customer account ID as in your system.
licenseCreatedOn	String	optional	Created date of license .
productId	String	required	You will get your product Ids from the Settings: Configure Products.
licenseTypeId	String	optional	Id of license.
licenseTypeName	String	optional	Name of license.
maxLicences	String	optional	Maximum number of licenses customer have.
licences	String	optional	utilized number of licenses.

Sample Output

{
  "status": "SUCCESS"
}

Response Body

Use this endpoint to update utilization licences.

Log update response.

Parameter	Type	Description
status	String	Enum SUCCESS, ERROR,

Adding Health Score value to custom parameter set

Use this endpoint to add values to custom parameter set.

HTTPS Request

POST /csm/account-view/multiple-custom-param

Complete URL

https://api.smartkarrot.com/dashboards/v4/csm/account-view/multiple-custom-param

Sample Request

{
  "appId": "1d7b1062-106a-4f95-a136-a2eec114b6f0",
  "accounts":[
  {
    "accountId":"123456",
    "customScores":[
       {
          "customParameterName":"Custom Index",
          "score":8
       }
    ]  
  }]
}

Request Body

Parameter	Type	Required	Description
appId	String	required	SmartKarrot App ID.
accountId	String	required	The customer account ID as in your system.
customParameterName	String	required	Name of the set up Custom Parameter for the Health score.
score	String	required	Value of the set up custom parameter(0-10).

Sample Output

{
  "status": "SUCCESS"
}

Response Body

Use this endpoint to add values to custom parameter set.

Log custom parameter set response.

Parameter	Type	Description
status	String	Enum SUCCESS, ERROR,

Create or Update User Endpoint

Use this endpoint to create a user ID when a user is using your app. A user can be a guest user, in which case, you can generate a random UUID for the user. If a user is logged in, use this endpoint to create the user in SmartKarrot.

Creating a user is required only once, and is not required if the user is already added to SmartKarrot through a backend upload process.

HTTPS Request

POST usageanalytics/user

Complete URL

https://api.smartkarrot.com/v4/usageanalytics/user

Sample Request

{
  "appId": "4ed062f1-fc38-4f32-a714-b63dc5399626",
  "customerAccountId": "de8327c8-ece7-427a-ba8f-e4c7809ea716",
  "userId": "8f2dfb97-fe4b-49b3-a5d5-a671335cde00",
  "status": "Active",
  "bundleId": "com.smartkarrot.tasks",
  "loginMechanism" : "AUTH",
  "platform":"iOS",
  "sessionId": "234240-234-234-234-234-234237B891079-A302-4DDD-8860-2672B9682A3B",
  "deviceId": "53e11019-8034-496b-a484-fa978918873c"
}

Request Body

Parameter	Type	Required	Description
appId	String	required	SmartKarrot App Id.
customerAccountId	String	required	The system customer account id.
userId	String	required	The system user Id.
status	String	required	Enum: Active, Inactive
bundleId	String	optional	Client unique id.(Android Package Name, iOS Bundle Id and Web Domain Name)
loginMechanism	String	required	Enum 'AUTH', 'GUEST', If the user is in your system then send AUTH else GUEST.
platform	String	required	Enum: iOS, Android, Web
sessionId	String	optional	Client session Id.
deviceId	String	optional	Client device Id.

Sample Output

{
  "status": "SUCCESS"
}

Response Body

Log user response.

Parameter	Type	Description
status	String	Enum SUCCESS, ERROR, INVALID_INPUT

Log Custom Events Endpoint

You can log screen views and other events to SmartKarrot. Examples of app events are the user opening a screen, purchasing a product, or logging in.

Events may have attributes associated with them. For example, a “Purchased Product” event may have attributes like “Product ID” with a value “B01M3TD8CF” and “Deliver to ZIP Code” as “07120-4719". An event can have up to five attributes.

Multiple events can be logged in the same call.

HTTPS Request

POST usageanalytics/event

Complete URL

https://api.smartkarrot.com/v4/usageanalytics/event

Sample Request

{
  "events": [
    {
      "name": "Purchase Product",
      "loggedAtTime": "2020-03-28T12:07:58.165Z",
      "parameters": [
        {
          "attributeName": "Module",
          "dataType": "String",
          "stringValue": "Product"
        },
        {
          "attributeName": "List Price",
          "dataType": "String",
          "stringValue": "$ 45"
        }
      ]
    }
  ],
  "userId": "28f05cea-4721-0818-2a7c-a88b102012fa",
  "appId": "a8548489-6d1d-44c4-b068-061f48c9f93c",
  "customerAccountId": "35373-67203-62612-15373-63900-1440",
  "productId":"91ed7505-f106-4e03-b88b-63b76693f391",
  "sessionId": "d28d89fwi5eupw8wfw7f94",
  "deviceId": "45010143537367203626121537363900144024",
  "platform": "Web",
  "userSourceIP":"142.250.182.36",
  "appVersion": "1.0"
}

Request Body

The list of events.

Parameter	Type	Required	Description
events	[Event]	required	An array of events.
userId	String	required	The user ID in your system.
appId	String	required	SmartKarrot App ID.
customerAccountId	String	required	The customer account ID as in your system.
productId	String	optional	SmartKarrot Product Id for your product.
sessionId	String	optional	Client session ID.
deviceId	String	optional	The unique device ID.
platform	String	required	Enum: iOS, Android, Web

The Event structure is as follows.

Parameter	Type	Required	Description
name	String	required	Event name.
loggedAtTime	String	required	ISO 8601 format.
parameters	[EventParameter]	optional	Event parameters

A Event parameter structure is as follows.

Parameter	Type	Required	Description
attributeName	String	required	Event attribute name.
dataType	String	required	Enum String, Number, Date, Boolean
stringValue	String	optional	Required only if dataType is String or Date. Date: ISO 8601 format.
numberValue	Number	optional	Required only if dataType is Number.
booleanValue	Bool	optional	Required only if dataType is Bool.

Sample Output

{
  "status": "SUCCESS"
}

Response Body

Log events response.

Parameter	Type	Description
status	String	Enum SUCCESS, ERROR, INVALID_INPUT

Log app_session_start events

Sample Structure for Mandatory Paramenters (app_session_start)

Sample Request -- App Session Start

{
  "events": [
    {
      "name": "app_session_start",
      "loggedAtTime": "2019-03-28T12:07:58.165Z",
      "parameters": [
        {
          "attributeName": "sessionId",
          "dataType": "String",
          "stringValue": "j28d89f9wi5eup4789794"
        },
        {
          "attributeName": "startTime",
          "dataType": "Date",
          "stringValue": "2019-03-28T12:07:58.165Z"
        }
      ]
    }
  ],
  "userId": "28f05cea-4721-0818-2a7c-a88b102012fa",
  "appId": "a8548489-6d1d-44c4-b068-061f48c9f93c",
  "deviceId": "45010143537367203626121537363900144024",
  "platform": "Web",
  "customerAccountId": "35373-67203-62612-15373-63900-1440",
  "productId":"91ed7505-f106-4e03-b88b-63b76693f391",
  "userSourceIP":"142.250.182.36",
  "appVersion": "1.0"
}

Request Body

The sessionId and startTime in the event parameters are required parameters for some calculations for analytics.

Parameter	Type	Required	Description
events	[Event]	required	An array of events.
userId	String	required	The user ID in your system.
appId	String	required	SmartKarrot App ID.
customerAccountId	String	required	The customer account ID as in your system.
productId	String	optional	SmartKarrot Product Id for your product.
sessionId	String	required	Client session ID.
deviceId	String	optional	The unique device ID.
platform	String	required	Enum: iOS, Android, Web

The Event structure is as follows.

Parameter	Type	Required	Description
name	String	required	Event name.
loggedAtTime	String	required	ISO 8601 format.
parameters	[EventParameter]	optional	Event parameters

A Event parameter structure is as follows.

Parameter	Type	Required	Description
attributeName	String	required	Event attribute name.
dataType	String	required	Enum String, Number, Date, Boolean
stringValue	String	optional	Required only if dataType is String or Date. Date: ISO 8601 format.
numberValue	Number	optional	Required only if dataType is Number.
booleanValue	Bool	optional	Required only if dataType is Bool.

Sample Output

{
  "status": "SUCCESS"
}

Response Body

Log events response.

Parameter	Type	Description
status	String	Enum SUCCESS, ERROR, INVALID_INPUT

Sample Request -- App Session End

{
  "events": [
    {
      "name": "app_session_end",
      "loggedAtTime": "2019-03-28T12:07:58.165Z",
      "parameters": [
        {
          "attributeName": "sessionId",
          "dataType": "String",
          "stringValue": "j28d89f9wi5eup4789794"
        },
        {
          "attributeName": "endTime",
          "dataType": "Date",
          "stringValue": "2019-03-28T12:07:58.165Z"
        }
      ]
    }
  ],
  "userId": "28f05cea-4721-0818-2a7c-a88b102012fa",
  "appId": "a8548489-6d1d-44c4-b068-061f48c9f93c",
  "deviceId": "45010143537367203626121537363900144024",
  "platform": "Web",
  "customerAccountId": "35373-67203-62612-15373-63900-1440",
  "productId":"91ed7505-f106-4e03-b88b-63b76693f391",
  "userSourceIP":"142.250.182.36",
  "appVersion": "1.0"
}

Log app_session_end events

Sample Structure for Mandatory Paramenters (app_session_end)

Request Body

The sessionId and endTime in the event parameters are required paramters for some calculations for analytics.

Parameter	Type	Required	Description
events	[Event]	required	An array of events.
userId	String	required	The user ID in your system.
appId	String	required	SmartKarrot App ID.
customerAccountId	String	required	The customer account ID as in your system.
productId	String	optional	SmartKarrot Product Id for your product.
sessionId	String	required	Client session ID.
deviceId	String	optional	The unique device ID.
platform	String	required	Enum: iOS, Android, Web

The Event structure is as follows.

Parameter	Type	Required	Description
name	String	required	Event name.
loggedAtTime	String	required	ISO 8601 format.
parameters	[EventParameter]	optional	Event parameters

A Event parameter structure is as follows.

Parameter	Type	Required	Description
attributeName	String	required	Event attribute name.
dataType	String	required	Enum String, Number, Date, Boolean
stringValue	String	optional	Required only if dataType is String or Date. Date: ISO 8601 format.
numberValue	Number	optional	Required only if dataType is Number.
booleanValue	Bool	optional	Required only if dataType is Bool.

Sample Output

{
  "status": "SUCCESS"
}

Response Body

Log events response.

Parameter	Type	Description
status	String	Enum SUCCESS, ERROR, INVALID_INPUT

Sample Request -- Page Load Event

{
  "events": [
    {
      "name": "page_load_event",
      "loggedAtTime": "2019-03-28T12:07:58.165Z",
      "parameters": [
        {
          "attributeName": "requestCount",
          "dataType": "Number",
          "numberValue": 54
        },
        {
          "attributeName": "loadTime",
          "dataType": "Number",
          "numberValue": 32.3
        },
        {
          "attributeName": "pageUrl",
          "dataType": "String",
          "stringValue": "https://devstage.smartkarrot.com/#/demo-events"
        }
      ]
    }
  ],
  "userId": "28f05cea-4721-0818-2a7c-a88b102012fa",
  "appId": "a8548489-6d1d-44c4-b068-061f48c9f93c",
  "sessionId": "j28d89f9wi5eup4789794",
  "deviceId": "45010143537367203626121537363900144024",
  "platform": "Web",
  "customerAccountId": "35373-67203-62612-15373-63900-1440",
  "productId":"91ed7505-f106-4e03-b88b-63b76693f391",
  "userSourceIP":"142.250.182.36",
  "appVersion": "1.0"
}

Log page_load_event events

Sample Structure for Mandatory Paramenters (page_load_event)

Request Body

The event page_load_event has some required parameters as provided in the sample event that should be passed for calculating the Performance Index. The parameters are "requestCount", "loadTime" and "pageUrl".

Parameter	Type	Required	Description
events	[Event]	required	An array of events.
userId	String	required	The user ID in your system.
appId	String	required	SmartKarrot App ID.
customerAccountId	String	required	The customer account ID as in your system.
productId	String	optional	SmartKarrot Product Id for your product.
sessionId	String	optional	Client session ID.
deviceId	String	optional	The unique device ID.
platform	String	required	Enum: iOS, Android, Web

The Event structure is as follows.

Parameter	Type	Required	Description
name	String	required	Event name.
loggedAtTime	String	required	ISO 8601 format.
parameters	[EventParameter]	optional	Event parameters

A Event parameter structure is as follows.

Parameter	Type	Required	Description
attributeName	String	required	Event attribute name.
dataType	String	required	Enum String, Number, Date, Boolean
stringValue	String	optional	Required only if dataType is String or Date. Date: ISO 8601 format.
numberValue	Number	optional	Required only if dataType is Number.
booleanValue	Bool	optional	Required only if dataType is Bool.

Sample Output

{
  "status": "SUCCESS"
}

Response Body

Log events response.

Parameter	Type	Description
status	String	Enum SUCCESS, ERROR, INVALID_INPUT

Set User Attributes Endpoint

User attributes can be the user's language preference, her zip code, city, or country. User attributes are useful in segmenting users. SmartKarrot has a set of standard user attributes:

1. userId
2. name
3. emailId
4. mobileNumber
5. dateOfBirth
6. gender
7. country
8. language
9. designation
10. persona

You can add or update custom user attributes when your app needs a specific one. The attribute value can be a string, number (int, float, or double), boolean, or date.

HTTPS Request

POST /usageanalytics/user/attribute

Complete URL

https://api.smartkarrot.com/v4/usageanalytics/user/attribute

Sample Request

{
    "userId": "3bdbe037-7fef-430c-92ed-021c4774d4be",
    "deviceId": "107f0cb1-a663-47ef-8efb-8f62e2bd1644",
    "platform": "d026ab01-71b5-49e0-a594-5f5cf40043b0",
    "appId": "6846ca43-f85b-44ed-a27b-9fbefb2f098c",
    "sessionId": "8c3b4198-c58a-4534-b3d8-79a70d71bb7d",
    "customerAccountId": "20b349b4-ef71-455b-b190-9d9f6fcac142",
    "userAttributes": [
        {
            "name": "Name",
            "dataType": "String",
            "stringValue": "Jane Doe",
            "loggedAtTime": "2018-12-14T07:46:31.565Z"
        },
        {
            "name": "Email Id",
            "dataType": "String",
            "stringValue": "[email protected]",
            "loggedAtTime": "2018-12-14T07:46:31.565Z"
        },
        {
            "name": "Designation",
            "dataType": "String",
            "stringValue": "VP Sales",
            "loggedAtTime": "2018-12-14T07:46:31.565Z"
        },
        {
            "name": "Persona",
            "dataType": "String",
            "stringValue": "Executive",
            "loggedAtTime": "2018-12-14T07:46:31.565Z"
        },
        {
            "name": "Mobile Number",
            "dataType": "String",
            "stringValue": "+1 1234567890" ,
            "loggedAtTime": "2018-12-14T07:46:31.565Z"
        },
        {
            "name": "City",
            "dataType": "String",
            "stringValue": "Los Angeles",
            "loggedAtTime": "2018-12-14T07:46:31.565Z"
        },
        {
            "name": "State",
            "dataType": "String",
            "stringValue": "California",
            "loggedAtTime": "2018-12-14T07:46:31.565Z"
        },
        {
            "name": "Country",
            "dataType": "String",
            "stringValue": "United States",
            "loggedAtTime": "2018-12-14T07:46:31.565Z"
        },
        {
            "name": "Gender",
            "dataType": "String",
            "stringValue": "Female",
            "loggedAtTime": "2018-12-14T07:46:31.565Z"
        },
        {
            "name": "Language",
            "dataType": "String",
            "stringValue": "English",
            "loggedAtTime": "2018-12-14T07:46:31.565Z"
        }
    ]

}

Request Body

The list of user attributes.

Parameter	Type	Required	Description
userAttributes	[UserAttribute]	required	An array of user attributes.
userId	String	required	The system user Id.
appId	String	required	SmartKarrot App Id.
sessionId	String	optional	Client session Id.
deviceId	String	optional	Client device Id.
idempotencyId	String	required	Unique key for the request, v4 UUID is recommended.
platform	String	required	Enum: iOS, Android, Web
customerAccountId	String	optional	The system customer account id. Required for multilevel organizations.

A User Attribute structure is as follows.

Parameter	Type	Required	Description
name	String	required	User attribute name.
dataType	String	required	Enum String, Number, Date, Boolean
loggedAtTime	String	required	ISO 8601 format.
stringValue	String	optional	Required only if dataType is String or Date. Date: ISO 8601 format.
numberValue	Number	optional	Required only if dataType is Number.
booleanValue	Bool	optional	Required only if dataType is Bool.

Sample Output

{
  "status": "SUCCESS"
}

Response Body

Log user attributes response.

Parameter	Type	Description
status	String	Enum SUCCESS, ERROR, INVALID_INPUT

Log Device Attributes Endpoint

If you use the SmartKarrot SDK, it automatically collects these device attributes. No action is required from your end.

If you decide to use this REST API, you could choose to populate one or more of the device attributes.

1. Device Id: This is an alphanumeric string that uniquely identifies a device to the app’s vendor as provided by iOS.
2. App Name: The display name of the app.
3. App Bundle Identifier
4. App Build: The build version in the iOS project settings (in the Info.plist).
5. App Version: The app version in the iOS project settings. This is not the version in the App Store.
6. Device Name: This is the device name as set in the iOS device settings at General > About settings.
7. Device Make: Set as "Apple" for iOS devices.
8. Device Model
9. OS: The device operating system.
10. OS Version
11. System Language: The language set in the iOS device settings at General > Language & Region > iPhone Language. The data collected is in the two-letter ISO 693-1 format.
12. System Currency: The currency set in the iOS device settings at General > Language & Region > Region. The currency is derived from the region and is in the three-letter alphabetic code in the ISO 4217 format.
13. System Region: The currency set in the iOS device settings at General > Language & Region > Region. This is typically the user's country and is in the two-letter alphabetic code in the ISO 3166-1 format.

HTTPS Request

POST /usageanalytics/device/attribute

Complete URL

https://api.smartkarrot.com/v4/usageanalytics/device/attribute

Sample Request

{
  "appId": "4ed062f1-fc38-4f32-a714-b63dc5399626",
  "platform": "Web",
  "deviceId": "53e11019-8034-496b-a484-fa978918873c",
  "idempotencyId": "9890BDAA-CF16-4A08-A8F7-9F680D9ADEBA",
  "userId": "8f2dfb97-fe4b-49b3-a5d5-a671335cde00",
  "sessionId": "234240-234-234-234-234-234237B891079-A302-4DDD-8860-2672B9682A3B",
  "deviceAttributes": {
    "App Bundle Identifier": "org.app.demo.UsageAnalytics",
    "Make": "Apple"
  }
}

Request Body

The list of user's device attributes.

Parameter	Type	Required	Description
appId	String	required	SmartKarrot App Id.
platform	String	required	Enum: iOS, Android, Web
deviceId	String	optional	Client device Id.
idempotencyId	String	required	Unique key for the request, v4 UUID is recommended.
userId	String	required	The system user Id.
sessionId	String	optional	Client session Id.
deviceAttributes	Map	required	A key-value pair of device attributes. Key and value are String type.

Any custom device attributes can be logged. Some of the pre-defined keys for device attributes are:

'Device ID', 'Device Name', 'Make', 'Model', 'OS', 'OS Version', 'System Language', 'System Currency', 'System Region', 'App Name', 'App Bundle Identifier', 'App Build', 'App Version'

The data collected for the attributes below should be in their respective formats.

1. System Language: Two-letter code ISO 693-1 format.
2. System Currency: Three-letter alphabetic code in the ISO 4217 format.
3. System Region: Two-letter alphabetic code in the ISO 3166-1 format.

Sample Output

{
  "status": "SUCCESS"
}

Response Body

Log device attributes response.

Parameter	Type	Description
status	String	Enum SUCCESS, ERROR, INVALID_INPUT

Option C: Auto-Capture Events

SmartKarrot automatically captures user interactions in your app. Drop a line of code to add our SDK, and another to initialize it and we are all set.

SmartKarrot will automatically capture events for every screen loaded and every tap. No developer effort is required. Want to manage the events that are stored? Head over to our platform and quickly select the ones you want SmartKarrot to capture. And while you are at it, give the events more convenient names and assign them to features.

Inside the SDK, a store-and-forward buffer minimizes the number of calls made to the server. A debounce logic ensures that a rapid tap-tap-tap, say to the same button, gets neatly grouped as one.

The auto-capture is available across our Web, iOS, and Android SDKs.

Quick Start - JavaScript SDK

1. Add our SDK to your app.
2. Start the SDK.
3. Tell us who is logged in.

Add the SDK to Your App

Add the following code in head tag of your HTML page.

<script src="https://docs.smartkarrot.com/frameworks/web/v4/auto/multi-product/UsageAnalytics.js"></script>

If you are using the Angular Web application framework, add declare var UsageAnalytics;.

Initialize the SDK

Initialize the SDK with this one line of code.

UsageAnalytics.configure("app-id", "customer-account-id", "option-c", "product-id")

Set User ID

UsageAnalytics.setUser("your-app-user-id", "customer-account-id", "product-id");

SmartKarrot treats a user as a "guest" user with an internally generated user ID until you set a user ID. Once you have assigned a user to the screen session, events logged of the guest user are transferred to the logged-in user.

Set Product Id

Note: All Parameters are case sensitive

UsageAnalytics.setProductId("product-id");

Set the product ID when the user switches to another product.

Find your product id here: Product Configuration

More Functions

Reset User ID

UsageAnalytics.resetUser();

Use this to tell SmartKarrot when a user has logged out. SmartKarrot logs events generated after the reset as those for a guest user.

Set User Attributes

// Using Standard UserAttribute "language".
UsageAnalytics.setUserAttribute(UsageAnalytics.UserAttribute.language, "en-us");

// Standard UserAttributes:
//
//    UsageAnalytics.UserAttribute {
//        userId,
//        name,
//        emailId,
//        mobileNumber,
//        dateOfBirth,
//        gender,
//        country,
//        language,
//        designation
//    }

SmartKarrot's segmentation is helped when it knows more about the user. Pass on user attributes like their language preference, ZIP code, city, or country. SmartKarrot has a set of standard user attributes:

1. User ID
2. Name
3. Email ID
4. Mobile Number
5. Date of Birth
6. Gender
7. Country
8. Language
9. Designation
10. Persona javascript // Custom UserAttribute. UsageAnalytics.setUserAttribute("Employee Id", 096);

You can set custom user attributes when your app needs a specific one. The attribute value can be a string, number (int, float, or double), boolean, or date.

iOS Auto-Capture

Add the SDK as described in Option A: SDK Integration. The SDK automatically captures screen views and tags them with the name of the view controller class.

You can switch off auto-capture using the autoCapture flag in the UsageAnalytics.shared.configure function.

Swizzling

SmartKarrot uses method swizzling to auto-capture screen views when the viewDidAppear(_:) method of the UIViewController is executed. Developers who prefer not to use swizzling can disable it using the autoCapture flag in the UsageAnalytics.shared.configure function.

Android Auto-Capture

The Android SDK automatically captures activity and fragment transitions.

You can switch off auto-capture using the autoCapture flag in the UsageAnalytics.init function.

App Analytics SDK

Engagement Score & Score Maturity

Duration Index

Loyalty Index

Loyalty Index is a measure of the percentage of user churn, i.e. the percentage of total users uninstalling the app to the total users installing the app in a given time period. If you have to enable Loyalty Index for your app, you need to add the following lines of code:

Enabling Loyalty Index for iOS

To enable Loyalty Index for your iOS app, you need to submit your Apple Push Notification certificates. There is a detailed step by step guide to generate them: external link After generating the certificates, submit the Dev & Prod certificates in .p12 format wihle app on boarding.

On your app side, add the following lines of codes:

// Add these functions to your AppDelegate file

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        UsageAnalytics.shared.didRegisterForRemoteNotificationsWithDeviceToken(deviceToken: deviceToken)
    }

func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
    UsageAnalytics.shared.didFailToRegisterForRemoteNotificationsWithError(error: error)
}

Enabling Loyalty Index for Android

To enable Loyalty Index for your android app you need to register for Firebase Cloud Messaging and then submit your app's FCM key (available as Server Key in your Firebase console.).

A detailed guide about registering your app for FCM can be found here: external link.

Then change your Notification Receiver service class (with intent filter com.google.firebase.MESSAGING_EVENT) as follows,

public class MyFirebaseNotificationService extends FirebaseMessagingService {
    @Override
    public void onNewToken(String s) {
        super.onNewToken(s);
        UsageAnalytics.updateDeviceToken(s);
        // Handle token if you are implementing FCM in your app.
    }
    // Rest of your code
}

Enabling Loyalty Index for Hybrid - Cordova/PhoneGap/Ionic

The pushNotificationDeviceToken will be the deviceToken obtained while using any push notification providers. This value can be obtained during push notification registration of the provider.

cordova.plugins.SmartKarrot.registerNotificationWithToken(“pushNotificationDeviceToken”, successCallback(), failureCallback())

If the app fails to register for push Notification, use the below code

cordova.plugins.SmartKarrot.failRegisterNotificationWithError(“error”, successCallback(), failureCallback())

No code is required to configure Loyalty Index for Android.

Retention Index

Feedback Index

Feedback Index is a measure of your app's rating across iOS App Store & Google Playstore.

Enabling for iOS

iOS App Store ratings are publicly available. So, you don't need to do anything.

Enabling for Android App:

For Android, you need to authorize the SmartKarrot platform to fetch your app's rating on your behalf. For this, you need to generate a service account with view access and submit the credentials json file while onboarding. Here is step by step guide to help you service account credentials file: Generating Service Account

Realtime Engagement

Survey and Feedback SDK

This module lets you run a survey with a single line of code. Build your survey on the SmartKarrot web platform. Integrate the SDK and run the survey in three quick steps:

1. Add our SDK to your app.
2. Configure the SmartKarrot integration.
3. Run the survey.

Step 1: Add our SDK to Your App

SmartKarrot provides iOS and Android SDKs.

iOS App

You can install the SDK using CocoaPods.

For installing using CocoaPods, add the line pod 'SmartKarrot-Survey' to your Podfile and install it with pod install.

• Update Your App's Info.plist File with NSPhotoLibraryUsageDescription.

Survey SDK uses Camera or Gallery to upload photos for Survey. The NSPhotoLibraryUsageDescription key is now required for access to Photos.

      <key>NSPhotoLibraryUsageDescription</key>
      <string>This App uses Camera or Gallery to upload photos for Survey.</string>

Android App

allprojects {
  repositories {
    maven { url "https://s3.amazonaws.com/smartkarrot-android-repo/" }
  }
}

The Android SDK comes as a Java library. Installing it is simple adding the lines to the right to your project level build.gradle file. You may have already completed this step when adding any other SmartKarrot SDK.

Then add this to your App's build.gradle file:

implementation 'com.smartkarrot:survey:6.0.0'

Web - JavaScript

Survey features are already available in Web - JavaScript Core SDK (UsageAnalytics).

Hybrid - Cordova/PhoneGap/Ionic

Survey features are already available in SmartKarrot plugin.

Step 2: Configure the SDK

The SDK must be initialized before using any of its functions.

iOS App

Import the SDK with into AppDelegate.swift file with

import SmartKarrot_Survey

Add this to your AppDelegate.swift file

Survey.shared.configure()

Android App

Add this line to the onCreate method of your activity or Application class.

Survey.init(context);

Web - JavaScript

Survey features are already configured as part of Web - JavaScript Core SDK (UsageAnalytics) integration.

Hybrid - Cordova/PhoneGap/Ionic

Call configureSurvey to configure SDK.

cordova.plugins.SmartKarrot.configureSurvey()

Step 3: Run the SDK

The SmartKarrot Survey SDK can be used to launch a single survey or to display a list of available surveys and let the user take the survey they choose.

List Available Surveys

This is the easiest way to launch a survey. The SmartKarrot SDK view lists all available surveys, letting the user choose a survey to start. If only one survey is available, the SDK launches it automatically.

iOS

  Survey.shared.listSurveys(from: viewController, animated: true)

The survey will be presented from a UIViewController. Typically, this is the view controller whose view is currently visible. The SmartKarrot SDK automatically dismisses the SDK view controller once the user has completed or abandoned the survey.

Android

  Survey.getInstance().listSurveys(context); 
  // `user_id` is the id of the user in your app.

You can add the user name and other information about the user by integrating the SmartKarrot Usage Analytics SDK.

Web - JavaScript

  UsageAnalytics.listSurveys(); 
  // `user_id` is the id of the user in your app.

This will display a list of surveys.

Hybrid - Cordova/PhoneGap/Ionic

  # List Surveys
  # This will render from native view.
  cordova.plugins.SmartKarrot.listSurveys(animated:true, successCallBack(), failureCallBack());

This will display a list of surveys from native view.

Start a Single Survey

  UsageAnalytics.startSurvey("survey-id");

  Survey.shared.startSurvey(surveyId: "survey-id", from: viewController, animated: true)
  // The user-id of the user taking the survey is taken from UsageAnalytics SDK.

  Survey.getInstance().startSurvey(context, "survey-id");
   // `user_id` is the id of the user in your app.

   # Single Survey
   # This will render from native view.

   # For Android
   cordova.plugins.SmartKarrot.startSurvey("survey-id", "app-user-id", successCallBack(), failureCallBack());

   # For iOS
   let animated= "true | false";
   cordova.plugins.SmartKarrot.startSurvey("survey-id", animated, successCallBack(), failureCallBack());

Add this line to launch a single survey with given id. You can get the survey id from SmartKarrot dashboard.

Financial Data Integration

This section describes how you can send financial data to SmartKarrot. SmartKarrot helps you collect three types of financial data:

1. Orders
2. Invoices
3. App Financial data

URL for Financial Integration

The SmartKarrot API for financial data is available at:

Environment	URL
Production	https://api.smartkarrot.com/dashboards/v4/financial

Get REST API Key

Get REST API Key from SmartKarrot Support Team (email: [email protected]).

Authenticate using API key.

SmartKarrot uses the Basic Authentication mechanism with an API key to authenticate requests. For example, if you API key is daced09f-8ade-48dc-b1d8-506204530ce3, you can log an order with a simple HTTP POST request:

curl -v -u apikey:daced09f-8ade-48dc-b1d8-506204530ce3 -H "Content-Type: application/json" -d '{ "appId" :"3956ca1e-d306-4dea-abc1-bfdabe44b524", "productId":"c519d994-a0cb-41f9-89ba-074a63923239" "orderId":"038883ee-88b5-4851-a0cd-eb704e085cfe", "customerAccountId":"csm-id-CA", "status":"Activated", "amount" : 21325.0, "effectiveDate":"2019-05-12", "endDate" :"2020-05-12" }' 'https://api.smartkarrot.com/dashboards/v4/financial/orders/'

Orders

HTTPS Request
POST    /orders         [create or update an order]

The orders are the basic object in Financial data dashboard around which many operations are centered. Basically, orders are components of contracts by which we get to know the amount or the revenues generated by a particular account. Based on the amount the ARR, MRR and other data in the Financial Dashboard are calculated.

Create or Update an order

HTTPS Request

POST /orders

This api is used to create an order in Smartkarrot. If the same order is pushed using the same api it will update the if any change is passed on to the system.

Complete URL

https://api.smartkarrot.com/dashboards/v4/financial/orders

Sample Request

{
  "customerAccountId": "d28f2cc6-4385-47b7-ab51-3fda6d0c1ab6",
  "appId": "c50f05b4-0fc7-43c7-88f6-46f0f0aef4a3",
  "orgProductId":"91ed7505-f106-4e03-b88b-63b76693f391",
  "orderId": "8920b276-5d2f-457c-87c4-af7156d2fe95",
  "status": "Activated",
  "amount": 8400,
  "effectiveDate": "2020-01-01",
  "endDate": "2020-12-31",
  "orderType":"Renewal order",
}

Request Body

Parameter	Type	Required	Description
customerAccountId	String	required	The customer account ID in your system.
appId	String	required	SmartKarrot App ID.
orgProductId	String	required	SmartKarrot Product Id for your product.
orderId	String	required	The order ID in your system.
status	String	required	Enum Activated, Draft
amount	Number (Double)	required	Amount of the Order.
effectiveDate	String	required	The start date of the order in 'yyyy-mm-dd' format.
endDate	String	required	The end date of the order in 'yyyy-mm-dd' format.
orderType	String	optional	Type of order.

Sample Output

{
  "status": "SUCCESS"
}

Response Body

Response for creating an order.

Parameter	Type	Description
status	String	Enum SUCCESS, ERROR, INVALID_INPUT

Create or Update bulk order

HTTPS Request

POST /orders/bulk

This api is used to create bulk order in Smartkarrot. If the same order is pushed using the same api it will update the if any change is passed on to the system.

Complete URL

https://api.smartkarrot.com/dashboards/v4/financial/orders/bulk

Sample Request

{
"appId": "d8c9a5d5-46eb-4ebf-97bf-62345a19e9d8",
    "orders": [
        {

            "customerAccountId": "6e4ece1f-64ab-45b1-b61a-4b4846b1f48d",
            "orgProductId": "590f15c5-8309-4755-b30f-5fe037353594",
            "orderId": "8920b276-5d2f-457c-87c4-af7156d2fe95",
            "status": "Activated",
            "amount": 16950,
            "effectiveDate": "2021-04-01",
            "endDate": "2023-01-30",
            "orderType":"Renewal order"
        },
        {

            "customerAccountId": "fg74ece1f-64ab-45b1-b61a-4b4846b1f465",
            "orgProductId": "cdd0f15c5-8309-4755-b30f-cdscsdc",
            "orderId": "wsdw324234-5d2f-457c-87c4-cscwdwdwd",
            "status": "Activated",
            "amount": 16950,
            "effectiveDate": "2021-04-06",
            "endDate": "2023-09-30",
            "orderType":"Renewal order"
        }
    ]
}

Request Body

Parameter	Type	Required	Description
appId	String	required	SmartKarrot App ID.
customerAccountId	String	required	The customer account ID in your system.
orgProductId	String	required	SmartKarrot Product Id for your product.
orderId	String	required	The order ID in your system.
status	String	required	Enum Activated, Draft
amount	Number (Double)	required	Amount of the Order.
effectiveDate	String	required	The start date of the order in 'yyyy-mm-dd' format.
endDate	String	required	The end date of the order in 'yyyy-mm-dd' format.
orderType	String	optional	Type of order.

Sample Output

{
  "status": "SUCCESS"
}

Response Body

Response for creating an order.

Parameter	Type	Description
status	String	Enum SUCCESS, ERROR, INVALID_INPUT

Invoices

HTTPS Request
POST    /invoices         [create or update an invoice]

The invoice are the basic object in Financial data dashboard around which many operations are centered. Basically, invoices are components of contracts by which we get to know the amount or the revenues generated by a particular orders/subscriptions. Based on the amount the ARR, MRR and other data in the Financial Dashboard are calculated.

Create or Update an Invoice

HTTPS Request

POST /invoices

This api is used to create an invoice in Smartkarrot. If the same invoice is pushed using the same api it will update the if any change is passed on to the system.

Complete URL

https://api.smartkarrot.com/dashboards/v4/financial/invoices

Sample Request

{
  "appId": "c53a1b79-9386-4963-9327-56d57f6cd21a",       
  "invoices": [
    {
    "customerAccountId": "jkd-4395njj4r900jgf984m-548j",     
     "invoiceId": "34566822-390f-461f-9093-acp291bpp5a4",        
      "orderId": "12300006-5d0f-057c-87c4-af7150d0f000",
      "invoiceType": "Monthly",    
      "invoiceDescription": "Inv21102020IN215En",  
      "invoiceAmount": 6000,           
      "dateInvoiced": "2020-10-27",    
      "invoiceStatus": "Paid",
      "datePaid": "2020-10-27",
      "invoicePeriodStart": "2020-10-01",          
      "invoicePeriodEnd": "2020-10-31" ,            
      "customFields": [
        {
          "name": "Customer Name",
          "stringValue": "DOMZOOM"
        },
        {
          "name": "Customer Plan",
          "stringValue": "monthly"
        },
        {
          "name": "Units",
          "integerValue": 400
        },
        {
          "name": "GST",
          "doubleValue": 3.55
        }
      ],            
    }
  ]
}

Request Body

Parameter	Type	Required	Description
appId	String	required	SmartKarrot App ID.
customerAccountId	String	required	The customer account ID in your system.
invoiceId	String	required	The invoice ID in your system.
orderId	String	optional	The order ID in your system.
invoiceType	String	required	Type of Invoice.
invoiceDescription	String	required	Description of Invoice.
invoiceAmount	Number (Double)	required	Amount of the Invoice.
dateInvoiced	String	required	Date of invoice creation in 'yyyy-mm-dd' format.
invoiceStatus	String	optional	Enum Paid Pending.
datePaid	String	optional	Date of invoice paid in 'yyyy-mm-dd' format.
invoicePeriodStart	String	required	Start Date of invoice in 'yyyy-mm-dd' format.
invoicePeriodEnd	String	required	End Date of invoice in 'yyyy-mm-dd' format.

Sample Output

{
  "status": "SUCCESS"
}

Response Body

Response for creating an order.

Parameter	Type	Description
status	String	Enum SUCCESS, ERROR, INVALID_INPUT

App Financial Data

HTTPS Request
POST    /app-financial-data                       [create or update a configuration of an app]
DELETE  /app-financial-data/{your-app-id}         [delete the configuration related to app]

The configuration of an app must be provided for calculation of financial data which will reflect in the Financial Dashboard.

Create or Update a configuration of app

HTTPS Request

POST /app-financial-data

This api is used to set the customer churn tolerance value for the app. This will remain same for each customer accounts, customer success managers.

Complete URL

https://api.smartkarrot.com/dashboards/v4/financial/app-financial-data

Sample Request

{
  "appId" : "1d7b1062-106a-4f95-a136-a2eec114b6f0",
  "orgId": "e661d9e8-e831-41e4-b4f6-a4e27754d168",    
  "logoChurnTolerance": 0.07,   //7%
  "mrrGracePeriod": 8,
  "currency": "Indian Rupee",
  "bussinessUnit" : [
      {
          "businessUnitId": "JK45YJK",
          "businessUnitName": "Name123"

      }

  ],

}

Request Body

Parameter	Type	Required	Description
appId	String	required	SmartKarrot App ID.
orgId	String	required	SmartKarrot organization ID.
logoChurnTolerance	String	required	The upper limit of customer churn.
mrrGracePeriod	Number	optional	An additional period beyond the due date(max 3 months).
currency	String	optional	Enum Indian Rupee, American Dollar, British Pound, Philippine Peso,Singapore Dollar, Euro
businessUnitId	String	optional	Id of business.
businessUnitName	String	optional	Name of business.

Sample Output

{
  "status": "SUCCESS"
}

Response Body

Response for creating an order.

Parameter	Type	Description
status	String	Enum SUCCESS, ERROR, INVALID_INPUT

Delete an app configuration

DELETE /app_financial_data/{your-app-id}

This api is used to delete a configuration (churn tolerance) related to an app which is passed in the params. Request parameters are not required.

Complete URL

https://api.smartkarrot.com/dashboards/v4/financial/app_financial_data/{your-app-id}

Sample Output

{
  "status": "SUCCESS"
}

Response Body

Response for creating an order.

Parameter	Type	Description
status	String	Enum SUCCESS, ERROR, INVALID_INPUT

Tickets (Case Management) Integration

This section describes how you can manage the tickets data in SmartKarrot. A ticket is created by a contact or an agent. A ticket is assigned to an agent.

URL for Ticket Integration

The SmartKarrot API is available at:

Environment	URL
Production	https://api.smartkarrot.com/v4

Authentication (Basic)

SmartKarrot uses an API key with the Basic Auth mechanism to authenticate requests. For example, if your API key is daced09f-8ade-48dc-b1d8-506204530ce3, you can post a comment on a ticket with a simple HTTP POST request:

curl -v -u apikey:daced09f-8ade-48dc-b1d8-506204530ce3 -H "Content-Type: application/json" -d '{"ticketId": "a354da06-ef51-4570-a473-7e7986d9bcac","description":"Description 3.0 for the comment","createdByType": "agent","createdBy" : "056f8591-3d96-4de8-8c9c-b8c713bc102a"}' 'https://api.smartkarrot.com/v4/tickets/comment'

Contacts

Get contacts

Sample input parameters: Get contacts

{
  "appId": "2d07df27-cc9e-4533-a321-dfcfe049a6ea",
  "limit": 2,
  "nextPageToken": "eyJjb250YWN0SWQiOnsicyI6Ijk0YmJhMzM0LWU4NDktNDE2NC05MGRhLTQ4OTIzNjhlZjMxYSJ9LCJjcmVhdGVUaW1lIjp7InMiOiIyMDIwLTExLTIzVDA2OjE2OjIzLjgyMFoifSwiYXBwSWQiOnsicyI6IjJkMDdkZjI3LWNjOWUtNDUzMy1hMzIxLWRmY2ZlMDQ5YTZlYSJ9fQ=="
}

Sample output parameters:

{
  "count": 2,
  "contacts": [
    {
      "contactId": "eb0e2a19-0fb0-4405-8c6f-3c220d4acfa6",
      "orgId": "1895cce0-f676-4cb9-9d7c-a01faaf934c9",
      "appId": "2d07df27-cc9e-4533-a321-dfcfe049a6ea",
      "firstName": "Anne",
      "lastName": "Rodriguez",
      "role": "VP Customer Success",
      "email": "[email protected]",
      "phoneNumber": "3044444473",
      "countryCode": "1",
      "status": "active",
      "accountId": "a88ffaab-d889-46bc-afb3-4c09875fa3b5",
      "displaySuggestion": true,
      "isChampion": true
    },
    {
      "contactId": "c16248e0-7f1a-432f-aaa1-9cd052e9fc4e",
      "orgId": "1895cce0-f676-4cb9-9d7c-a01faaf934c9",
      "appId": "2d07df27-cc9e-4533-a321-dfcfe049a6ea",
      "firstName": "Arturo",
      "lastName": "Rains",
      "role": "CS Head",
      "email": "[email protected]",
      "phoneNumber": "2032518504",
      "countryCode": "1",
      "status": "active",
      "accountId": "9612bfab-0485-4162-9d77-c0bb007d1ce0",
      "displaySuggestion": true,
      "isChampion": true
    }
  ],
  "nextPageToken": "eyJjb250YWN0SWQiOnsicyI6ImMxNjI0OGUwLTdmMWEtNDMyZi1hYWExLTljZDA1MmU5ZmM0ZSJ9LCJjcmVhdGVUaW1lIjp7InMiOiIyMDIxLTAyLTEyVDExOjA0OjAzLjM3MFoifSwiYXBwSWQiOnsicyI6IjJkMDdkZjI3LWNjOWUtNDUzMy1hMzIxLWRmY2ZlMDQ5YTZlYSJ9fQ=="
}

Endpoint

GET /tickets/contacts

Complete URL

https://api.smartkarrot.com/v4/tickets/contacts

Description

This endpoints gets contacts stored in SmartKarrot.

The query is paginated and returns up to 1,000 records at a time. You can change the number of records fetched with the limit parameter. The nextPageToken in the response should be used as an input to get the next set of contacts. Email address and Salesforce ID are additional filters available as query parameters.

Input Parameters

Parameter	Type	Required	Description
appId	String	Required	SmartKarrot App ID.
emailId	String	Optional	The email address to be searched.
salesforceId	String	Optional	The Salesforce contact ID to be searched.
limit	Number	Optional	The number of contacts to fetch. This can be a maximum of 1,000.
nextPageToken	String	Optional	Token to fetch the next page.

Create contacts

Sample Input Parameters: Create contacts

{
  "appId": "7aa6b29b-709d-4d65-b1ea-acc8793c3e9a",
  "contacts": [
    {
      "email": "[email protected]",
      "firstName": "David",
      "lastName": "Lyon",
      "customerContactId" : "EZ141",
      "productIds": [
        "a6ea7f7f-319b-4b97-ab6a-1544fe8e7e57",
        "26f4b204-fec5-47a8-a891-cbba18987ff1"
      ],
      "accountId": "EZ141",
      "role": "Lead Engineer",
      "countryCode": "+91",
      "phoneNumber": "6901313214",
      "uploadedImageUrl": "www.dummyurl.com/12-23.jpg"
    },
    {
      // "email": "[email protected]",
      "firstName": "Andrew",
      "lastName": "Shaw",
      "customerContactId" : "EZ143",
      "productIds": [
        "a6ea7f7f-319b-4b97-ab6a-1544fe8e7e57",
        "26f4b204-fec5-47a8-a891-cbba18987ff1"
      ],
      "accountId": "Hy169",
      "role": "Data Scientist",
      "countryCode": "+404",
      "phoneNumber": "345957392",
      "uploadedImageUrl": "www.dummyurl.com/21-4.jpg"
    }
  ]
}

Sample Output Parameters

{
    "Saved Contact count": 1,
    "Unsaved Contact count": 1,
    "unsavedContacts": [
        {
            "firstName": "Andrew",
            "lastName": "Shaw",
            "role": "Data Scientist",
            "phoneNumber": "345957392",
            "countryCode": "+404",
            "uploadedImageUrl": "www.dummyurl.com/21-4",
            "status": "active",
            "customerContactId": "EZ143",
            "displaySuggestion": true,
            "isChampion": false,
            "allValues": 1
        }
    ]
}

Endpoint

POST /tickets/contacts

Complete URL

https://api.smartkarrot.com/v4/tickets/contacts

Description

Export contacts from your database and store it into SmartKarrot’s contact database. This endpoint can be used to create or update multiple contacts at the same time.

Parameters

Parameter	Type	Required	Description
appId	String	Required	SmartKarrot’s App id
contacts	Contact	Required	List of contacts to save/modify

Contact has the following fields

Parameters

Parameter	Type	Required	Description
email(unique)	String	Required	Contact's email address
firstName	String	Required	Contact's first name
lastName	String	Optional	Contact's last name
customerContactId	String	Optional	Contact ID in your system
role	String	Optional	Contact's role/position
countryCode	String	Optional	Country code for phone number
phoneNumber	String	Optional	Contact's phone number
uploadedImageUrl	String	Optional	Contact's profile image url
accountId	String	Optional	The customer account ID in your system
productIds	String	Optional	You will get your product Ids from the Settings: Configure Products.

Response

Status	Description
Status	200
Description	Successfully saved the contacts

Save Agents

Sample Input Parameters: Save Agents

 {
   "appId": "7aa6b29b-709d-4d65-b1ea-acc8793c3e9a",
   "agents": [
    {
      "email": "[email protected]",
      "firstName": "Salman",
      "lastName": "Katamond",
      "customerAgentId" : "MK-agent003",
      "countryCode": "+404",
      "phoneNumber": "+606-303-21",
      "uploadedImageUrl": "www.dummyurl.com/12-23" 
    },
    {
      "firstName": "Mathew",
      "lastName": "Wade",
      //"email": "[email protected]",
      "customerAgentId" : "ZY-agent67",
      "phoneNumber": "+202-1212-12",
      "countryCode": "+44",
      "uploadedImageUrl": "www.34dummyurl.com/4.5"
    }
  ]
}

Sample Output Parameters

{
    " Saved Agents count: ": 1,
    " Unsaved Agents count: ": 1,
    "unsavedAgents": [
        {
            "firstName": "Mathew",
            "lastName": "Wade",
            "phoneNumber": "+202-1212-12",
            "countryCode": "+44",
            "customerAgentId": "ZY-agent67",
            "uploadedImageUrl": "www.34dummyurl.com/4.5",
            "allValues": 1
        }
    ]
}

Endpoint

POST /agents

Complete URL

https://api.smartkarrot.com/v4/agents

Description

Export agents from your database and store it into SmartKarrot’s agent database. This endpoint can be used to create or update multiple agents at the same time.

Parameters

Parameter	Type	Required	Description
appId	String	Required	SmartKarrot’s App id
agents	Agent	Required	List of agents to save or update

Agent has the following fields

Parameters

Parameter	Type	Required	Description
email(unique)	String	Required	Agent's email address
firstName	String	Required	Agent's first name
lastName	String	Optional	Agent's last name
customerAgentId	String	Optional	Agent's id in your system
countryCode	String	Optional	Country code for phone number
phoneNumber	String	Optional	Agent's phone number
uploadedImageUrl	String	Optional	Agent's profile image url

Response

Status	Description
Status	200
Description	Successfully saved the agents

Delete Agents

Sample Output Parameters: Delete Agents

{
    "Agent deleted"
}

Endpoint

DELETE /agents

Complete URL

https://api.smartkarrot.com/v4/agents

Description

Delete an agent from the SmartKarrot's agent database

Parameters

Parameter	Type	Required	Description
id	String	Required	Agent's UUID

Response

Status	Description
Status	200
Description	Successfully deleted the agent

Fetch Tickets

Sample Input Parameters

{  

    "appId" : "1d7b1062-106a-4f95-a136-a2eec114b6f0"
}

Sample output Parameters

{
  "count": 2,
  "tickets": [
    {
      "ticketId": "9d346f9f-c2b3-46ef-a64d-ca149facfcda",
      "visibleId": "532",
      "appId": "7aa6b29b-709d-4d65-b1ea-acc8793c3e9a",
      "accountId": "905d34b5-ab46-45f0-87b1-e5d9deb9dd1a",
      "ticketName": "mx-001",
      "createdBy": "8153a279-b7d5-4ee0-9cac-616bb7be37db",
      "createdByType": "agent",
      "escalation": "notEscalated",
      "assignedTo": "f6deca9f-f7a2-4487-8bd9-621f2bb225c8",
      "dueDate": "2021-01-18T04:34:29.795123Z",
      "priority": "high",
      "status": "resolved",
      "type": "customer query",
      "customFields": {
        "expiry": "none",
        "csm": "csm-2"
      },
      "createTime": "Jan 18, 2021 4:34:29 AM",
      "updateTime": "Feb 1, 2021 4:34:33 AM",
      "allValues": 1
    },
    {
      "ticketId": "72d4c1ea-a151-4beb-894e-0776ceb954c0",
      "visibleId": "965",
      "appId": "7aa6b29b-709d-4d65-b1ea-acc8793c3e9a",
      "accountId": "905d34b5-ab46-45f0-87b1-e5d9deb9dd1a",
      "ticketName": "mx-002",
      "createdBy": "8481a6f9-6990-4131-812a-bc6de2f14ccb",
      "createdByType": "contact",
      "escalation": "notEscalated",
      "assignedTo": "50a0347b-9f19-4283-a247-18450b87220a",
      "dueDate": "2021-01-18T04:34:29.794881Z",
      "priority": "medium",
      "status": "open",
      "type": "payment dashboard",
      "customFields": {
        "expiry": "none",
        "recheck": "enabled"
      },
      "createTime": "Jan 18, 2021 4:34:29 AM",
      "updateTime": "Feb 1, 2021 4:34:33 AM",
      "allValues": 1
    }
  ]
}

Endpoint

GET /tickets

Complete URL

https://api.smartkarrot.com/v4/tickets/{appId}

Description

This endpoint can be used to retrieve all the tickets associated with the app.

Parameters

Parameter	Type	Required	Description
appId	String	Required	SmartKarrot’s App id

Response

Status	Description
Status	200
Description	Successfully retrieved the tickets

Create a Ticket

Sample Input Parameters

{  

    "appId" : "1d7b1062-106a-4f95-a136-a2eec114b6f0",
    "visibleId" : "TicketMx-EOD41",
    "accountId" : "05b58b26-7647-4b90-abfc-2585c141c68a",
    "ticketName" : "Payment subdue",
    "createdBy" : "74f5c5a2-ffe0-403e-9384-06ad7396ce8e",
    "createdByType" : "contact",
    "dueDate" : "2022-08-09T11:19:42.12Z",
    "escalation" : "escalated",
    "priority" : "High",
    "status" : "Open",
    "productId":"26f4b204-fec5-47a8-a891-cbba18987ff1",
    "type" : "Payment iussue",
    "customFields" : {
        "expiry" : "none",
        "csm" : "Unassigned"

}
}

Sample Output Parameters

{

    "ticketId": "e7e8d69a-1412-400f-b3d5-749dd3e19720",
    "visibleId": "TicketMx-EOD41",
    "appId": "1d7b1062-106a-4f95-a136-a2eec114b6f0",
    "accountId": "05b58b26-7647-4b90-abfc-2585c141c68a",
    "ticketName": "Payment subdue",
    "isDescriptionSaved": false,
    "createdBy": "74f5c5a2-ffe0-403e-9384-06ad7396ce8e",
    "createdByType": "contact",
    "escalation": "escalated",
    "dueDate": "2022-08-09T11:19:42.120Z",
    "priority": "High",
    "status": "Open",
    "type": "Payment iussue",
    "customFields": {
        "expiry": "none",
        "csm": "Unassigned"
    },
    "productId": "26f4b204-fec5-47a8-a891-cbba18987ff1"

}

Endpoint

POST /tickets

Complete URL

https://api.smartkarrot.com/v4/tickets

Description

This endpoint can be used to create a ticket .

Parameters

Parameter	Type	Required	Description
appId	String	Required	SmartKarrot's App id
visibleId	String	Optional	Client's own ticket id
accountId	String	Required	Customer account id
ticketName	String	Optional	Name of the ticket
createdBy	String	Required	Creator's id
createdByType	String	Optional	Enum: agent, contact
assignedTo	String	Optional	Agent's id to whom ticket is assigned.
dueDate	String	Optional	Due date for the ticket
escalation	String	Optional	Enum: escalated, notEscalated
priority	String	Optional	Priority of the ticket
status	String	Optional	Status of the ticket
type	String	Optional	Type of the ticket
customFields	Map	Optional	A key value pair to store other additional fields for the ticket
productId	String	Optional	You will get your product Ids from the Settings: Configure Products..

Response

Status	Description
Status	201
Description	Successfully created the ticket

Update a Ticket

Sample Input Parameters

{
    "id" : "72d4c1ea-a151-4beb-894e-0776ceb954c0",
    "visbleId" : "EZ1014a",
    "accountId" : "b6a96d3d-1253-4fee-ba0d-80dddf01c09b",
    "assignedTo" : "0ee3cc23-20af-4f90-9c1f-802e8f59346",
    "ticketName" :"Payment subdue",
    "dueDate" : "2021-01-12T14:48:00.000Z",
    "priority" : "High",
    "createByType" : "agent ",
    "status" : "closed",
    "escalation" : "escalated",
    "type" : "Payment query",
    "customFields" : {
        "key1" :"value1",
        "key2" : "value2"
    }
}

Sample Output Parameters

{
    "ticketId": "72d4c1ea-a151-4beb-894e-0776ceb954c0",
    "visibleId": "965",
    "appId": "7aa6b29b-709d-4d65-b1ea-acc8793c3e9a",
    "accountId": "905d34b5-ab46-45f0-87b1-e5d9deb9dd1a",
    "ticketName": "ticket101",
    "createdBy": "8481a6f9-6990-4131-812a-bc6de2f14ccb",
    "createdByType": "contact",
    "escalation": "escalated",
    "dueDate": "2021-01-18T04:34:29.794881Z",
    "priority": "High",
    "status": "closed",
    "type": "Payment query",
    "customFields": {
        "key1": "value1",
        "key2": "value2"
    },
    "createTime": "Jan 18, 2021 4:34:29 AM",
    "updateTime": "Feb 1, 2021 12:11:03 PM",
    "version": 3,
    "allValues": 1
}

Endpoint

PUT /tickets/{id}

Complete URL

https://api.smartkarrot.com/v4/tickets/{id}

Description

This endpoint can be used to update an existing ticket.

Parameters

Parameter	Type	Required	Description
id	String	Required	Ticket's unique id
visibleId	String	Optional	Client's own ticket id
accountId	String	Optional	Customer account id
ticketName	String	Optional	Name of the ticket
assignedTo	String	Optional	Agent's id to whom ticket is assigned.
dueDate	String	Optional	Due date for the ticket
escalation	String	Optional	Enum: escalated, notEscalated
priority	String	Optional	Priority of the ticket
status	String	Optional	Status of the ticket
type	String	Optional	Type of the ticket
customFields	Map	Optional	A key value pair to store other additional fields for the ticket

Response

Status	Description
Status	200
Description	Successfully updated the ticket

Delete a Ticket

Sample Input Parameters

{  

    "appId" : "1d7b1062-106a-4f95-a136-a2eec114b6f0"
}

Sample Output Parameters

{
    "message": "Ticket deleted"
}

Endpoint

DELETE /tickets/{id}

Complete URL

https://api.smartkarrot.com/v4/tickets/{id}

Description

This endpoint can be used to delete a tickets .

Parameters

Parameter	Type	Required	Description
id	String	Required	Ticket's id that needs to be deleted

Response

Status	Description
Status	200
Description	Successfully deleted the ticket

Fetch Ticket Comments

Sample Input Parameters

{
    "id":"d02f2965-5dc1-4ba9-861f-b11a6a309e81",
    "ticketId" : "hit0-gtnttjt-ntjgbt-598jtnbt"
}

Sample output Parameters

{
    "count": 2,
    "comments": [
        {
            "CommentId": "d02f2965-5dc1-4ba9-861f-b11a6a309e81",
            "ticketId": "a10525ae-5805-4cc3-98f8-6291540ef02f",
            "description": "Pospone the date for meet if possible.",
            "createdByType": "agent",
            "createdById" :  "b5982819-3c9d-4b61-9e07-5b8fa3cf09a5",
            "createTime": "Feb 1, 2021 9:37:32 AM",
            "updateTime": "Feb 1, 2021 9:37:32 AM",
            "version": 1,
            "allValues": 1
        },
        {
            "CommentId": "fe0ed6ec-2e76-4637-aa91-2f6badddcaa3",
            "ticketId": "a10525ae-5805-4cc3-98f8-6291540ef02f",
            "description": "Sure, will ask Dev about the same.",
            "createdByType": "contact",
            "createdById" :  "ce343da7-2287-49c3-b4a6-b06b97e69a43",
            "createTime": "Feb 1, 2021 9:38:50 AM",
            "updateTime": "Feb 1, 2021 9:38:50 AM",
            "version": 1,
            "allValues": 1
        }

Endpoint

GET /tickets/comments

Complete URL

https://api.smartkarrot.com/v4/tickets/comments

Description

This endpoint can be used to retrieve all the comments associated with a ticket.

Parameters

Parameter	Type	Required	Description
appId	String	Required	SmartKarrot’s App id
ticketId	String	Required	Ticket id

Response

Status	Description
Status	200
Description	Successfully retrieved the comments of the ticket

Create a Ticket Comment

Sample Input Parameters

{
  "ticketId" : "9c68623f-7340-456b-a272-29c741c31a43",
  "description" : "version 3.0 to be released for the beta clients",
  "createdByType" : "agent",
  "createdBy" :"50a0347b-9f19-4283-a247-18450b87220a"
  }

Sample Output Parameters

{
    "CommentId": "8a26114e-098c-4652-8889-a823e349580c",
    "ticketId": "9c68623f-7340-456b-a272-29c741c31a43",
    "description": "version 3.0 to be released for the beta clients",
    "createdBy": "50a0347b-9f19-4283-a247-18450b87220a",
    "createdByType": "agent",
    "createTime": "Feb 1, 2021 8:05:49 PM",
    "updateTime": "Feb 1, 2021 8:05:49 PM",
    "version": 1,
    "allValues": 1
}

Endpoint

POST /tickets/comments

Complete URL

https://api.smartkarrot.com/v4/tickets/comments

Description

This endpoint can be used to create a comment for a ticket with a data block containing the fields you’d like to set on the comment. Any unspecified fields will not be added to the comment .

Parameters

Parameter	Type	Required	Description
ticketId	String	Required	Ticket id of the ticket to contain the comment.
description	String	Required	decription of the comment
createdBy	String	Optional	Creator's id
createdByType	String	Optional	Enum: agent, contact

Response

Status	Description
Status	201
Description	Successfully created the comment

Edit a ticket comment

Sample Input Parameters

{
    "id":"d02f2965-5dc1-4ba9-861f-b11a6a309e81",
    "description" : "The progress on usage analytics is steady."
}

Sample Output Parameters

{
    "CommentId": "d02f2965-5dc1-4ba9-861f-b11a6a309e81",
    "ticketId": "a10525ae-5805-4cc3-98f8-6291540ef02f",
    "description": "The progress on usage analytics is steady.",
    "createTime": "Feb 1, 2021 9:37:32 AM",
    "updateTime": "Feb 1, 2021 8:03:03 PM",
    "version": 2,
    "allValues": 1
}

Endpoint

PUT /tickets/comments

Complete URL

https://api.smartkarrot.com/v4/tickets/comments

Description

This endpoint can be used to update an existing comment on a ticket. Only the fields provided in the data block will be updated; any unspecified fields will remain unchanged

Parameters

Parameter	Type	Required	Description
id	String	Required	Comment's unique id
description	String	Required	updated description for the comment

Response

Status	Description
Status	200
Description	Successfully updated the comment