Custom List Segments


Custom List Segments are custom segments that you can create based on your requirements and analytics. These can be users with the required interests, demographics, and so on. You can use these segments to re-engage your users without having to apply the same conditions or filters again.


A custom list segment can be handy in many scenarios. Typical use cases can be any of the following and more:

  • A retail business running SMS campaigns:
    As a retail business, you may be generating user lists at your point of sale across different cities. You can upload city-based segments and run personalized campaigns to re-engage these users.

  • Engagement integrated with your segmentation engine:
    You may have a segmentation engine or a data science engine that has created a user set to engage with a specific message. In this case, you can use custom list segments to seamlessly create segments from your custom lists and schedule engagement for them.

  • Real-time sync for engagement with your in-house segments:
    For example, an app streaming a football match can have millions of users. However, let us assume that the target audience is 10,000 users. The next match is even more interesting and you are expecting a surge in the number of users. You have a list of 15,000 users handy that you can use to run the campaign. You create a segment on this list and run a campaign immediately.

Create a custom list segment

You can create a custom list segment by uploading user lists via the dashboard or an API.

File Format

The list of the users for your segment must follow a specific format. You can upload the profiles with identity type as GUID or CleverTap ID (g) or the identity (i).

The format of the CSV file is as follows:






The type and identity columns are mandatory for uploading a custom list segment.


You can only qualify the user profiles that are already available in CleverTap.

Create from dashboard

  1. Click the + Segment button.

  2. Click Custom Lists. The Create new Window appears.

  1. Click the Upload user list button and select the CSV file.
  1. Name the file and save it.
  1. You will receive an email with the details after the file is processed.

The uploaded segment is now available for use.

File size

You can upload maximum file size of 50 MB from the dashboard. The maximum file size allowed from an API upload is 5GB.

Create from API

You can create a custom list segment from API. For more information, see Custom list API.

Replace via dashboard

You can replace a custom list segment from the dashboard. However, if the segment is currently in use for engagement through a Campaign or Journey, then you must stop the Campaign or Journey before replacing the segment.

To replace a segment:

  1. Click the ellipsis for segment action from the Segments dashboard.
  1. Click the replace icon
  2. Click the Re-upload user list and select the CSV file.
    Upload the CSV file.
  3. Name the file and save it. Wait for it to be processed.
  4. You will receive an email with the details after the file is processed.

The uploaded segment is now available for use.

Troubleshoot Upload

You may see the following messages when trying to upload the file.

If the file is not uploaded correctly, you may have to upload it again.

Segment issue

File upload failed

The segment could not be created from the uploaded file. Fix the errors and re-upload the file.

File re-upload failed

The segment could not be refreshed with the latest file. The segment will be available with the last successful update. Refer to the Segment Details page for the last updated file.

Segment processing

The custom list segment is available for use only after the process of creating or updating is complete.

Segment details

The segment details can be viewed from the Segment dashboard.

The segment details page shows all the available information for the segment such as:

  • Trend - If the users have increased or decreased over time.
  • Campaigns and Journeys - The number of campaigns and Journeys currently using the custom list segment.
  • Segment size and reachability - The total number of users in the segment and their reachability across various engagement channels.
  • Sample Users - These are samples from your list. You can open any of them to check their details.


Hover over sample users to find the download icon.
Click this button to download all the users in your segment.

Use Custom List Segment

You can use the custom list segment from the Who section when creating a campaign. All the custom list segments are listed under the Custom list segment tab.

Updated 6 months ago

Custom List Segments

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.