Documentation > API

Working with User Profiles API

Download User Profiles

CleverTap enables developers to download User profiles using the below documented API. User profiles can be downloaded in two ways using this API

  1. Download profiles by Events
  2. Download profiles by ID

Download Profiles by Events

Using the API documented below, you can download all the user profiles that have performed a certain event

Understanding User Profiles paging request and response

To support efficient batching and pagination of large record sets, accessing user profile records via the Server API is a multi-request process.

With your first request you will specify a JSON formatted query for records as part of the POST payload, and a batch_size URL query parameter, specifying the number of records to be returned per request, along with your CleverTap Account ID and CleverTap Account Passcode in the request headers.

The response to this initial query request will return a cursor, which you will then append to the URL query in subsequent requests to fetch the actual record set paginated by the batch_size you specify.

Each response of records using that cursor will return a next_cursor to fetch the subsequent set of records. Once there are no more records to be fetched, the next_cursor key will no longer be returned.

In this regard, it may be helpful to think of the cursor as something akin to a database cursor

Request Authentication

Every request to the API should include your CleverTap Account ID and CleverTap Account Passcode in the request header keyed with X-CleverTap-Account-Id and X-CleverTap-Passcode, respectively.
Content-Type header must be specified as application/json.

Initial Endpoint For Cursor

A request to download User Profile information is an HTTP URL of the following form:

POST https://api.clevertap.com/1/profiles.json?batch_size=5000

Maximum batch_size is 5000, this will return 5000 records per request.

Payload

JSON formatted request with the following parameters

Required Parameters

event_name – The name of the event which has been performed by the users whose profiles you want to download

from & to – Date range within which users should have performed the event you have specified in event_name , input values have to be formatted as integers in YYYYMMDD format

Optional Parameters

Refer here for documentation on advanced queries, their structure, and examples.

Notification Sent event is supported here. Further information about the event is available in the special events section on the above link.

Example Payload

{
    "event_name": "choseNewFavoriteFood",
    "event_properties": [
        {
            "name": "value",
            "operator": "contains",
            "value": "piz"
        }
    ],
    "from": 20150810,
    "to": 20151025
}
copy Copied

Response

{
    "status": "success",
    "cursor": "ZiZiNwMEBQBkaWZzY2MuO20BBQFlYmN7ZG5hewYBTQVjb2BzZmphfwEABQUra2Jmeg%3D%3D"
}
copy Copied

Endpoint For Subsequent Records

To download subsequent requests you have to use the endpoint documented below while keeping the CleverTap authentication headers in place:

GET https://api.clevertap.com/1/profiles.json?cursor=ZiZiNwMEBQBkaWZzY2MuO20BBQFlYmN7ZG5hewYBTQVjb2BzZmphfwEABQUra2Jmeg%3D%3D

Response

{
  "status": "success",
  "previous_cursor": "ZiZiNwMEBQBkaWZzY2MuO20BBQFlYmN7ZG5hewYBTQVjb2BzZmphfwEABQUra2Jmeg==",
  "next_cursor": "ZiZjNwMEBQBkaWZzY2MuO20BBQFlYmN7ZG5hewYBTQVjb2BzZmphfwEABQUra2Jmeg%3D%3D",
  "records": [
    {
      "identity": "5555555555",
      "profileData": {
        "favoriteFood": "pizza"
      },
      "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"
        }
      ]
    }
  ]
}
copy Copied

Response records may have keys email, phone, name, identity, and profileData (containing the custom profile attributes)

There may be a platformInfo array containing all platform names with the corresponding objectId (CleverTap ID), push_token, app_version, os_version, make (device make), model (device model) if available.

Download Profiles by ID

Using this API, you can retrieve the profile and all the events performed by an individual using their ID. Supported ID values are – email, a custom identity (that you have set for the user via the SDK, JavaScript or Server API), or the unique CleverTap objectId used by CleverTap to identify the user profile.

Request Authentication

Every request to the API should include your CleverTap Account ID and CleverTap Account Passcode in the request header keyed with X-CleverTap-Account-Id and X-CleverTap-Passcode, respectively.

Endpoint

A request to download User Profile information is an HTTP URL of the following form:

GET https://api.clevertap.com/1/profile.json?<profile_key>=<value>

Payload

JSON formatted request with the following parameters

Required parameters
profile_key – A valid ID that can be used to identify a profile. Supported values are: email, identity & objectId

Example:

GET https://api.clevertap.com/1/profile.json?email=Email ID
GET https://api.clevertap.com/1/profile.json?objectId=CleverTap objectID
GET https://api.clevertap.com/1/profile.json?identity=Your identity value

Response:

{
  "status": "success",
  "record": {
    "email": "jack@gmail.com",
    "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"
      }
    ]
  }
}
copy Copied

Response records may have keys email, phone, name, identity, and profileData (containing the custom profile attributes)

There may be a platformInfo array containing all platform names with the corresponding objectId (CleverTap ID), push_token, app_version, os_version, make (device make), model (device model) if available.

Uploading User Profiles

CleverTap enables developers to upload User profiles using the below documented API request

Endpoint

A request to upload User Profile information is an HTTP URL of the following form:

POST https://api.clevertap.com/1/upload

Authentication

All requests should include your CleverTap Account ID and CleverTap Account Passcode in the request headers keyed with X-CleverTap-Account-Id and X-CleverTap-Passcode, respectively.
Content-Type header must be specified as application/json.

Payload

JSON formatted payload with Content-Type: application/json header and a JSON object keyed with d whose value is an Array container of JSON data records, and then JSON-encoded, e.g. {"d":JSON-encoded data} with the following keys:

Required parameters

type – set to profile for updating an Users’ profile. Must be String

profileData – JSON profile keys and values to be updated. See example payload below

One of the following identity parameters are required

identity – identity to recognize a user uniquely. It can be the user’s email id, a phone number or any other identifier that you are using to tag your users.This is the key that will be looked up to find the user whose profile needs to be updated. If this identity is not found a new user profile will be created. Must be String

FBID – Can be used to identify a unique user by his/her Facebook ID. Must be String

GPID – Can be used to identify a unique user by his Google Plus ID. Must be String

objectId – Can be used to identify a unique user by their CleverTapGlobal Object ID. Must be String

Optional Parameters

ts – date and time when the profile was originally created, formatted as a UNIX epoch. Defaults to current timestamp if omitted. Must be Integer

Example payload

In this sample, profile attribute data for a user identified by customer id 1189549 is updated

profileData[“Phone”] should be a string formatted as +[country code][phone number]. Must be String

{
  "d": [
    {
      "identity": "1189549",  // customer ID, email or any other ID that uniquely identifies your user
      "ts": 1468308340,       // user creation date, or just leave this field out to set the time has current
      "type": "profile",
      "profileData": {
        "Name": "Jack Montana",
        "Email": "jack@gmail.com",
        "Phone": "+14155551234",
        "Gender": "M",
        "Employed": "Y",
        "Education": "Graduate",
        "Married": "Y",
        "DOB": "$D_1487576752",    // UNIX epoch timestamp with $D_ prefix for recording date properties (string)
        "Customer Type": "Platinum"
      }
    }
  ]
}
copy Copied

Example response format

{
    "status":<success, partial, fail>, 
    "processed":<count>, 
    "unprocessed": [{"status":"fail", "code":<error code>, "error":<error msg>, "record":<record>}]
}
copy Copied

Example response

{
    "status": "success",
    "processed": 1,
    "unprocessed": []
}
copy Copied

Error codes

514 Gender invalid
515 Email invalid
516 Phone number invalid
517 Employment status invalid
518 Education status invalid
519 Marital status invalid
520 Age invalid
523 Missing identity
524 Data neither event nor profile
525 Timestamp not an epoch
526 objectId invalid
555 Miscellaneous server error

HTTP Response Codes

200 Successful request
400 Bad Request. Some mandatory parameter was missing
429 Too many requests were made concurrently.
500 Server Error
Currently, we return 429 when you make more than 3 concurrent requests. Please try again after 10 minutes

Debugging

  • Records with errors in processing will be sent back along with the response of the HTTP request
  • To test whether data submitted is without errors, you can add the parameter dryRun=1 to the URL

Data Validation

  • User Profile attribute keys are limited to 32 characters
  • User Profile attribute values are limited to 120 bytes
  • Maximum number of custom User Profile attributes is 63

Limitations and Constraints

Maximum 100 records may be sent per API call. The calls to the endpoint are synchronous. We recommend you make a single call from your server at a time, wait for the response before making another API request

Concurrent requests are limited to 3 per account. Requests that exceed the limit will return a 429 HTTP response code

Import Device Tokens

CleverTap enables developers to import an existing device token (GCM, APNS etc.) into a user’s profile.

Request Authentication

Every request to the API should include your CleverTap Account ID and CleverTap Account Passcode in the request header keyed with X-CleverTap-Account-Id and X-CleverTap-Passcode, respectively. Content-Type header must be specified as application/json.

Endpoint

A request to upload device tokens to a User Profile is an HTTP URL of the following form:

POST https://api.clevertap.com/1/upload

Payload

JSON-formatted request with the following parameters

Required parameters

type – set to ‘token’ for updating Tokens. Must be of type String.
tokenData – JSON keys and values to be updated. See example payload below.
objectId – used to identify a unique user by their CleverTap Global Object ID. Must be of type String.

Note : for updating Google Chrome tokens, the below mentioned additional JSON keys are also required
keys – JSON object, retrieved from google endpoint response at the time of registering WebPush subscription. See example below –

Payload Structure for iOS/Android/Windows (mobile devices)

{
    "d": [
        {
            "type": "token",
            "tokenData": {
                "id": <Device Token>,
                "type": apns/gcm/fcm/wns/mpns
            },
            "objectId": <ClevertapId/GUID>
        }
    ]
}
copy Copied

Payload Structure for WebPush (Chrome)

{
    "type": "token",
    "tokenData": {
        "id": <DeviceToken>,
        "type": "chrome",
        "keys": {
            "p256dh": <>,
            "auth": <>
        }
    },
    "objectId": <ClevertapId/GUID>
}
copy Copied

Example payload

{
    "d": [
        {
            "type": "token",
            "tokenData": {
                "id": "frfsgvrwe:APfdsafsgdfsgghfgfgjkhfsfgdhjhbvcvnetry767456fxsasdf",
                "type": "chrome",
                "keys": {
                    "p256dh": "BLc4xRzKlKORKWlbdgFaBrrPK3ydWAHo4M0gs0i1oEKgPpWC5cW8OCzVrOQRv-1npXRWk8udnW3oYhIO4475rds=",
                    "auth": "5I2Bu2oKdyy9CwL8QVF0NQ=="
                }
            },
            "objectId": "QBOpVJZmKilRAzfaiVS86Tovxm75lHxg"
        },
        {
            "type": "token",
            "tokenData": {
                "id": "dYfuuBmHLGI:APA91bEfAq1b6NAmz0uhUbVxwSLqgKF25zDb7vhgajzS-bOAEUKekH_jbzO5oU1Qip-ZLvDpwKccxAxVNjC3rUUJnFTKDUiBcF9AtuG03_PRfjoUxLKHMR9qykK22SiubrLirNzQtNnO",
                "type": "fcm"
            },
            "objectId": "__gc4grg4053N1eYkW6OBH71jhFev7b1iP"
        },
        {
            "type": "token",
            "tokenData": {
                "id": "frfsgvrwe:APfdsafsgdfsgghfgfgjkhfsfgdhjhbvcvnetry767456fxsasdf",
                "type": "gcm"
            },
            "objectId": "__QlXHaDHBZxZPLEMpPo6VvwdZ7FnbGvWA"
        },
        {
            "type": "token",
            "tokenData": {
                "id": "frfsgvrwe:APfdsafsgdfsgghfgfgjkhfsfgdhjhbvcvnetry767456fxsasdf",
                "type": "apns"
            },
            "objectId": "-HwB9gZWb3RcKhXCQ222FhAhkjeYQs0Hj"
        },
        {
            "type": "token",
            "tokenData": {
                "id": "frfsgvrwe:APfdsafsgdfsgghfgfgjkhfsfgdhjhbvcvnetry767456fxsasdf",
                "type": "wns"
            },
            "objectId": "~9XrS4Dy6GsnDbdX98Ijs63kEtJDQbhJA"
        },
        {
            "type": "token",
            "tokenData": {
                "id": "frfsgvrwe:APfdsafsgdfsgghfgfgjkhfsfgdhjhbvcvnetry767456fxsasdf",
                "type": "mpns"
            },
            "objectId": "~y9MqjkDGRfbzwwH8fZI6LIXgTKaEPxHr"
        }
    ]
}
copy Copied

Error Codes

530 : Invalid ‘objectId’
531 : Invalid token data
532 : Token ‘id’ is not present
533 : Token ‘type’ is not present
534 : Token ‘type’ is not valid for ‘objectId’
535 : Invalid token data

Limitations and Constraints

Device token can be updated against CleverTapId (objectId/guid) and not against an email ID or user’s identity in a profile. If given profile already has a token, it won’t be updated and an error will be reported into Live Error Stream.

Maximum 100 records may be sent per API call. The calls to the endpoint are synchronous. We recommend you make a single call from your server at a time, wait for the response before making another API request.

Concurrent requests are limited to 3 per account. Requests that exceed the limit will return a 429 HTTP response code