> ## 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.

# Segments Overview

> Create, update, and manage your file-based, filter-based, and cohort-synced segments.

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.

## 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](/api/file-segments/create-file-segment): Creates a new file segment from a CSV file URL.
* [Add Users to File Segment](/api/file-segments/add-users-to-file-segment): Adds a list of users from a CSV file to an existing file segment.
* [Remove Users from File Segment](/api/file-segments/remove-users-from-file-segment): Removes a list of users from a CSV file from an existing file segment.
* [Replace Users in File Segment](/api/file-segments/replace-users-from-file-segment): Replaces all users in an existing file segment with a new list of users from a CSV file.

<Note>
  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.
</Note>

### Manage Segments (v2)

The Manage Segments API allows you to control the lifecycle of your segments by archiving or unarchiving them.

* [Archive Segment](/api/manage-segments/archive-segment): Archives an existing segment (File or Filter).
* [Unarchive Segment](/api/manage-segments/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](/api/filter-segments/list-segments): Lists all filter segments.
* [Create Filter Segment](/api/filter-segments/create-filter-segment): Creates a new filter segment based on a set of filter conditions.
* [Get Segment by ID](/api/filter-segments/get-segment-by-id): Fetches a specific segment (File or Filter) by its ID.
* [Update Filter Segment](/api/filter-segments/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.

**Endpoint:**

* [Sync Cohort Members](/api/cohort-sync/sync-cohort-members): Adds or removes users from a custom segment.

<Note>
  These API endpoints do not currently support Team-level scoping. All segments generated using these calls will be assigned to the Default Team automatically.
</Note>

## FAQs

### Filter-Based Segments

<AccordionGroup>
  <Accordion title="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**.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="How do I increase the rate limits?">
    Please connect with your account manager.
  </Accordion>
</AccordionGroup>

### File-Based Segments

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Is there a timeout for file processing?">
    No. There is no fixed processing timeout. MoEngage processes the file until it completes successfully or encounters an error, then sends the result to your `callback_url`.
  </Accordion>

  <Accordion title="What happens if the file download fails?">
    If the initial file download fails, MoEngage automatically retries before reporting a failure via the callback. The callback payload will include an `error_message` field describing the failure.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

### Manage Segments

<AccordionGroup>
  <Accordion title="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.
  </Accordion>
</AccordionGroup>

### Cohort Sync

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="When is it recommended to use the Cohort Sync API?">
    The Cohort Sync API is ideal for segments or segment operations involving fewer users.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Postman Collections

Test these endpoints quickly by importing our Postman collections: [File Segments](https://www.postman.com/moengage-dev/api-docs/collection/z8f27qa/moengage-custom-segment-api), [Filter Segments](https://www.postman.com/moengage-dev/api-docs/collection/s16aovr/moengage-custom-segment-filter-based-crud-api-s), and [Cohort Sync](https://www.postman.com/moengage-dev/api-docs/collection/2siizsq/moengage-cohort-audience-sync-revamp?action=share\&creator=3182294) in Postman.