> ## Documentation Index
> Fetch the complete documentation index at: https://moengage-sdk-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Create File Segment
> Creates a new Custom File Segment from a CSV file URL.
If your file is private, you should whitelist [these IPs](https://help.moengage.com/hc/en-us/articles/35329024618772-A-Guide-to-MoEngage-IP-Whitelisting-Mechanism#h_01JNGJNR5F141E7KRK89YW1X8H) to provide access only to MoEngage for the file.
Check the data center and API endpoint [mapping page here](https://help.moengage.com/hc/en-us/articles/360057030512-Data-Centers-in-MoEngage#01G5DQVXGT2KZMXTJPF77QPJ25).
## Limits
The limit of 1000 custom file segments is calculated only for the file segments that are active. Most of our customers utilize only 30-40% of this limit at any given point.
| Rate Limit Name | Rate Limit |
| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
| total active segment | The limit of the total number of active custom 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, please get in touch with support) |
| 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. |
## Notes
### Limits
* 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.
### 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 & Availability
As soon as the request is received at the MoEngage system, MoEngage creates a custom segment with zero users. After this, the file is processed and users are added to the custom segment. If the created custom segment is queried in between the file processing, it will show zero or partial user count.
## OpenAPI
````yaml /api/custom-segments/custom-segments.yaml post /v2/custom-segments/file-segment
openapi: 3.0.3
info:
title: MoEngage Custom Segments API
description: >
Use the MoEngage Custom 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 Custom Segments.
version: '3.0'
servers:
- url: https://api-{dc}.moengage.com
description: MoEngage API Endpoint
variables:
dc:
description: Your account's Data Center (e.g., 01, 02, 03).
default: '01'
enum:
- '01'
- '02'
- '03'
- '04'
- '05'
security:
- basicAuth: []
tags:
- name: Custom Segments - File
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 Custom File Segment API to:
* Create a new Custom File Segment
* Add Users to an existing Custom Segment
* Remove Users from an existing Custom Segment
* Replace Users from an existing Custom Segment
- name: Custom Segments - Lifecycle
description: >
Archiving and unarchiving through APIs makes it easy to retrieve and reuse
custom 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: |
Archived segments will not be shown beyond 180 days.
- name: Custom Segments - Filters
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 custom
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. |
## FAQs
You can simply generate the payload from the MoEngage dashboard. Log in to the MoEngage dashboard and navigate to the **Test & Debug** -> **Segment Payload section**. Choose your filters and click on **Generate Payload**.
You can use the LIST Custom Segment API with the name query param filter to get the id of the custom segment.
Both the name and the definition of a custom segment are unique. If the definition of the custom segment in the request matches an existing segment, we return a conflict 409 error.
In the case of 409 Conflict, we return a conflicting name/id in the response payload. You can check the payload to get the existing custom segment with the same definition.
paths:
/v2/custom-segments/file-segment:
post:
tags:
- Custom Segments - File
summary: Create File Segment
description: Creates a new Custom 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
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
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:
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'
components:
schemas:
CreateSegmentRequestV2:
description: Schema for creating a new file segment.
allOf:
- $ref: '#/components/schemas/BaseSegmentRequestV2'
- type: object
properties:
expiry_time:
type: integer
format: int32
description: >-
Segment expiry time in days. The segment is archived after this
time.
required:
- expiry_time
ApiResponseSuccessV2:
type: object
properties:
message:
type: string
description: The status message of the request.
success:
type: boolean
example: true
description: Indicates if the request was accepted.
cs_name:
type: string
description: The unique name of the custom segment being processed.
CallbackV2:
type: object
description: >-
The payload sent to the callback URL. The structure depends on the
processing status.
properties:
db_name:
type: string
description: The database name.
example: test_db
segment_name:
type: string
description: The name of the segment.
example: test_segment_name
request_id:
type: string
description: The unique ID of the request.
example: d5a263c4ef1198ae3d8496c0460f570f
status:
type: integer
description: >-
The HTTP status code indicating the outcome (e.g., 201 for success,
400/500 for failure).
example: 201
values_found:
type: integer
description: (Success only) Total number of identifiers found in the file.
values_processed:
type: integer
description: (Success only) Number of identifiers successfully processed.
user_count:
type: integer
description: (Success only) Number of users added to the segment.
error_message:
type: string
description: (Failure only) A description of the error.
required:
- db_name
- segment_name
- request_id
- status
ApiErrorV2:
type: object
properties:
title:
type: string
description: A short title for the error.
BaseSegmentRequestV2:
type: object
properties:
name:
type: string
description: Name of the custom segment. Must be unique for creation.
attribute_name:
type: string
description: >-
Name of the user attribute to use as an identifier (e.g., 'ID',
'email').
attribute_type:
type: string
description: The data type of the attribute_name.
enum:
- string
- double
file_url:
type: string
format: uri
description: A public, downloadable URL to a single-column CSV file.
callback_url:
type: string
format: uri
description: Callback URL to receive the result of segment processing.
emails:
type: array
items:
type: string
format: email
description: List of email IDs to receive segment processing response.
required:
- name
- attribute_name
- attribute_type
- file_url
responses:
401_FileSegmentError:
description: Unauthorized. Authentication or Authorization Failure.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorV2'
example:
title: Authentication required
description:
409_FileSegmentConflict:
description: Conflict. File-segment creation attempt with duplicate name.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorV2'
example:
title: Resource not created
description: 'Name already exists : '
429_FileSegmentRateLimit:
description: >-
Too Many Requests. The number or rate of requests exceeds the allowed
limit.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorV2'
example:
title: Too Many Requests
description:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >
Basic Authentication using your **Workspace ID** (as username) and
**Data API Key** (as password) from the MoEngage Dashboard.
````