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.

​
Rate Limits

Rate Limit NameRate Limit
total active segmentThe limit of the total number of active custom 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 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.

​
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 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.

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 custom 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.

Response

Everything worked as expected.