Get User Profiles API

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.

📘

Note

The batch size denotes the maximum number of records that can be fetched in a single call. The response may vary.

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

https://api.clevertap.com/1/profiles.json

HTTP Method

POST

Headers

These headers are all required. The X-CleverTap-Account-Id and X-CleverTap-Passcode are used to authenticate the request. Refer to the authentication guide to understand how to get their values.

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.

string

"Content-Type: application/json"

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

curl -X POST -d '{"event_name":"App Launched","from":20171201,"to":20171225}' "https://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://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://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://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://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://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

https://api.clevertap.com/1/profiles.json

HTTP Method

GET

Headers

The headers described below are all required. The X-CleverTap-Account-Id and X-CleverTap-Passcode are used to authenticate the request. Refer to the authentication guide to understand how to get their values.

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.

string

"Content-Type: application/json"

URL Parameter

Parameter

Description

Type

Example Value

cursor

Required parameter. Specifies what set of user profiles to return.

string

ZyZjfwYEAgdjYmZyKz8NegYFAwxmamF%2FZ21meU4BBQFlYmN7ZG5ifAYCTQQrai57K2ouegJMABl6

Example Request

curl "https://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

https://api.clevertap.com/1/profile.json

HTTP Method

GET

Headers

These headers are all required. The X-CleverTap-Account-Id and X-CleverTap-Passcode are used to authenticate the request. Refer to the authentication guide to understand how to get their values.

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.

string

"Content-Type: application/json"

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

curl "https://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.
  • Requests are limited to three (3) concurrent requests. If you exceed this limit, a 429 error returns. Try again after 10 minutes.

Did this page help you?