Upload Events API
The Upload Events API provides you 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.
Overview
Uploading events to CleverTap requires a POST request with a JSON payload specifying the event information. 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 type, the maximum number of properties is 256. The number of events submitted per account across those event types is unlimited.
Base URL
https://location.api.clevertap.com/1/upload
HTTP Method
POST
Headers
These headers are all required. The X-CleverTap-Account-Id and X-CleverTap-Passcode are used to authenticate the request. To view how to get their values, refer to the Authentication guide.
Header | Description | Type | Example Value |
---|---|---|---|
X-CleverTap-Account-Id | Your CleverTap Account ID. | string | "X-CleverTap-Account-Id: ACCOUNT_ID" |
X-CleverTap-Passcode | Your CleverTap Account Passcode. | string | "X-CleverTap-Passcode: PASSCODE" |
Content-Type | Request content-type is always set to application/json; charset=utf-8. | string | "Content-Type: application/json; charset=utf-8" |
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 120 characters and property values are limited to 512 bytes.
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 will be created.
Parameter | Description | Type | Example Value |
---|---|---|---|
type | (Required) Set to event. | string | "event" |
evtName | (Required) Name of event. | string | âProduct Viewedâ |
evtData | (Required) Event properties describing the event. Passed as key/value pairs. | object | "evtData": |
ts | (Optional) Date and time when the event occured, Formatted as a UNIX epoch in seconds. The format | ts | 1468308340 |
identity | Identity 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. | 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" |
Here is an example 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
}
]
}
}
]
}
Example 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://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://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://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://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://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 Response
{
"status": "success",
"processed": 1,
"unprocessed": []
}
Debugging
Requests with processing errors will be 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 will be submitted without errors, you can add the parameter dryRun=1 to the URL. This will validate the input without submitting the data to CleverTap.
A list of errors code for this API can be found on the Errors page.
Updated 2 months ago