Create and manage file-based segments (upload, add, remove, replace users) and filter-based segments built from event and attribute conditions, plus archive/unarchive operations and cohort audience synchronization from partner platforms.
openapi: 3.0.3
info:
title: MoEngage Segments API
description: |
Use the MoEngage Segments API to create, update, and manage your file and filter segments.
- **v2 API:** Manage File Segments and segment lifecycle (Archive/Unarchive).
- **v3 API:** Create, read, update, and list filter-based Segments.
version: '3.0'
servers:
- url: https://api-{dc}.moengage.com
description: MoEngage API Endpoint
variables:
dc:
description: "The ‘dc’ in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. You can find your DC number and replace the value of ‘dc’ in the URL by referring to the DC and API endpoint mapping [here](/api/introduction#data-centers). Your MoEngage Data Center (DC) can be 01, 02, 03, 04, 05, 06, or 101."
default: '01'
tags:
- name: File Segments
description: |
If you need to create segments by importing a large number of users, we recommend utilising the File segment API. This API allows you to easily generate a file segment by initiating a call to the file segment API endpoint. To proceed, you will need to compile a CSV file containing the relevant users (ensuring that the users are already present in MoEngage). It is essential to provide the public path of the file, which allows for downloading and identification of users in order to successfully create the file segment.
Use the File Segment API to:
* Create a new file segment
* Add users to an existing segment
* Remove users from an existing segment
* Replace users from an existing segment
- name: Manage Segments
description: |
Archiving and unarchiving through APIs makes it easy to retrieve and reuse segments whenever required for purposes such as A/B testing, maintaining regulatory compliance, and improving system performance.
You can access the archived segments and utilize them to analyze and market campaigns without the need to recreate them from scratch.
x-mint:
content: |
<Warning>
Archived segments will not be shown beyond 180 days.
</Warning>
- name: Filter Segments
description: |
If you need to create a segment based on the events or actions performed by your users on your application or website, the recommended approach is to use the filter segment API. With this API, you can create a segment by specifying the desired filter conditions.
The filter segment API supports various operations, including create, update, get, and list, allowing you to effectively manage your segments based on specific criteria.
x-mint:
content: |
## Authentication
Authentication is performed using Basic Auth. You must also provide the `MOE-APPKEY` header.
## Request Headers
| Key | Required | Description |
| :--- | :--- | :--- |
| `Content-Type` | Yes | Set to `application/json`. |
| `Authorization` | Yes | Basic Auth. `{"Authorization": "Basic Base64_ENCODED_WORKSPACEID_APIKEY="}` |
| `MOE-APPKEY` | Yes | Your MoEngage App ID. Found in Settings -> Account -> APIs -> App ID. |
security:
- basicAuth: []
paths:
/v2/custom-segments/file-segment:
post:
tags:
- File Segments
summary: Create File Segment
description: This API creates a new file segment from a CSV file URL.
operationId: createFileSegment
parameters:
- name: Content-Type
in: header
description: Select the file content type.
required: true
schema:
type: string
default: text/csv
enum:
- text/csv
- application/csv
- application/vnd.ms-excel
- text/plain
- application/octet-stream
- binary/octet-stream
- name: Database
in: header
description: Set the database from which the data is available (MOE-DBNAME).
required: false
schema:
type: string
x-mint:
content: |
<Note>
- If your file is private, you should whitelist [these IPs](/user-guide/settings/account/security/ip-whitelisting-in-moengage) to provide access only to MoEngage for the file.
- This API endpoint does not currently support Team-level scoping. All segments generated using this call will be assigned to the Default Team automatically.
</Note>
#### Rate Limits
| Rate Limit Name | Rate Limit |
| :--- | :--- |
| total active segment | The limit of the total number of active segments at a time for a client is 1000. |
| file_segment ops per hour | The total number of file segment operations (create/add/remove) per hour per client allowed is 10. |
| file_segment ops per day | The total number of file segment operations (create/add/remove) per day per client allowed is 100. |
| file_segment users per day | The total number of users uploaded via the File segment is limited to 2 million per day. (This limit is customizable, contact the MoEngage Support team). |
| file_size_limit | The size of the file from which the segment is created/updated. For each request, the file size limit is 150 MB. |
<Note>
**Notes**
* Breaching the limits will reject the request.
* Per hour and per day limits will consider the calculation based on the last hour and last 24 hrs respectively.
* The limit of 1000 active segments is calculated across all types of 'active segments'. Most of our customers utilise only 30-40% of this limit at any given point.
</Note>
#### CSV File Requirements
* The attribute names should be separated by new lines.
* CSV should be a single column and less than 150MB.
* Values should not end with a comma (e.g., `abcd` not `abcd,`).
* Values should not have duplicates or special characters (e.g., `abcd` not `"abcd"` or `a#bc`).
* File should not have empty rows or columns.
* A user attribute value must uniquely identify a single user.
* [Sample File Link](https://app-cdn.moengage.com/assets/Sample_GAIDs.csv)
#### Segment Processing and Availability
As soon as the request is received at the MoEngage system, MoEngage creates a segment with zero users. After this, the file is downloaded, processed, and users are added to the segment. If the segment is queried during processing, it will show zero or partial user count.
There is no fixed processing timeout. If the initial file download fails, MoEngage automatically retries before reporting a failure via the callback.
#### Callback Payload
When file processing completes, MoEngage sends a `POST` request to your `callback_url`. Your server must return an HTTP `200` to acknowledge receipt.
The payload structure depends on the processing outcome.
**Success (status: 201)**
| Field | Type | Description |
| :--- | :--- | :--- |
| `db_name` | string | The MoEngage database name for your workspace. |
| `segment_name` | string | The name of the processed segment. |
| `request_id` | string | Unique identifier for this processing request. |
| `status` | integer | `201` on successful processing. |
| `values_found` | integer | Number of rows present in the uploaded file. |
| `values_processed` | integer | Number of values processed from `values_found`. Values with corrupted or empty data are skipped. |
| `user_count` | integer | Number of users found in MoEngage from the processed values and added to the segment. |
**Failure (status: 400 or 500)**
| Field | Type | Description |
| :--- | :--- | :--- |
| `db_name` | string | The MoEngage database name for your workspace. |
| `segment_name` | string | The name of the segment for which processing failed. |
| `request_id` | string | Unique identifier for this processing request. |
| `status` | integer | `400` for client errors (for example, file too large, download failed), `500` for server errors. |
| `error_message` | string | Description of what caused the processing to fail. |
requestBody:
description: Configuration for the new file segment.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSegmentRequestV2'
example:
name: "custom_segment_unique_name"
attribute_name: "unique_identifier"
attribute_type: "string"
file_url: "https://s3.amazonaws.com/Sample_GAIDs.csv"
callback_url: "http://example.com/moengage-callback"
emails: ["user1@example.com", "user2@example.com"]
expiry_time: 30
responses:
'200':
description: Everything worked as expected.
content:
application/json:
example: "No example response body available for this status code."
'202':
description: Request accepted for processing.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ApiResponseSuccessV2'
- $ref: '#/components/schemas/CallbackV2'
examples:
api_response:
summary: API Response - Success
description: Immediate response from the API when the request is accepted.
value:
message: "File-segment creation request accepted"
success: true
cs_name: "custom_segment_unique_name"
cs_id: "6a1d8c3292d59351fe910b13"
callback_success:
summary: Callback - Success
description: Callback sent to your callback_url when segment processing completes successfully.
value:
db_name: "test_db"
segment_name: "test_segment_name"
request_id: "d5a263c4ef1198ae3d8496c0460f570f"
values_found: 80
values_processed: 70
user_count: 60
status: 201
'400':
description: Bad Request. Request not accepted due to missing a required parameter. The reason is passed in the description field.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ApiErrorV2'
- $ref: '#/components/schemas/CallbackV2'
examples:
api_invalid_request:
summary: API Response - Invalid Request
description: Immediate response from the API when the request is invalid.
value:
title: "Invalid Request"
description: "<message>"
callback_file_size:
summary: Callback - Failure (File Size)
description: Callback sent to your callback_url when file size exceeds the limit.
value:
db_name: "test_db"
segment_name: "test_segment_name"
request_id: "d5a263c4ef1198ae3d8496c0460f570f"
status: 400
error_message: "File size cannot be greater than 150MB. Created custom_segment contains 0 users."
callback_download_failed:
summary: Callback - Failure (Download Failed)
description: Callback sent to your callback_url when file download fails.
value:
db_name: "test_db"
segment_name: "test_segment_name"
request_id: "d5a263c4ef1198ae3d8496c0460f570f"
status: 400
error_message: "File download failed. Created custom_segment contains 0 users."
'401':
$ref: '#/components/responses/401_FileSegmentError'
'409':
$ref: '#/components/responses/409_FileSegmentConflict'
'429':
$ref: '#/components/responses/429_FileSegmentRateLimit'
'500':
description: Server Errors. Something went wrong on MoEngage.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ApiErrorV2'
- $ref: '#/components/schemas/CallbackV2'
examples:
api_internal_error:
summary: API Response - Internal Server Error
description: Immediate response from the API when an internal server error occurs.
value:
title: "Internal Server Error"
callback_internal_error:
summary: Callback - Failure (Internal Server Error)
description: Callback sent to your callback_url when segment processing encounters an internal error.
value:
db_name: "test_db"
segment_name: "test_segment_name"
request_id: "d5a263c4ef1198ae3d8496c0460f570f"
status: 500
error_message: "Internal Server Error. Contact MoEngage Team."
'502':
description: Bad Gateway. Something went wrong on MoEngage.
content:
application/json:
example: "No example response body available for this status code."
'503':
description: Service Unavailable. Something went wrong on MoEngage.
content:
application/json:
example: "No example response body available for this status code."
'504':
description: Gateway Timeout. Something went wrong on MoEngage.
content:
application/json:
example: "No example response body available for this status code."
callbacks:
segmentCreationCallback:
$ref: '#/components/callbacks/segmentProcessingCallback'
/v2/custom-segments/file-segment/add-users:
put:
tags:
- File Segments
summary: Add Users to File Segment
description: This API adds a list of users from a CSV file to an existing file segment.
operationId: addUsersToFileSegment
parameters:
- name: Content-Type
in: header
description: Select the file content type.
required: true
schema:
type: string
default: text/csv
enum:
- text/csv
- application/csv
- application/vnd.ms-excel
- text/plain
- application/octet-stream
- binary/octet-stream
- name: Database
in: header
description: Set the database from which the data is available (MOE-DBNAME).
required: false
schema:
type: string
x-mint:
content: |
<Note>
This API endpoint does not currently support Team-level scoping. All segments generated using this call will be assigned to the Default Team automatically.
</Note>
requestBody:
description: Details of the segment to update and the file URL of users to add.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSegmentRequestV2'
example:
name: "custom_segment_unique_name"
"cs_id": "<unique cs id>"
attribute_name: "unique_identifier"
attribute_type: "string"
file_url: "https://s3.amazonaws.com/Sample_GAIDs_add.csv"
callback_url: "http://example.com/moengage-callback"
emails: ["user1@example.com"]
responses:
'202':
description: Request accepted for processing.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponseSuccessV2'
example:
message: "File-segment user-add request accepted"
success: true
cs_name: "custom_segment_unique_name"
"cs_id": "<unique cs id>"
'400':
description: Bad Request. Invalid payload format.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorV2'
example:
title: "Invalid Request"
description: "<message>"
'401':
$ref: '#/components/responses/401_FileSegmentError'
'404':
$ref: '#/components/responses/404_FileSegmentNotFound'
'429':
$ref: '#/components/responses/429_FileSegmentRateLimit'
'500':
description: Server Errors. Something went wrong on MoEngage.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorV2'
example:
title: "Internal Server Error"
/v2/custom-segments/file-segment/remove-users:
put:
tags:
- File Segments
summary: Remove Users from File Segment
description: This API removes a list of users from a CSV file from an existing file segment.
operationId: removeUsersFromFileSegment
parameters:
- name: Content-Type
in: header
description: Select the file content type.
required: true
schema:
type: string
default: text/csv
enum:
- text/csv
- application/csv
- application/vnd.ms-excel
- text/plain
- application/octet-stream
- binary/octet-stream
- name: Database
in: header
description: Set the database from which the data is available (MOE-DBNAME).
required: false
schema:
type: string
x-mint:
content: |
<Note>
This API endpoint does not currently support Team-level scoping. All segments generated using this call will be assigned to the Default Team automatically.
</Note>
requestBody:
description: Details of the segment to update and the file URL of users to remove.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSegmentRequestV2'
example:
name: "custom_segment_unique_name"
"cs_id": "<unique cs id>"
attribute_name: "unique_identifier"
attribute_type: "string"
file_url: "https://s3.amazonaws.com/Sample_GAIDs_remove.csv"
callback_url: "http://example.com/moengage-callback"
emails: ["user1@example.com"]
responses:
'202':
description: Request accepted for processing.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponseSuccessV2'
example:
message: "File-segment user-remove request accepted"
success: true
cs_name: "custom_segment_unique_name"
"cs_id": "<unique cs id>"
'400':
description: Bad Request. Invalid payload format.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorV2'
example:
title: "Invalid Request"
description: "<message>"
'401':
$ref: '#/components/responses/401_FileSegmentError'
'404':
$ref: '#/components/responses/404_FileSegmentNotFound'
'429':
$ref: '#/components/responses/429_FileSegmentRateLimit'
'500':
description: Server Errors. Something went wrong on MoEngage.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorV2'
example:
title: "Internal Server Error"
/v2/custom-segments/file-segment/replace:
put:
tags:
- File Segments
summary: Replace Users from File Segment
description: This API replaces all users in an existing file segment with a new list of users from a CSV file.
operationId: replaceUsersInFileSegment
parameters:
- name: Content-Type
in: header
description: Select the file content type.
required: true
schema:
type: string
default: text/csv
enum:
- text/csv
- application/csv
- application/vnd.ms-excel
- text/plain
- application/octet-stream
- binary/octet-stream
- name: Database
in: header
description: Set the database from which the data is available (MOE-DBNAME).
required: false
schema:
type: string
x-mint:
content: |
<Note>
**Notes:**
* This API drops all existing users from the segment and adds the new users provided in the File URL.
* Only the newly added users are counted towards the daily file segment user limit.
* This API does not currently support Team-level scoping. All segments generated using this call will be assigned to the Default Team automatically.
</Note>
requestBody:
description: Details of the segment to update and the file URL of users to replace with.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSegmentRequestV2'
example:
name: "custom_segment_unique_name"
attribute_name: "unique_identifier"
"cs_id": "<unique cs id>"
attribute_type: "string"
file_url: "https://s3.amazonaws.com/Sample_GAIDs_replace.csv"
callback_url: "http://example.com/moengage-callback"
emails: ["user1@example.com"]
responses:
'202':
description: Request accepted for processing.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponseSuccessV2'
example:
message: "File-segment user-replace request accepted"
success: true
cs_name: "custom_segment_unique_name"
"cs_id": "<unique cs id>"
'400':
description: Bad Request. Invalid payload format.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorV2'
example:
title: "Invalid Request"
description: "<message>"
'401':
$ref: '#/components/responses/401_FileSegmentError'
'404':
$ref: '#/components/responses/404_FileSegmentNotFound'
'429':
$ref: '#/components/responses/429_FileSegmentRateLimit'
'500':
description: Server Errors. Something went wrong on MoEngage.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorV2'
example:
title: "Internal Server Error"
/v2/custom-segments/archive:
patch:
tags:
- Manage Segments
summary: Archive Segment
description: This API archives an existing segment (File or Filter). Archiving and unarchiving through APIs makes it easy to retrieve and reuse segments whenever required for purposes such as A/B testing, maintaining regulatory compliance, and improving system performance. You can access the archived segments and utilize them to analyze and market campaigns without the need to recreate them from scratch.
operationId: archiveCustomSegment
x-mint:
content: |
<Warning>
Archived segments will not be shown beyond 180 days.
</Warning>
<Note>
This API endpoint does not currently support Team-level scoping. All segments generated using this call will be assigned to the Default Team automatically.
</Note>
requestBody:
description: The name of the segment to be archived.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentNameRequestV2'
example:
name: "custom_segment_unique_name"
"cs_id": "<unique cs id>"
responses:
'202':
description: Segment archive request accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponseSuccessV2'
example:
message: "Successfully archived the custom segment"
success: true
cs_name: "custom_segment_unique_name"
"cs_id": "<unique cs id>"
'400':
$ref: '#/components/responses/400_FileSegmentError'
'401':
$ref: '#/components/responses/401_FileSegmentError'
'404':
$ref: '#/components/responses/404_FileSegmentNotFound'
'500':
$ref: '#/components/responses/5XX_FileSegmentError'
/v2/custom-segments/unarchive:
patch:
tags:
- Manage Segments
summary: Unarchive Segment
description: This API unarchives an existing segment, making it active again.
operationId: unarchiveCustomSegment
x-mint:
content: |
<Note>
This API endpoint does not currently support Team-level scoping. All segments generated using this call will be assigned to the Default Team automatically.
</Note>
requestBody:
description: The name of the segment to be unarchived.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentNameRequestV2'
example:
name: "custom_segment_unique_name"
"cs_id": "<unique cs id>"
responses:
'202':
description: Segment unarchive request accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponseSuccessV2'
example:
message: "Successfully unarchived the custom segment"
success: true
cs_name: "custom_segment_unique_name"
"cs_id": "<unique cs id>"
'400':
$ref: '#/components/responses/400_FileSegmentError'
'401':
$ref: '#/components/responses/401_FileSegmentError'
'404':
$ref: '#/components/responses/404_FileSegmentNotFound'
'500':
$ref: '#/components/responses/5XX_FileSegmentError'
/v3/custom-segments:
get:
tags:
- Filter Segments
summary: List Segments
description: This API lists all segments. You can optionally filter segments by an exact name match.
operationId: listCustomSegments
x-mint:
content: |
<Note>
This API endpoint does not currently support Team-level scoping. All segments generated using this call will be assigned to the Default Team automatically.
</Note>
#### Rate Limit
The rate limit is 50 request/minute, 200 requests/hour, and 1000 requests/day.
parameters:
- $ref: '#/components/parameters/AppKeyHeader'
- $ref: '#/components/parameters/SegmentNameQuery'
responses:
'200':
$ref: '#/components/responses/200_SegmentListV3'
'400':
$ref: '#/components/responses/400_FilterSegmentError'
'401':
$ref: '#/components/responses/401_FilterSegmentError'
'429':
$ref: '#/components/responses/429_FilterSegmentRateLimitOnly'
'500':
$ref: '#/components/responses/500_FilterSegmentError'
post:
tags:
- Filter Segments
summary: Create Filter Segment
description: This API creates a new segment based on a set of filter conditions.
operationId: createFilterSegment
x-mint:
content: |
<Note>
This API endpoint does not currently support Team-level scoping. All segments generated using this call will be assigned to the Default Team automatically.
</Note>
#### Generate Request from Dashboard
To simplify the request generation, MoEngage has added an option in the dashboard where you can specify filters as per your requirement and generate the payload.
1. Login to the MoEngage dashboard.
2. Click **Test & Debug** at the lower left in the side panel.
3. Click **Segment Payload**.
4. Specify the name for your segment payload and provide the required filters.
5. Click **Generate payload** button.
#### Rate Limit
The rate limit is 50 request/minute, 200 requests/hour, and 1000 requests/day.
parameters:
- $ref: '#/components/parameters/AppKeyHeader'
requestBody:
description: The filter definition for the new segment.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FilterSegmentRequestV3'
example:
name: "segment_example_name"
included_filters:
filter_operator: "and"
filters:
- filter_type: "user_attributes"
name: "Name"
data_type: "string"
operator: "in"
value: ["Chandan", "Kumar"]
negate: false
case_sensitive: false
responses:
'201':
$ref: '#/components/responses/201_SegmentCreatedV3'
'400':
$ref: '#/components/responses/400_FilterSegmentError'
'401':
$ref: '#/components/responses/401_FilterSegmentError'
'409':
$ref: '#/components/responses/409_FilterSegmentError'
'413':
$ref: '#/components/responses/413_FilterSegmentError'
'429':
$ref: '#/components/responses/429_FilterSegmentError'
'500':
$ref: '#/components/responses/500_FilterSegmentError'
/v3/custom-segments/{id}:
get:
tags:
- Filter Segments
summary: Get Segment by ID
description: This API fetches a specific segment (File or Filter) by its ID.
operationId: getCustomSegment
x-mint:
content: |
<Note>
This API endpoint does not currently support Team-level scoping. All segments generated using this call will be assigned to the Default Team automatically.
</Note>
#### Rate Limit
The rate limit is 100 requests/minute, 1000 requests/hour, and 4000 requests/day.
parameters:
- $ref: '#/components/parameters/AppKeyHeader'
- $ref: '#/components/parameters/SegmentIdPath'
responses:
'200':
$ref: '#/components/responses/200_SegmentListV3'
'400':
$ref: '#/components/responses/400_FilterSegmentError'
'401':
$ref: '#/components/responses/401_FilterSegmentError'
'429':
$ref: '#/components/responses/429_FilterSegmentRateLimitOnly'
'500':
$ref: '#/components/responses/500_FilterSegmentError'
patch:
tags:
- Filter Segments
summary: Update Filter Segment
description: This API updates an existing filter segment by its ID.
operationId: updateFilterSegment
parameters:
- $ref: '#/components/parameters/AppKeyHeader'
- $ref: '#/components/parameters/SegmentIdPath'
x-mint:
content: |
<Note>
This API endpoint doe
# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/moengage/refs/heads/main/openapi/moengage-custom-segments-openapi.yml