Skip to main content
POST
/
v2
/
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 NameRate Limit
total active segmentThe limit of the total number of active segments at a time for a client is 1000.
file_segment ops per hourThe total number of file segment operations (create/add/remove) per hour per client allowed is 10.
file_segment ops per dayThe total number of file segment operations (create/add/remove) per day per client allowed is 100.
file_segment users per dayThe 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_limitThe 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)
FieldTypeDescription
db_namestringThe MoEngage database name for your workspace.
segment_namestringThe name of the processed segment.
request_idstringUnique identifier for this processing request.
statusinteger201 on successful processing.
values_foundintegerNumber of rows present in the uploaded file.
values_processedintegerNumber of values processed from values_found. Values with corrupted or empty data are skipped.
user_countintegerNumber of users found in MoEngage from the processed values and added to the segment.
Failure (status: 400 or 500)
FieldTypeDescription
db_namestringThe MoEngage database name for your workspace.
segment_namestringThe name of the segment for which processing failed.
request_idstringUnique identifier for this processing request.
statusinteger400 for client errors (for example, file too large, download failed), 500 for server errors.
error_messagestringDescription 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.