Custom List API

Overview

Custom list segments are segments that are created from your list of users. You can create a custom list segment in three steps:

  1. Request for a pre-signed URL with your first API call. A pre-signed URL gives you temporary access to upload your list of users. This request returns a URL that you can use in the second step to upload your file.
  2. Upload your file to the URL received from step 1.
  3. Make a second API call to indicate that you have completed the file upload. CleverTap selects the file to create the segment that it displays on the dashboard.

Step 1: Create a pre-signed URL

This request returns a pre-signed URL to upload your custom list.

Base URL

Here is an example base URL from the account in the India region:
https://in1.api.clevertap.com/get_custom_list_segment_url

Region

Refer Region for more details.

HTTP Method

POST

Headers

Refer Headers for more details.

📘

Note

Currently, we don't have any Body Parameters for this API.

Example Request

Here is an example cURL request to the Custom List Endpoint showing the headers needed to authenticate the request from the account in the India region:

curl -X POST \
  https://in1.api.clevertap.com/get_custom_list_segment_url \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-CleverTap-Account-Id: ACCOUNT_ID' \
  -H 'X-CleverTap-Passcode: PASSCODE'

Example Response

{
    "presignedS3URL": <PRE-SIGNED URL>,
    "expiry": "7 May, 01:29 PM",
    "status": "success"
}

A success response is displayed if the pre-signed URL is generated.

{ "status" : "success"}

The pre-signed URL is valid for a maximum of 24 hours from the time of generation.

{ "expiryEpoch": {"$date": "2019-04-24T13:04:37.088Z"}

If the pre-signed URL is not generated successfully, then you get the following response:

URL not generated, Please come back later

Step 2: Upload custom list file

Upload the list of users file to the pre-signed URL received from step 1. This file must be a .CSV file. See Creating a file for custom list segment for more information about the specifications of the custom list segment file.

Use the following command to upload the file:

$(curl --request PUT --upload-file "<path to file on your local machine>" "<presigned URL>")

Example Request

$(curl --request PUT 
--upload-file "Users⁩/janedoe/Documents⁩/custom_list_file.csv”
"<PRE-SIGNED URL")

Example Response

A success response displays the progress of the file upload until it completes.

%   Total    % Received %       Xferd  Average   Speed      Time      Time    Time    Current
                                       Dload  Upload      Total     Spent     Left      Speed
100  1909    0               0  100  1909           0          1438  0:00:01  0:00:01    --:--:--        1439

Step 3: Indicate completion of file upload

Using the pre-signed URL received from step 1, make an API call to indicate that you have completed the upload of the custom list. When this step is completed successfully, CleverTap selects the uploaded custom list and displays it on the dashboard.

Base URL

Here is an example base URL from the account in the India region:
https://in1.api.clevertap.com/upload_custom_list_segment_completed

To know the API endpoint for your account, refer to Region.

HTTP Method

POST

Headers

These headers are all required. The X-CleverTap-Account-Id and X-CleverTap-Passcode authenticate the request. See the authentication guide to learn about getting their values.

HeaderDescriptionTypeExample Value
X-CleverTap-Account-IdYour CleverTap Account ID.string"X-CleverTap-Account-Id: ACCOUNT_ID"
X-CleverTap-PasscodeYour CleverTap Account Passcode.string"X-CleverTap-Passcode: PASSCODE"
Content-TypeRequest content-type is always set to application/json.string"Content-Type: application/json"

Body Parameters

ParameterDescriptionTypeExample Value
nameName of the segment.stringsample segment
creatorName of the user making this API call.stringJane
filenameName of the file that you had uploaded previously.stringmy_file_name.csv
emailEmail address of the owner. This must be an Admin email.string[email protected]
urlThe pre-signed URL that identifies this file's location received as a response to the first API callstring
replaceOptional parameter. This will be used when you want to replace a set of users in an existing segmentbooleantrue

Example Request

Here is an example cURL request to the Upload Custom List Segment Completion API showing the headers needed to authenticate the request from the account in the India region:

curl -X POST \
  https://in1.api.clevertap.com/upload_custom_list_segment_completed \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-CleverTap-Account-Id: ACCOUNT_ID' \
  -H 'X-CleverTap-Passcode: PASSCODE' \
  -H 'cache-control: no-cache' \
  -d '{ "name":"sample segment", "email":"[email protected]","filename": "my_file_name","creator":"Jane", "url":"<PRE-SIGNED URL>", "replace":false}

Example Response

A success response appears if there are no immediate errors in the custom list file upload. The segment id for the segment created is returned in the response.

{
    "Segment ID": 1598345958,
    "status": "success"
}

If the file is not found at the specified URL, the following response appears:

{
   "status": "fail",
   "Error": “Invalid URL”
}

If you do not specify the mandatory parameters, the following response appears:

{
   "status": "fail",
   "Error": “name, email ID,filename,creator and pre-signed url are mandatory”
}

If the email ID is either not in the right format or it is invalid, the following response appears:

{
   "status": "fail",
   "Error": “email id is either not in the right format or does not belong to a valid admin”
}

If an old URL, which was successfully processed previously, is re-used with a new custom list name, you’ll get the following response:

{
   "status": "fail",
   "Error": “New file referencing a previously used URL. Please change URL”
}

Example Response on email

The following responses are emailed to the owner’s email address mentioned in this API call as these need some processing.

If the file is uploaded successfully and a segment is created/replaced, the following response appears:

my_file_name.csv was sucessfully processed for Custom list segment sample segment.

Segment details
- Total users in uploaded list: 1
- Users in list identified on CleverTap: 1

If the segment could not be created/updated from the file uploaded, the following response appears:

File my_file_name.csv could not be processed for Custom list segment sample segment.
Please, check file uploaded and try again.

Status on dashboard

You can see the segment on the dashboard after it is processed successfully. The possible statuses are:

  • Segment successfully created/updated: the segment is processed successfully from the file.
    *File upload failed: The segment could not be created from the file.
  • File re-upload failed: The segment could not be replaced with the new file. The previous set of users exist in the file.
    *Segment unavailable: The segment is being processed now. Wait till it is complete. An email is sent on the completion.

The campaigns can be created on the segment after the processing is complete. See Custom Lists to create a campaign on the custom list segment.

Sample code for uploading large files

package myjava;

import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;

public class UploadFileToS3 {

    private static boolean uploadCsvFile(File file, String preSignURL) throws Exception {
        long startTime = System.currentTimeMillis();
        System.out.println("Starting with Clevertap file upload for file: " + file.getName() + ", now:" + startTime);
        OutputStream bos = null;
        HttpURLConnection connection = null;
        try {
            URL url = new URL(preSignURL);
            connection = (HttpURLConnection) url.openConnection();

            long fileLength = file.length();
            System.out.println("Length of  the file: " + (fileLength / (1024 * 1024)) + " MB");
            // to enable streaming of a HTTP request body without internal buffering,
            // when the content length is known in advance
            connection.setFixedLengthStreamingMode(fileLength);

            connection.setConnectTimeout(10000);
            connection.setReadTimeout(90000000);
            connection.setDoOutput(true);
            connection.setRequestMethod("PUT");

            bos = connection.getOutputStream();
            FileInputStream inFileReader = new FileInputStream(file);
            int batchSize = 10240; // buffer size to stream, can be decreased/increased according to the need
            byte[] localbuffer = new byte[batchSize];
            long bytesTransferred = 0;
            while (bytesTransferred + batchSize <= fileLength) {
                inFileReader.read(localbuffer);
                bos.write(localbuffer);

                // To have an idea about how much memory the system is using at an instant
                if ((bytesTransferred % (1024 * 1024)) == 0) {
                    System.out.println("Data transferred: " + (bytesTransferred / (1024 * 1024)) + " MB, current system mem: "
                            + (Runtime.getRuntime().totalMemory() - Runtime.getRuntime().freeMemory()) / (1024 * 1024) + " MB");
                }
                bytesTransferred += batchSize;
            }

            int remainingBytes = (int) (fileLength - bytesTransferred);
            System.out.println("writing the remaining bytes: " + remainingBytes);
            localbuffer = new byte[remainingBytes]; // the remaining number of bytes can be less than the buffer size, so new byte array needed
            inFileReader.read(localbuffer);
            bos.write(localbuffer);
            bos.flush(); // finally flush

            inFileReader.close();
            int responseCode = connection.getResponseCode();
            System.out.println("ResponseCode for Clevertap file upload for file: " + file.getName() + ", code:" + responseCode);
            System.out.println("final " + (Runtime.getRuntime().totalMemory() - Runtime.getRuntime().freeMemory()));
            System.out.println("uploaded successfully");
            System.out.println("timetaken = " + ((int) ((System.currentTimeMillis() - startTime) / 1000)) + " sec");
            return true;
        }  catch (Exception e) {
            System.out.println("Exception with Clevertap file upload for file: " + file.getName());
        } finally {
            System.out.println("/: " + file.getName() + ", url:" + preSignURL);
            if (bos != null) {
                bos.close();
            }
            if (connection != null) {
                connection.disconnect();
            }
        }

        System.out.println("uploading failed");
        System.out.println("timetaken = " + ((int) ((System.currentTimeMillis() - startTime) / 1000)) + " sec");
        return false;
    }

    public static void main(String[] args) throws Exception {

        String url = "<S3_PresignedUrl>";
        File f = new File("<File_Path>");
        uploadCsvFile(f, url);

    }
}

API FAQs

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