Upload User Profiles API
The Upload User Profiles API enables you to create or update user profiles in CleverTap.
For example, you can use this API to update a user profile to include information, such as gender, phone, and customer type.
Overview
Uploading user profiles to CleverTap requires a POST request with a JSON payload specifying the user profile information. 100 user profiles records can be sent per API call.
Base URL
https://api.clevertap.com/1/upload
HTTP Method
POST
Headers
These headers are all required. The X-CleverTap-Account-Id and X-CleverTap-Passcode are used to authenticate the request. Please see the authentication guide to see 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; charset=utf-8. | string | "Content-Type: application/json; charset=utf-8" |
Body Parameters
User profile attribute keys are limited to 120 bytes and their values are limited to 512 bytes. The maximum number of custom user profile keys is 256.
For each user profile, a user identifier is required. This is the key that CleverTap uses to find the user whose profile needs to be updated. You have to set a value for one of these parameters to identify the user: identity, FBID, GPID, or objectId. If this identity is not found a new user profile will be created.
Parameter | Description | Type | Example Value |
---|---|---|---|
type | Set to profile. Required. | string | âprofileâ |
profileData | User profile properties. Passed as key/value pairs. Required. | object | "profileData": { |
ts | Date and time when the event occurred, Formatted as a UNIX epoch in seconds. Defaults to the current timestamp if omitted. Optional. | ts | 1468308340 |
identity | Identity to recognize a unique user. It can be the userâs email, a phone number, or any other identifier that you are using to tag your users. | string | â[email protected]â |
FBID | Identify a unique user by Facebook ID. | string | â34322423" |
objectId | Identify a unique user by CleverTap Global Object ID. | string | â34322425" |
Here is an example JSON payload.
{
"d": [
{
"identity": "1189549",
"ts": 1468308340,
"type": "profile",
"profileData": {
"Name": "Jack Montana",
"Name": {"$delete" : 1}, //this will delete the value of name
"Email": "[email protected]",
"Phone": "+14155551234",
"Gender": "M",
"Gender": {"$delete" : 1}, //this will delete the value of gender
"MSG-sms": false,
"MSG-email":true,//called when email must be subscribed
"MSG-whatsapp": true,
"MSG-dndPhone": true,
"MSG-dndEmail": true, //called when all profiles sharing the same email must be unsubscribed
"category-unsubscribe": {
"email": ["Newsletters", "Promotions"]
},//called when profile needs to be unsubscribed from multiple subscription groups
"category-resubscribe": {
"email": ["Football", "Movies"]
},//called when profile needs to be subscribed from multiple subscription groups
"DOB": "$D_1487576752",
"Customer Type": "Platinum",
"Custom Multi Value":{"$remove":["shoes","bags"]}, // To remove Multi Value properties
"Custom Multi Value":{"$add":["shoes","bags"]}, //To add Multi Value properties
"My Number 1": {"$incr" : 10}, //To increment integer data
"My Number 2": {"$decr" : 30} //To decrement integer data
}
}
]
}
//$delete applicable only to name and gender fields
Note
In order to increment/decrement a numerical user property, the property needs have an existing value. If the property does not exist or if the value is NULL, please pass the property key OR add the value before using the incr/decr operator
Example Request
curl -X POST -d '{"d":[{"objectId":"25b08803c1af4e00839f530264dac6f8","type":"profile","profileData":{"Name": "Jack Test"}}]}' "https://api.clevertap.com/1/upload" \
-H "X-CleverTap-Account-Id: ACCOUNT_ID" \
-H "X-CleverTap-Passcode: PASSCODE" \
-H "Content-Type: application/json; charset=utf-8"
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://api.clevertap.com/1/upload")
request = Net::HTTP::Post.new(uri)
request.content_type = "application/json; charset=utf-8"
request["X-Clevertap-Account-Id"] = "ACCOUNT_ID"
request["X-Clevertap-Passcode"] = "PASSCODE"
request.body = JSON.dump({
"d" => [
{
"objectId" => "25b08803c1af4e00839f530264dac6f8",
"type" => "profile",
"profileData" => {
"Name" => "Jack Test"
}
}
]
})
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; charset=utf-8',
}
data = '{"d":[{"objectId":"25b08803c1af4e00839f530264dac6f8","type":"profile","profileData":{"Name": "Jack Test"}}]}'
response = requests.post('https://api.clevertap.com/1/upload', headers=headers, 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; charset=utf-8'
);
$data = '{"d":[{"objectId":"25b08803c1af4e00839f530264dac6f8","type":"profile","profileData":{"Name": "Jack Test"}}]}';
$response = Requests::post('https://api.clevertap.com/1/upload', $headers, $data);
var request = require('request');
var headers = {
'X-CleverTap-Account-Id': 'ACCOUNT_ID',
'X-CleverTap-Passcode': 'PASSCODE',
'Content-Type': 'application/json; charset=utf-8'
};
var dataString = '{"d":[{"objectId":"25b08803c1af4e00839f530264dac6f8","type":"profile","profileData":{"Name": "Jack Test"}}]}';
var options = {
url: 'https://api.clevertap.com/1/upload',
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 {
D []struct {
ObjectID string `json:"objectId"`
Type string `json:"type"`
ProfileData struct {
Name string `json:"Name"`
} `json:"profileData"`
} `json:"d"`
}
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/upload", 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; charset=utf-8")
resp, err := http.DefaultClient.Do(req)
if err != nil {
// handle err
}
defer resp.Body.Close()
Example Response
{
"status": "success",
"processed": 1,
"unprocessed": []
}
Debugging
Requests with processing errors will be returned in the API call response as shown in the example below.
{
"status":<success, partial, fail>,
"processed":<count>,
"unprocessed": [{"status":"fail", "code":<error code>, "error":<error msg>, "record":<record>}]
}
To test if your data will be submitted without errors, you can add the parameter dryRun=1 to the URL. This will validate the input without submitting the data to CleverTap.
A list of errors code for this API can be found on this page.
Updated over 1 year ago