Create File Segment

curl --request POST \
  --url https://api-{dc}.moengage.com/v2/custom-segments/file-segment \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "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": [
    "[email protected]",
    "[email protected]"
  ],
  "expiry_time": 30
}
'

"No example response body available for this status code."

POST

custom-segments

file-segment

Create File Segment

curl --request POST \
  --url https://api-{dc}.moengage.com/v2/custom-segments/file-segment \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "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": [
    "[email protected]",
    "[email protected]"
  ],
  "expiry_time": 30
}
'

"No example response body available for this status code."

If your file is private, you should whitelist these IPs 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

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.

Authorizations

Authorization

string

header

required

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.

Headers

Content-Type

enum<string>

default:text/csv

required

Select the file content type.

Available options:

text/csv,

application/csv,

application/vnd.ms-excel,

text/plain,

application/octet-stream,

binary/octet-stream

Database

string

Set the database from which the data is available (MOE-DBNAME).

Body

application/json

Configuration for the new file segment.

Schema for creating a new file segment.

name

string

required

Name of the segment. Must be unique for creation.

attribute_name

string

required

Name of the user attribute to use as an identifier (e.g., 'ID', 'email').

attribute_type

enum<string>

required

The data type of the attribute_name.

Available options:

string,

double

file_url

string<uri>

required

A public, downloadable URL to a single-column CSV file.

expiry_time

integer<int32>

required

Segment expiry time in days. The segment is archived after this time.

callback_url

string<uri>

Callback URL to receive the result of segment processing.

emails

string<email>[]

List of email IDs to receive segment processing response.

Callbacks

POST

{$request.body#/callback_url}segmentCreationCallback

Body

application/json

Result of the segment processing job.

The payload sent to the callback URL. The structure depends on the processing status.

db_name

string

required

The database name.

Example:

"test_db"

segment_name

string

required

The name of the segment.

Example:

"test_segment_name"

request_id

string

required

The unique ID of the request.

Example:

"d5a263c4ef1198ae3d8496c0460f570f"

status

integer

required

The HTTP status code indicating the outcome (e.g., 201 for success, 400/500 for failure).

Example:

201

values_found

integer

(Success only) Number of rows present in the uploaded file.

values_processed

integer

(Success only) Number of values processed from values_found. Values with corrupted or empty data are skipped.

user_count

integer

(Success only) Number of users found in MoEngage from the processed values and added to the segment.

error_message

string

(Failure only) A description of the error.

Response

200

OK. Acknowledges receipt of the callback. Your endpoint should return this.

Response

Everything worked as expected.

Segments Overview Add Users to File Segment

⌘I

​Rate Limits

​CSV File Requirements

​Segment Processing and Availability

​Callback Payload

Authorizations

Headers

Body

Callbacks

Body

Response

Response

Rate Limits

CSV File Requirements

Segment Processing and Availability

Callback Payload