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

ParameterDescriptionTypeExample Value
batch_sizeThe number of results to return in each API call. The maximum is 5000.int50
appOptional 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.booleantrue
eventsOptional 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.booleantrue
profileOptional 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.booleantrue

Body Parameters

ParameterDescriptionTypeExample Value
event_nameThe 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”
fromStart of date range for events needed. Value specified in format YYYYMMDD.int20171201
toEnd of date range for events needed. Value specified in format YYYYMMDD.int20171225

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

ParameterDescriptionTypeExample Value
cursorRequired parameter. Specifies what set of user profiles to return.stringZyZjfwYEAgdjYmZyKz8NegYFAwxmamF%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.

KeyDescription
emailUser’s email address.
profileDataUser’s custom profile properties.
identityCustom user identity provided by you.
nameUser’s name.
platformInfoArray 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.

ParameterDescriptionTypeExample Value
emailUser’s email address.string[email protected]
identityCustom user identity defined by you.string“5555555555”
objectIdCleverTap 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.