Upload Events

Overview

The Upload Events API provides you with the capability to upload user events to CleverTap. For example, you can use this API to store user events, such as product views and purchases. You associate these events with a specific user by using an identifier, such as an email address or a phone number. By storing user events in CleverTap, you can create richer segments and run targeted campaigns.

Uploading events to CleverTap requires a POST request with a JSON payload specifying the event information. A maximum of 1000 event records can be sent per API call.

While the maximum number of event types per account is 512, some events are reserved for system events, so you may not get to use all of them. For each event, the maximum number of properties is 100 by default, and this limit is configurable per account. The number of events submitted per account across those event types is unlimited.

For more information on request limits, refer to API Request Limit.

Base URL

The following is a sample base URL:

https://<region>.api.clevertap.com/1/upload

For region-specific endpoints, refer to Region.

HTTP Method

POST

Headers

Refer to Headers for more details.

Body Parameters

Events are uploaded as a JSON payload. The payload is an object keyed with "d" whose value is an array describing the event, including the event name, event properties, timestamp, and user identifier.

Event keys are limited to 1024 characters. Property values are validated up to 1024 characters at upload time.

For each event, a user identifier is required. This is the key that CleverTap uses to find the user whose profile needs to be updated. You have to set a value for one of these parameters to identify the user: identity, FBID, GPID, or objectId. If this identity is not found, a new user profile is created.

The following table lists the body parameters:

ParameterDescriptionTypeExample Value
type(Required) Set to event.string"event"
evtName(Required) Name of event.string"Product Viewed"
evtData(Optional) Event properties describing the event. Passed as key/value pairs. If omitted or empty, the record is still processed.object"evtData":
{ "Product name": "Casio Watch", "Category": "Mens Watch" }
ts(Optional) Date and time when the event occurred, formatted as a UNIX epoch in seconds. Defaults to the current timestamp if omitted.integer1468308340
identityIdentity to recognize a unique user. It can be the user's email, a phone number, or any other identifier you are using to tag your users.
You have to set a value for one of these parameters to identify the user: identity, FBID, GPID, or objectId.
string"[email protected]"
FBID

Identify a unique user by Facebook ID.

You have to set a value for one of these parameters to identify the user: identity, FBID, GPID, or objectId.

string"34322423"
GPID

Identify a unique user by Google Plus ID.

You have to set a value for one of these parameters to identify the user: identity, FBID, GPID, or objectId.

string"34322424"
objectId

Identify a unique user by CleverTap Global Object ID.

You have to set a value for one of these parameters to identify the user: identity, FBID, GPID, or objectId.

string"34322425"

Example Request

The following is a sample request:

curl -X POST -d '{ "d": [ { "FBID": "34322423", "ts": 1468308340, "type": "event", "evtName": "Product viewed", "evtData": { "Product name": "Casio Chronograph Watch", "Category": "Mens Watch", "Price": 59.99, "Currency": "USD" } } ] }' "https://<region>.api.clevertap.com/1/upload" \
-H "X-CleverTap-Account-Id: ACCOUNT_ID" \
-H "X-CleverTap-Passcode: PASSCODE" \
-H "Content-Type: application/json; charset=utf-8"
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://<region>.api.clevertap.com/1/upload")
request = Net::HTTP::Post.new(uri)
request.content_type = "application/json; charset=utf-8"
request["X-Clevertap-Account-Id"] = "ACCOUNT_ID"
request["X-Clevertap-Passcode"] = "PASSCODE"
request.body = JSON.dump({
  "d" => [
    {
      "FBID" => "34322423",
      "ts" => 1468308340,
      "type" => "event",
      "evtName" => "Product viewed",
      "evtData" => {
        "Product name" => "Casio Chronograph Watch",
        "Category" => "Mens Watch",
        "Price" => 59.99,
        "Currency" => "USD"
      }
    }
  ]
})

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'X-CleverTap-Account-Id': 'ACCOUNT_ID',
    'X-CleverTap-Passcode': 'PASSCODE',
    'Content-Type': 'application/json; charset=utf-8',
}

data = '{ "d": [ { "FBID": "34322423", "ts": 1468308340, "type": "event", "evtName": "Product viewed", "evtData": { "Product name": "Casio Chronograph Watch", "Category": "Mens Watch", "Price": 59.99, "Currency": "USD" } } ] }'

response = requests.post('https://<region>.api.clevertap.com/1/upload', headers=headers, data=data)
<?php
include('vendor/rmccue/requests/library/Requests.php');
Requests::register_autoloader();
$headers = array(
    'X-CleverTap-Account-Id' => 'ACCOUNT_ID',
    'X-CleverTap-Passcode' => 'PASSCODE',
    'Content-Type' => 'application/json; charset=utf-8'
);
$data = '{ "d": [ { "FBID": "34322423", "ts": 1468308340, "type": "event", "evtName": "Product viewed", "evtData": { "Product name": "Casio Chronograph Watch", "Category": "Mens Watch", "Price": 59.99, "Currency": "USD" } } ] }';
$response = Requests::post('https://<region>.api.clevertap.com/1/upload', $headers, $data);
var request = require('request');

var headers = {
    'X-CleverTap-Account-Id': 'ACCOUNT_ID',
    'X-CleverTap-Passcode': 'PASSCODE',
    'Content-Type': 'application/json; charset=utf-8'
};

var dataString = '{ "d": [ { "FBID": "34322423", "ts": 1468308340, "type": "event", "evtName": "Product viewed", "evtData": { "Product name": "Casio Chronograph Watch", "Category": "Mens Watch", "Price": 59.99, "Currency": "USD" } } ] }';

var options = {
    url: 'https://<region>.api.clevertap.com/1/upload',
    method: 'POST',
    headers: headers,
    body: dataString
};

function callback(error, response, body) {
    if (!error && response.statusCode == 200) {
        console.log(body);
    }
}

request(options, callback);

Example Payload

The following is a sample JSON payload:

{
    "d": [
        {
            "FBID": "34322423",
            "ts": 1468308340, // time when the event occurred in UNIX epoch value in seconds
            "type": "event",
            "evtName": "Product viewed",
            "evtData": {
                "Product name": "Casio Chronograph Watch",
                "Category": "Mens Watch",
                "Price": 59.99,
                "Currency": "USD"
            }
        },
        {
            "identity": "[email protected]",
            "ts": 1468208340,
            "type": "event",
            "evtName": "Charged",
            "evtData": {
                "Amount": 300,
                "Currency": "USD",
                "Payment mode": "Credit Card",
                "Delivery By": "$D_1468322268",     
                "Items": [
                    {
                        "Category": "books",
                        "Book name": "The millionaire next door",
                        "Quantity": 1
                    },
                    {
                        "Category": "books",
                        "Book name": "Achieving inner zen",
                        "Quantity": 4
                    }
                ]
            }
        }
    ]
}

Only the Items array in Charged events accepts a nested structure.

Example Response

The following is a sample response:

{
    "status": "success",
    "processed": 1,
    "unprocessed": []
}

Debugging

Requests with processing errors are returned in the API call response, as shown in the example below.

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

To test if your data submits without errors, you can add the parameter dryRun=1 to the URL. This validates the input without submitting the data to CleverTap.

Error Codes

The following table lists the error codes returned by this API:

HTTP-Level Errors (whole request rejected)

HTTP StatusCode or StatusErrorDescriptionExample Error Response
400failPayload is mandatoryRequest body is absent or empty{"status":"fail","error":"Payload is mandatory"}
400failMalformed requestRequest body is not valid JSON{"status":"fail","error":"Malformed request"}
400failBatch size exceededPayload contains more than 1000 records{"status":"fail","error":"Batch size exceeded"}
401failInvalid CredentialsAccount-Id or Passcode header value is incorrect{"status":"fail","error":"Invalid Credentials"}
503fail12-digit account ID mandatory.Account-Id header is missing{"status":"fail","error":"12 digit account ID mandatory."}
503failPlease come back laterService is not ready; retry the request{"status":"fail","error":"Please come back later"}

Record-Level Errors (HTTP 200, individual records in unprocessed array)

CodeErrorDescription
509Event name is mandatoryevtName field is absent or empty
512Only Items can have a nested structureA non-Items field in a non-Charged event contains a nested object or array
513Trying to raise a restricted system eventevtName matches a reserved system event (for example, Notification Sent, App Launched)
515Email is not validProfile email field is malformed
516Phone number is not validProfile phone is not in +(digits) format
517Employed needs to be Y/NProfile Employed field is not Y or N
518Education needs to be School/College/Graduate.Profile Education field has an invalid value
519Married needs to be Y/NProfile Married field is not Y or N
520Age is invalidProfile Age is not a number between 0 and 120
522Cannot have more than n properties.evtData exceeds the property limit (default 100)
523'identity' or 'fbId' or 'gpId' or 'objectId' is necessary...No valid user identifier found in the record
524Data is not of type Event, Profile, or Tokentype field is absent or has an unrecognized value
525The timestamp should be in Unix Epoch format...ts is zero, in milliseconds, or not parseable as a Long
527The record is too old. Please use the historic batch upload APIts is older than the allowed ingestion window
528Trying to raise a discarded eventEvent name is on the account's discard list
530Invalid 'objectId'Token upload attempted without a valid objectId
531Invalid token data.tokenData is absent or has fewer than 2 fields
532Token 'id' is not present.tokenData.id is missing
533Token 'type' is not present.tokenData.type is missing
534Token 'type' is not valid for 'objectId'.Token type does not match the device type of the objectId
536Invalid Name update operationProfile Name field contains an unsupported operation
537Invalid gender update operationProfile Gender field contains an unsupported operation
555ErrorUnhandled exception during record processing

Notes

  • You can also use the Data Upload Script to upload the event data to the CleverTap dashboard.
  • A list of error codes for this API can be found on the Errors page.

To understand common queries and concerns about CleverTap APIs, refer to API FAQs.


CleverTap Ask AI Widget (CSP-Safe)