Documentation > API

Working with Events API

Download Events

CleverTap enables developers to download Events using the below documented API

Understanding Events paging request and response

To support efficient batching and pagination of large record sets, accessing user event records via the Server API is a multi-request process.

With your first request you will specify a JSON formatted query for records as POST payload, and a batch_size URL query parameter, specifying the number of records to be returned per request, along with your CleverTap Account ID and CleverTap Account Passcode in the request headers.

The response to this initial query request will return a cursor, which you will then append to the URL query in subsequent requests to fetch the actual record set paginated by the batch_size you specify.

Each response of records using that cursor will return a next_cursor to fetch the subsequent set of records. Once there are no more records to be fetched, the next_cursor key will no longer be returned.

In this regard, it may be helpful to think of the cursor as something akin to a database cursor.

Request Authentication

Every request to the API should include your CleverTap Account ID and CleverTap Account Passcode in the request header keyed with X-CleverTap-Account-Id and X-CleverTap-Passcode, respectively.
Content-Type header must be specified as application/json.

Initial Endpoint For Cursor

The cursor request to download events is an HTTP URL of the following form:

POST https://api.clevertap.com/1/events.json?batch_size=5000

Note:Maximum batch_size is 5000, this will return 5000 records per request.

Payload

JSON formatted request with the following parameters

Required Parameters

event_name – The name of the event which has been performed by the users whose events you want to download

from & to – Date range within which users should have performed the event you have specified in event_name , input values have to be formatted as integers in format YYYYMMDD

Optional Parameters

Refer here for documentation on advanced queries, their structure, and examples.

Notification Sent event is not supported for event export API. You can obtain information about users receiving a particular notification using the profile download API.

Example Payload

{
    "event_name": "choseNewFavoriteFood",
    "event_properties": [
        {
            "name": "value",
            "operator": "contains",
            "value": "piz"
        }
    ],
    "from": 20150810,
    "to": 20151025
}
copy Copied

Response

{
    "status": "success",
    "cursor": "ZiZiNwMEBQBkaWZzY2MuO20BBQFlYmN7ZG5hewYBTQVjb2BzZmphfwEABQUra2Jmeg%3D%3D"
}
copy Copied

Endpoint For Subsequent Records

To download subsequent requests you have to use the endpoint documented below while keeping the CleverTap authentication headers in place:

GET https://api.clevertap.com/1/events.json?cursor=ZiZiNwMEBQBkaWZzY2MuO20BBQFlYmN7ZG5hewYBTQVjb2BzZmphfwEABQUra2Jmeg%3D%3D

app=true request parameter can be passed to receive app fields in response (os_version, app_version, make (device make), model (device model) within the profile object)

profile=true request parameter must be passed to receive custom profile fields in response (profileData within the profile object)

Response

{
    "status": "success",
    "previous_cursor": "ZyZjfwYEAgdjYmZyKz8NegYFAwxmamF/Z21meU4BBQFlYmN7ZG5ifAYCTQQrai57K2ouegJMARl6",
    "next_cursor": "ZyZjfwYEAgdjYmZyKz8NegYFAwxmamF%2FZ21meU4BBQFlYmN7ZG5ifAYCTQQrai57K2ouegJMABl6",
    "records": [
        {
            "profile": {
                "objectId": "a8ffcbc9-a747-4ee3-a791-c5e58ad03097",
                "platform": "Web",
                "email": "peter@foo.com",
                "profileData": {
                    "favoriteColor": "blue"
                },
                "identity": "5555555555",
                "id": 33
            },
            "ts": 20151023140416,   // yyyyMMddHHmmSS format
            "event_props": {
                "value": "pizza"
            },
            "session_props": {
                "utm_source": "Foo",
                "utm_medium": "Bar",
                "utm_campaign": "FooBar",
                "session_source": "Direct"
            }
        },
        {
            "profile": {
                "objectId": "a8ffcbc9-a747-4ee3-a791-c5e58ad03097",
                "platform": "Web",
                "email": "peter@foo.com",
                "profileData": {
                    "favoriteColor": "blue"
                },
                "identity": "5555555555",
                "id": 33
            },
            "ts": 20151024121636,
            "event_props": {
                "value": "pizza"
            },
            "session_props": {
                "session_source": "Others",
                "session_referrer": "http://example.com"
            }
        }
    ]
}
copy Copied

The table below highlights the various keys you see in the response above –

Key Description
objectId CleverTap ID of user
profileData All custom profile properties of user
identity Custom user identity provided by you
ts Event timestamp, in yyyyMMddHHmmSS format
event_props All event properties and their values
session_props Session properties utm_source, utm_medium, utm_campaign, session_source and session_referrer for the event, if they were set
session_source Possible source values are Direct, Search, Social, Email & Batch. If unset, the source is UnAvailable, and Others if there is a custom referrer (session_referrer field contains the referrer value if source is Others)

Please refer here for explanation regarding session properties and their possible values.

Upload Events

CleverTap enables developers to upload Events using the below documented API request

Endpoint

A request to upload Event information is an HTTP URL of the following form:

POST https://api.clevertap.com/1/upload

Authentication

All requests should include your CleverTap Account ID and CleverTap Account Passcode in the request headers keyed with X-CleverTap-Account-Id and X-CleverTap-Passcode, respectively.
Content-Type header must be specified as application/json.

Payload

JSON formatted payload with Content-Type: application/json header and a JSON object keyed with d whose value is an Array container of JSON data records, and then JSON-encoded, e.g. {"d":JSON-encoded data} with the following keys:

Required parameters

type – set to event for updating an Events. Must be String

evtName – name of the Event

evtData – JSON keys and values to be updated. See example payload below

One of the following identity parameters are required

identity – identity to recognize a user uniquely. It can be the user’s email id, a phone number or any other identifier that you are using to tag your users. This is the key that will be looked up to find the user whose profile needs to be updated. If this identity is not found a new user profile will be created. Must be String

FBID – Can be used to identify a unique user by his/her Facebook ID. Must be String

GPID – Can be used to identify a unique user by his Google Plus ID. Must be String

objectId – Can be used to identify a unique user by their CleverTap Global Object ID. Must be String

Optional parameters

ts – date and time when the event was originally performed, formatted as a UNIX epoch. Defaults to current timestamp if omitted. Must be Integer

Example payload

In the below sample, there are two events being uploaded
1. A user who is identified by his/her Facebook ID and performed a Product viewed event
2. A user who is identified by his/her email ID and performed a Charged event

{
    "d": [
        {
            "FBID": "34322423",
            "ts": 1468308340, // time when the event occurred
            "type": "event",
            "evtName": "Product viewed",
            "evtData": {
                "Product name": "Casio Chronograph Watch",
                "Category": "Mens Watch",
                "Price": 59.99,
                "Currency": "USD"
            }
        },
        {
            "identity": "jack@gmail.com",
            "ts": 1468208340, // time when the event occurred
            "type": "event",
            "evtName": "Charged",
            "evtData": {
                "Amount": 300,
                "Currency": "USD",
                "Payment mode": "Credit Card",
                "Delivery By": "$D_1468322268",      // UNIX epoch timestamp with $D_ prefix for recording date properties (string)
                "Items": [
                    {
                        "Category": "books",
                        "Book name": "The millionaire next door",
                        "Quantity": 1
                    },
                    {
                        "Category": "books",
                        "Book name": "Achieving inner zen",
                        "Quantity": 4
                    }
                ]
            }
        }
    ]
}
copy Copied

Example response format

{
    "status":<success, partial, fail>, 
    "processed":<count>, 
    "unprocessed": [{"status":"fail", "code":<error code>, "error":<error msg>, "record":<record>}]
}
copy Copied

Example response

{
    "status": "success",
    "processed": 2,
    "unprocessed": []
}
copy Copied

Error codes

509 Event name mandatory
512 Invalid event structure
513 Raised a restricted system event
522 Event properties limit exceeded
523 Missing identity
524 Data neither event nor profile
525 Timestamp not in UNIX epoch format
526 objectId invalid
555 Miscellaneous server error

Additional error codes limited to download API
1 Too many requests were made concurrently
2 Request still in progress, please retry later

HTTP Response Codes

200 Successful request
400 Bad Request. Some mandatory parameter was missing
429 Too many requests were made concurrently.
500 Server Error
Currently, we return 429 when you make more than 3 concurrent requests. Please try again after 10 minutes

Debugging

  • Records with errors in processing will be sent back along with the response of the HTTP request
  • To test whether data submitted is without errors, you can add the parameter dryRun=1 to the URL. This will validate the input without submitting the data to CleverTap

Data Validation

  • The maximum number of event types per account is 150. The number of events submitted per account across those event types is unlimited
  • Notification Sent, Notification Viewed, Notification Clicked, UTM Visited, App Launched, App Uninstalled, and Stayed are reserved event names
  • For the Charged event, its value object may optionally contain a nested array element called Items which may further contain value objects. The Items array is limited to 16 elements.
  • For each event type, the maximum number of properties is 16
  • Restricted characters in event and property names are : dot(.), colon(;), dollar sign($), single quote('), double quote("), and backslash(\)
  • Event keys are limited to 32 characters and property values are limited to 40 bytes
  • Events are query-able for period of 365 days

Limitations and Constraints

Maximum 1000 records may be sent per API call. The calls to the endpoint are synchronous. We recommend you make a single call from your server at a time, wait for the response before making another API request

Concurrent requests are limited to 3 per account. Requests that exceed the limit will return a 429 HTTP response code