Custom Segments Overview

Create, update, and manage your file-based and filter-based segments using the MoEngage Custom Segments API.

Overview

The MoEngage Custom Segments API allows you to programmatically manage your audience segments. This suite includes the v2 API for handling high-volume file-based segments and segment lifecycles, and the v3 API for dynamic, filter-based custom segments.

Custom Segment API Endpoints

The Custom Segments API is a collection of the following endpoints:

File Segments (v2)

• Create File Segment
• Add Users to File Segment
• Remove Users from File Segment
• Replace Users in File Segment

Segment Lifecycle (v2)

• Archive Custom Segment
• Unarchive Custom Segment

Filter Segments (v3)

• List Custom Segments
• Create Filter Segment
• Get Custom Segment by ID
• Update Filter Segment

Segment Types

Type	Description	Best For
File Segment	Created by importing a CSV file of unique user identifiers.	Large, static lists or external data imports.
Filter Segment	Created based on user attributes or real-time actions/events.	Dynamic targeting based on user behavior and profile data.

Usage Limits & Guidelines

File Segment Limits

Rate Limit Name	Limit Value
Total Active Segments	Maximum of 1000 active custom segments per client.
Operations per Hour	10 operations (create/add/remove) per hour.
Users per Day	2 million users uploaded via File Segment per day.
File Size	Maximum 150 MB per CSV file.

FAQs

Filter-Based Segments

How can I generate the payload for custom segment creation?

You can generate the payload directly from the MoEngage Dashboard. Navigate to Test & Debug -> Segment Payload, choose your filters, and click Generate Payload.

How do I get the ID of a custom segment I created earlier but didn't save?

Use the List Custom Segment API with the name query parameter to filter and retrieve the unique ID of the desired segment.

Why am I getting a 409 Conflict error even with a different name?

Both the name and the definition (filters) of a custom segment must be unique. If the definition matches an existing segment, the API returns a 409 Conflict.

How do I know which existing segment is conflicting?

In the case of a 409 error, the response payload includes the existing_cs_name and existing_cs_id of the conflicting segment.

How do I increase the rate limits?

Please connect with your account manager.

File-Based Segments

Why does my new segment show zero users immediately after creation?

Segment processing is asynchronous. MoEngage first creates the segment container (showing zero users) and then processes the file. The count will update once processing is complete.

Can I update a file segment using filter conditions?

No. File segments can only be updated (add/remove/replace) via the File Segment API using CSV imports. For attribute-based updates, use Filter Segments.

Segment Lifecycle

What is the benefit of archiving a segment instead of deleting it?

Archiving allows you to reuse segments for A/B testing or historical analysis without recreating them from scratch, while keeping your active segment list within the 1000-segment limit.