Overview

Use this API to create or update user profiles in CleverTap. With this API, you can update user profile information such as gender, phone, and customer type.

Uploading user profiles to CleverTap requires a POST request with a JSON payload specifying the user profile information. A maximum of 1000 user profile records can be sent per API call.

📘
Concurrent Requests
Concurrent requests to the Upload User Profiles API are limited to 15 per account. Requests that exceed the limit will return a 429 HTTP response code.

For more information on request limit, refer to API Request Limit.

Base URL

Here is an example base URL for an account in the India region:
https://in1.api.clevertap.com/1/upload

Region

Refer Region for more details.

Account-level Passcode for APIs

You can have multiple account-level passcodes rather than having a single account passcode used across different partners. This offers better security when using CleverTap APIs.

HTTP Method

POST

Headers

Refer Headers for more details.

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. A new user profile will be created if this identity is not found.

Parameter	Description	Type	Example Value	Required/Optional
type	Set to profile.	string	“profile”	Required
profileData	User profile properties. Passed as key/value pairs. profileData[“Phone”] should be formatted as +[country code][phone number].	object	"profileData": { "Name": "Jack Montana", "Email": "[email protected]", "Phone": "+14155551234", "Gender": "M", "Employed": "Y", "Education": "Graduate", "Married": "Y", "MSG-sms": false, "Customer Type": "Platinum" }	Required
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. You have to set a value for one of these parameters to identify the user: identity, FBID, GPID, or objectId.	string	“[email protected]”	Optional
FBID	Identify a unique user by Facebook ID. You have to set a value for one of these parameters to identify the user: identity, FBID, GPID, or objectId.	string	“34322423"	Optional
objectId	Identify a unique user by CleverTap Global Object ID. You have to set a value for one of these parameters to identify the user: identity, FBID, GPID, or objectId.	string	“34322425"	Optional

Here is an example JSON payload.

{
  "d": [
    {
      "identity": "1189549",       
      "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-dndWhatsApp": 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",// Pass the date format value as Epoch in seconds.
       "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
The property must have an existing value to increment or decrement a numerical user property. 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 or decr operator.

Example Request

Here are the sample requests to the Upload User Profiles API showing the headers needed to authenticate the request from the account in the India region:

curl -X POST -d '{"d":[{"objectId":"25b08803c1af4e00839f530264dac6f8","type":"profile","profileData":{"Name": "Jack Test"}}]}' "https://in1.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://in1.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://in1.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://in1.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://in1.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://in1.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

The following is the example response for Upload User Profiles API:

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

Delete User Property Values

You can delete user property values using the$delete operator as shown in the following example:

{"d":
    [
        {
            "identity":"test_user",
            "type":"profile",
            "profileData":
                {
                    "testAttribute":{"$delete":"user_property_value"}
                }
        }
    ]
}

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.

For more information on API error codes, refer to this page.

To understand the common queries and concerns related to CleverTap APIs, refer to API FAQs.

Upload User Profiles

Overview

📘
Concurrent Requests

Base URL

Region

Account-level Passcode for APIs

HTTP Method

Headers

Body Parameters

📘
Note

Example Request

Example Response

Delete User Property Values

Debugging

Overview

📘Concurrent Requests

Base URL

Region

Account-level Passcode for APIs

HTTP Method

Headers

Body Parameters

📘Note

Example Request

Example Response

Delete User Property Values

Debugging

📘
Concurrent Requests

📘
Note