> ## 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.
# Create File Segment
> This API creates a new file segment from a CSV file URL.
* 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.
#### 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. |
**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.
#### 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. |
## OpenAPI
````yaml /api/custom-segments/custom-segments.yaml post /v2/custom-segments/file-segment
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'
security:
- basicAuth: []
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: |
Archived segments will not be shown beyond 180 days.
- 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. |
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
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:
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:
'{$request.body#/callback_url}':
post:
summary: Segment Processing Callback (v2)
description: >-
A webhook sent to your `callback_url` when a v2 file segment
processing job is complete.
requestBody:
description: Result of the segment processing job.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CallbackV2'
responses:
'200':
description: >-
OK. Acknowledges receipt of the callback. Your endpoint
should return this.
method: post
type: path
path: '{$request.body#/callback_url}'
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 segment being processed.
cs_id:
type: string
description: The unique identifier of the segment.
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) Number of rows present in the uploaded file.
values_processed:
type: integer
description: >-
(Success only) Number of values processed from values_found. Values
with corrupted or empty data are skipped.
user_count:
type: integer
description: >-
(Success only) Number of users found in MoEngage from the processed
values and 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.
description:
type: string
description: A detailed, human-readable explanation of the error.
BaseSegmentRequestV2:
type: object
properties:
name:
type: string
description: Name of the 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: >
Authentication is done via Basic Auth. This requires a base64-encoded
string of your credentials in the format 'username:password'.
- **Username**: Use your MoEngage workspace ID (also known as the App
ID). You can find it in the MoEngage dashboard at **Settings** >
**Account** > **APIs** > **Workspace ID (earlier app id)**.
- **Password**: Use your API Key, which you can find within the **Data**
tile.
For more information on authentication and getting your credentials,
refer
[here](https://www.moengage.com/docs/api/introduction#getting-your-credentials).
````