Get User Profiles
Overview
There are two ways to get user profiles. The first way is to download user profiles that have performed a specific event. For example, you can download a list of users that have launched your app in the past day. The second way to download user profiles is by requesting the specific users needed. The Get User Profiles API lets you download user profiles from CleverTap.
Get User Profiles by Events
Getting a list of user-profiles by events requires two steps:
- With your first API call, specify the event name, date range, and batch size needed. This request returns a cursor you will use to get the list of user profile records in the Get User Profiles Using Cursor section.
- Make a second API call using the cursor from the Get Cursor by Specifying Events for User Profiles section. This call returns the first batch of user-profiles and another cursor to get the second batch of user profiles. You repeat this process until the cursor is not returned in the response, which means there are no more matching user profiles.
Batch Size
The batch size denotes the maximum number of records that can be fetched in a single call. The batch size should be provided in multiples of 23 (23, 46, 69....) as there is a total of 23 memory buckets available in CleverTap's data storage mechanism.
Get Cursor by Specifying Events for User Profiles
In this request, you specify the event name, date range, and batch size needed. This request returns a cursor, which you will use to get the list of user profiles in the Get User Profiles Using Cursor section.
Base URL
Here is an example base URL from the account in the India region:
https://in1.api.clevertap.com/1/profiles.json
Region
Refer Region for more details.
HTTP Method
POST
Headers
Refer Headers for more details.
URL Parameter
Parameter | Description | Type | Example Value |
---|---|---|---|
batch_size | The number of results to return in each API call. The maximum is 5000. | int | 50 |
app | Optional parameter. Set to true to receive app fields in the response This will return the OS version, device make, device model, app version within the profile object. | boolean | true |
events | Optional parameter. Includes the event summary fields in the response. The default value is true. Set to false to exclude event summary fields in the response. | boolean | true |
profile | Optional parameter. Includes the custom profile properties in the response. The default value is true. Set to false to exclude custom profile properties fields in the response. | boolean | true |
Body Parameters
Parameter | Description | Type | Example Value |
---|---|---|---|
event_name | The event type needed. You can get both standard and custom events from this endpoint. The standard events include App Launched, App Installed, App Uninstalled, Charged, Notification Viewed, Notification Sent, Product Viewed, and UTM Visited. | string | “App Launched” |
from | Start of date range for events needed. Value specified in format YYYYMMDD. | int | 20171201 |
to | End of date range for events needed. Value specified in format YYYYMMDD. | int | 20171225 |
Example Request
Here is an example cURL request to the Get User Profiles API showing the headers needed to authenticate the request from the account in the India region:
curl -X POST -d '{"event_name":"App Launched","from":20171201,"to":20171225}' "https://in1.api.clevertap.com/1/profiles.json?batch_size=50" \
-H "X-CleverTap-Account-Id: ACCOUNT_ID" \
-H "X-CleverTap-Passcode: PASSCODE" \
-H "Content-Type: application/json"
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://in1.api.clevertap.com/1/profiles.json?batch_size=50")
request = Net::HTTP::Post.new(uri)
request.content_type = "application/json"
request["X-Clevertap-Account-Id"] = "ACCOUNT_ID"
request["X-Clevertap-Passcode"] = "PASSCODE"
request.body = JSON.dump({
"event_name" => "App Launched",
"from" => 20171201,
"to" => 20171225
})
req_options = {
use_ssl: uri.scheme == "https",
}
response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
http.request(request)
end
# Recommended python version 2.7
import requests
headers = {
'X-CleverTap-Account-Id': 'ACCOUNT_ID',
'X-CleverTap-Passcode': 'PASSCODE',
'Content-Type': 'application/json',
}
params = (
('batch_size', '50'),
)
data = '{"event_name":"App Launched","from":20171201,"to":20171225}'
response = requests.post('https://in1.api.clevertap.com/1/profiles.json', headers=headers, params=params, 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'
);
$data = '{"event_name":"App Launched","from":20171201,"to":20171225}';
$response = Requests::post('https://in1.api.clevertap.com/1/profiles.json?batch_size=50', $headers, $data);
var request = require('request');
var headers = {
'X-CleverTap-Account-Id': 'ACCOUNT_ID',
'X-CleverTap-Passcode': 'PASSCODE',
'Content-Type': 'application/json'
};
var dataString = '{"event_name":"App Launched","from":20171201,"to":20171225}';
var options = {
url: 'https://in1.api.clevertap.com/1/profiles.json?batch_size=50',
method: 'POST',
headers: headers,
body: dataString
};
function callback(error, response, body) {
if (!error && response.statusCode == 200) {
console.log(body);
}
}
request(options, callback);
type Payload struct {
EventName string `json:"event_name"`
From int `json:"from"`
To int `json:"to"`
}
data := Payload{
// fill struct
}
payloadBytes, err := json.Marshal(data)
if err != nil {
// handle err
}
body := bytes.NewReader(payloadBytes)
req, err := http.NewRequest("POST", "https://in1.api.clevertap.com/1/profiles.json?batch_size=50", body)
if err != nil {
// handle err
}
req.Header.Set("X-Clevertap-Account-Id", "ACCOUNT_ID")
req.Header.Set("X-Clevertap-Passcode", "PASSCODE")
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
// handle err
}
defer resp.Body.Close()
Example Response
{
"cursor":"AfljfgIJBgBnamF5Kz8NegcBAwxhbCe%2Fbmhhe04BBAVlYjT4YG5reQEATQQrai57K2oue04FAUhnd38%3D",
"status":"success"
}
Get User Profiles Using Cursor
Using the cursor from the Get Cursor by Specifying Events for User Profiles section, you will make an API call that returns the first batch of user profiles and another cursor to get the second batch of user profiles. Repeat this process until a cursor is not returned in the response, which means there are no more matching user profiles.
Base URL
Here is an example base URL from the account in the India region:
https://api.clevertap.com/1/profiles.json
To know the API endpoint for your account, refer to Region.
HTTP Method
GET
Headers
Refer Headers for more details.
URL Parameter
Parameter | Description | Type | Example Value |
---|---|---|---|
cursor | Required parameter. Specifies what set of user profiles to return. | string | ZyZjfwYEAgdjYmZyKz8NegYFAwxmamF%2FZ21meU4BBQFlYmN7ZG5ifAYCTQQrai57K2ouegJMABl6 |
Example Request
Here is an example cURL request to the Get User Profiles Using Cursor API showing the headers needed to authenticate the request from the account in the India region:
curl "https://in1.api.clevertap.com/1/profiles.json?cursor=CURSOR" \
-H "X-CleverTap-Account-Id: ACCOUNT_ID" \
-H "X-CleverTap-Passcode: PASSCODE" \
-H "Content-Type: application/json"
require 'net/http'
require 'uri'
uri = URI.parse("https://api.clevertap.com/1/profiles.json?cursor=CURSOR")
request = Net::HTTP::Get.new(uri)
request.content_type = "application/json"
request["X-Clevertap-Account-Id"] = "ACCOUNT_ID"
request["X-Clevertap-Passcode"] = "PASSCODE"
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',
}
params = (
('cursor', 'CURSOR'),
)
response = requests.get('https://api.clevertap.com/1/profiles.json', headers=headers, params=params)
<?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'
);
$response = Requests::get('https://api.clevertap.com/1/profiles.json?cursor=CURSOR', $headers);
var request = require('request');
var headers = {
'X-CleverTap-Account-Id': 'ACCOUNT_ID',
'X-CleverTap-Passcode': 'PASSCODE',
'Content-Type': 'application/json'
};
var options = {
url: 'https://api.clevertap.com/1/profiles.json?cursor=CURSOR',
headers: headers
};
function callback(error, response, body) {
if (!error && response.statusCode == 200) {
console.log(body);
}
}
request(options, callback);
req, err := http.NewRequest("GET", "https://api.clevertap.com/1/profiles.json?cursor=CURSOR", nil)
if err != nil {
// handle err
}
req.Header.Set("X-Clevertap-Account-Id", "ACCOUNT_ID")
req.Header.Set("X-Clevertap-Passcode", "PASSCODE")
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
// handle err
}
defer resp.Body.Close()
Example Response
If there are more user profiles available, next_cursor will be returned. The value for next_cursor is used to get the next batch of user profiles.
User profiles will be returned in a records object. The schema for the user profile object is documented in the section below.
{
"status": "success",
"next_cursor": "ZiZjNwMEBQBkaWZzY2MuO20BBQFlYmN7ZG5hewYBTQVjb2BzZmphfwEABQUra2Jmeg%3D%3D",
"records": [
{
"identity": "5555555555",
"profileData": {
"favoriteFood": "pizza"
},
"events": {
"App Launched": {
"count": 10,
"first_seen": 1457271567,
"last_seen": 1458041215
},
"Charged": {
"count": 6,
"first_seen": 1457962417,
"last_seen": 1458041276
}
},
"platformInfo": [
{
"platform": "iOS",
"os_version": "10.2",
"app_version": "6.1.3",
"make": "Apple",
"model": "iPhone7,2",
"push_token": "95f98af6ad9a5e714a56c5bf527a78cb1e3eda18d2f23bc8591437d0d8ae71a3",
"objectId": "-1a063854f83a4c6484285039ecff87cb"
},
{
"platform": "Web",
"objectId": "a8ffcbc9-a747-4ee3-a791-c5e58ad03097"
}
]
}
]
}
If there are no more user profiles available, next_cursor will not be returned, and a success response will be returned.
{ "status" : "success"}
User Profile Object
The following is the schema for the user profile object.
Key | Description |
---|---|
User’s email address. | |
profileData | User’s custom profile properties. |
identity | Custom user identity provided by you. |
name | User’s name. |
platformInfo | Array containing all platform names with the corresponding objectId (CleverTap ID), phone number, push_token, app_version, os_version, make (device make), model (device model) if available. |
Download User Profiles by ID
You can download user profiles by requesting the specific user needed. You can also retrieve a user’s profile and all the events performed by a specific user. Supported identity values are email, a custom identity, or the CleverTap objectId.
Base URL
Here is an example base URL from the account in the India region:
https://api.clevertap.com/1/profile.json
To know the API endpoint for your account, refer to Region.
HTTP Method
GET
Headers
Refer Headers for more details.
URL Parameters
One of the three parameters documented below needs to be included in your request to specify the user profile needed.
Parameter | Description | Type | Example Value |
---|---|---|---|
User’s email address. | string | “[email protected]” | |
identity | Custom user identity defined by you. | string | “5555555555” |
objectId | CleverTap ID. | string | “1a063854f83a4c6484285039ecff87cb” |
Example Request
Here is an example cURL request to the Get User Profiles by ID API showing the headers needed to authenticate the request from the account in the India region:
curl "https://in1.api.clevertap.com/1/[email protected]" \
-H "X-CleverTap-Account-Id: ACCOUNT_ID" \
-H "X-CleverTap-Passcode: PASSCODE" \
-H "Content-Type: application/json"
require 'net/http'
require 'uri'
uri = URI.parse("https://api.clevertap.com/1/[email protected]")
request = Net::HTTP::Get.new(uri)
request.content_type = "application/json"
request["X-Clevertap-Account-Id"] = "ACCOUNT_ID"
request["X-Clevertap-Passcode"] = "PASSCODE"
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',
}
params = (
('email', '[email protected]'),
)
response = requests.get('https://api.clevertap.com/1/profile.json', headers=headers, params=params)
<?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'
);
$response = Requests::get('https://api.clevertap.com/1/[email protected]', $headers);
var request = require('request');
var headers = {
'X-CleverTap-Account-Id': 'ACCOUNT_ID',
'X-CleverTap-Passcode': 'PASSCODE',
'Content-Type': 'application/json'
};
var options = {
url: 'https://api.clevertap.com/1/[email protected]',
headers: headers
};
function callback(error, response, body) {
if (!error && response.statusCode == 200) {
console.log(body);
}
}
request(options, callback);
req, err := http.NewRequest("GET", "https://api.clevertap.com/1/[email protected]", nil)
if err != nil {
// handle err
}
req.Header.Set("X-Clevertap-Account-Id", "ACCOUNT_ID")
req.Header.Set("X-Clevertap-Passcode", "PASSCODE")
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
// handle err
}
defer resp.Body.Close()
Example Response
The user profile returns in a record object. The schema for the user profile object is documented below.
{
"status": "success",
"record": {
"email": "[email protected]",
"profileData": {
"Last Score": 308,
"High Score": 308,
"Replayed": true
},
"events": {
"App Launched": {
"count": 10,
"first_seen": 1457271567,
"last_seen": 1458041215
},
"Charged": {
"count": 6,
"first_seen": 1457962417,
"last_seen": 1458041276
}
},
"platformInfo": [
{
"platform": "iOS",
"os_version": "10.2",
"app_version": "6.1.3",
"make": "Apple",
"model": "iPhone7,2",
"push_token": "95f98af6ad9a5e714a56c5bf527a78cb1e3eda18d2f23bc8591437d0d8ae71a3",
"objectId": "-1a063854f83a4c6484285039ecff87cb"
},
{
"platform": "Web",
"objectId": "a8ffcbc9-a747-4ee3-a791-c5e58ad03097"
}
]
}
}
Additional Notes
- API errors are described on this page.
- For more information on request limit, refer to API Request Limit.
- To understand the common queries and concerns related to CleverTap APIs, refer to API FAQs.
Updated 11 months ago