The MoEngage Segments API allows you to manage your audience segments. This suite includes the v2 API for handling high-volume file-based segments and segment lifecycles, the v3 API for dynamic, filter-based segments, and the Cohort Sync API for synchronizing external audiences directly with MoEngage.Documentation Index
Fetch the complete documentation index at: https://moengage.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
Endpoints
The Segments API is a collection of the following endpoints:File Segments (v2)
The File Segments API allows you to create and manage segments by importing users from CSV files hosted at a URL.- Create File Segment: Creates a new file segment from a CSV file URL.
- Add Users to File Segment: Adds a list of users from a CSV file to an existing file segment.
- Remove Users from File Segment: Removes a list of users from a CSV file from an existing file segment.
- Replace Users in File Segment: Replaces all users in an existing file segment with a new list of users from a CSV file.
Ensure all users are imported into MoEngage before including them in a file segment; only existing profiles can be successfully mapped.File segments archived for more than 30 days will undergo permanent user deletion. This data cannot be recovered once deleted.
Manage Segments (v2)
The Manage Segments API allows you to control the lifecycle of your segments by archiving or unarchiving them.- Archive Segment: Archives an existing segment (File or Filter).
- Unarchive Segment: Unarchives an existing segment, making it active again.
Filter Segments (v3)
The Filter Segments API allows you to create and manage dynamic segments based on user attributes and behavioral filter conditions.- List Segments: Lists all filter segments.
- Create Filter Segment: Creates a new filter segment based on a set of filter conditions.
- Get Segment by ID: Fetches a specific segment (File or Filter) by its ID.
- Update Filter Segment: Updates an existing filter segment by its ID.
Cohort Sync
The Cohort Sync API allows you to synchronize cohorts or audiences created in your own ecosystem directly with MoEngage. This server-to-server integration enables you to add or remove users from custom segments dynamically, ensuring your marketing campaigns always target the most relevant audience.- Automated Segment Creation: Automatically creates a custom segment in MoEngage if it doesn’t already exist.
- Dynamic Membership: Real-time updates to segments allow scheduled campaigns to engage the latest set of users.
- No Middleware Needed: Direct server-to-server calls remove the need for manual CSV uploads or hosting external URLs.
- Increased Efficiency: Ideal for segment operations involving smaller subsets of users.
- Sync Cohort Members: Adds or removes users from a custom segment.
These API endpoints do not currently support Team-level scoping. All segments generated using these calls will be assigned to the Default Team automatically.
FAQs
Filter-Based Segments
How can I generate the payload for segment creation?
How can I generate the payload for 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 segment I created earlier but didn't save?
How do I get the ID of a segment I created earlier but didn't save?
Use the List 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?
Why am I getting a 409 Conflict error even with a different name?
Both the name and the definition (filters) of a 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?
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?
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?
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?
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.
Manage Segments
What is the benefit of archiving a segment instead of deleting it?
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.
Cohort Sync
What is the difference between Cohort Sync API and the File Segment API?
What is the difference between Cohort Sync API and the File Segment API?
The Cohort Sync API enables the creation of segments without needing separate files or CSVs, eliminating the requirement for a separate path or URL as seen in the File Segment API. Segment creation can be initiated by making a direct server-to-server call, eliminating the additional steps required for generating user files.
When is it recommended to use the Cohort Sync API?
When is it recommended to use the Cohort Sync API?
The Cohort Sync API is ideal for segments or segment operations involving fewer users.
Does the Cohort Sync API create new users?
Does the Cohort Sync API create new users?
The Cohort Sync API does not create new users in MoEngage. Instead, it resolves existing users in MoEngage based on predefined user identifiers and assigns them to the corresponding custom segment created through Cohort Sync.