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
email	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
email	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.

Overview

Get User Profiles by Events

📘Batch Size

Get Cursor by Specifying Events for User Profiles

Base URL

Region

HTTP Method

Headers

URL Parameter

Body Parameters

Example Request

Example Response

Get User Profiles Using Cursor

Base URL

HTTP Method

Headers

URL Parameter

Example Request

Example Response

User Profile Object

Download User Profiles by ID

Base URL

HTTP Method

Headers

URL Parameters

Example Request

Example Response

Additional Notes

📘
Batch Size