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: application/json' \
  --header 'MOE-DBNAME: <moe-dbname>' \
  --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
}
'

{
  "message": "File-segment creation request accepted",
  "success": true,
  "cs_name": "custom_segment_unique_name",
  "cs_id": "6a1d8c3292d59351fe910b13"
}

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: application/json' \
  --header 'MOE-DBNAME: <moe-dbname>' \
  --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
}
'

{
  "message": "File-segment creation request accepted",
  "success": true,
  "cs_name": "custom_segment_unique_name",
  "cs_id": "6a1d8c3292d59351fe910b13"
}

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.

承認

Authorization

string

header

必須

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.

ヘッダー

MOE-DBNAME

string

必須

The MoEngage database name (db_name) from which the data is available.

ボディ

application/json

Configuration for the new file segment.

Schema for creating a new file segment.

name

string

必須

Name of the segment. Must be unique for creation.

attribute_name

string

必須

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

attribute_type

enum<string>

必須

The data type of the attribute_name.

利用可能なオプション:

string,

double

file_url

string<uri>

必須

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

expiry_time

integer<int32>

必須

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.

コールバック

POST

{$request.body#/callback_url}segmentCreationCallback

ボディ

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

The database name.

例:

"test_db"

segment_name

string

The name of the segment.

例:

"test_segment_name"

request_id

string

The unique ID of the request.

例:

"d5a263c4ef1198ae3d8496c0460f570f"

status

integer

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

例:

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.

レスポンス

200

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

レスポンス

Request accepted for processing.

API Response
Processing Callback

Response returned when a file segment request is accepted for processing.

message

string

The status message of the request.

success

boolean

Indicates if the request was accepted.

例:

true

cs_name

string

The unique name of the segment being processed.

cs_id

string

The unique identifier of the segment being processed.

APIドキュメント

エンドポイント

Create File Segment

Rate Limits

CSV File Requirements

Segment Processing and Availability

Callback Payload

承認

ヘッダー

ボディ

コールバック

ボディ

レスポンス

レスポンス