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 Custom File Segment API to:

• Create a new Custom File Segment
• Add Users to an existing Custom Segment
• Remove Users from an existing Custom Segment
• Replace Users from an existing Custom Segment

Request Headers

Request headers are applicable to create, update, archive, or unarchive the custom segment.

Authentication

Authentication applies to create, update, archive, or unarchive APIs.

The API request will be authenticated through Basic Authentication. Basic Authentication sends a Base64-encoded string containing your username and password with every API request. It encodes a 'username:password' string in Base64 and appends the encoded string with 'Basic '. This string is included in the authorization header as shown below:

{"Authorization: Basic Base64_ENCODED_APPKEY_APIKEY=="}

The username and password details can be obtained from the MoEngage Dashboard. We've revamped the settings UI in the Dashboard. If you're using the API for the first time, follow these steps for the revamped and old UIs:

Revamped UI

1. Navigate to Settings -> Account -> APIs.
2. Click Generate Key in the Data tile in the API Keys section, and click Save.
3. Use the Workspace ID as the username and the Data API Key as the password to generate the authentication header.

Old UI

1. Navigate to Settings -> APIs -> DATA API Settings.
2. Click Generate Key.
3. Click Save on the Data APIs settings section. 
4. Use the DATA API ID as the username and the DATA API KEY as the password to generate the authentication header.

Revamped Settings Old Settings

Authentication is performed using a client like Postman as follows:

If your file is private, you should whitelist these IPs to provide access only to MoEngage for the file.
DC-1 (US) - 184.72.243.80
DC-2 (EU) - 18.195.110.23
DC-3 (AP) - 3.6.251.95

Check the data center and API endpoint mapping page here.

Response Codes

Limits

Create File Segment

API Endpoint

POST https://api-0X.moengage.com/v2/custom-segments/file-segment

Each customer is hosted on a different data center, you can find your data center number (value of X), by checking the data center and API endpoint mapping page here.

Request Body

Use callback, emails, or both for better visibility and end-to-end integration capability.

Response

Example

POST https://api-0X.moengage.com/v2/custom-segments/file-segment
Body
{
  "name": "custom_segment_unique_name",
  "attribute_name": "unique_identifier",
  "attribute_type": "string",
  "file_url": "https://s3.amazonaws.com/Sample_GAIDs.csv",
  "callback_url": "http://localhost:5000",
  "emails": ["abc@gmail.com", "xyz@wrx.com"],
  "expiry_time": 30
}

Callback Sample Body

{
"db_name": "test_db",
"segment_name": "test_segment_name",
"request_id": "d5a263c4ef1198ae3d8496c0460f570f",
"values_found":80 ,
"values_processed": 70,
"user_count": 60,
"status": 201
}

{
"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."
}

{
"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."
}

{
"db_name": "test_db",
"segment_name": "test_segment_name",
"request_id": "d5a263c4ef1198ae3d8496c0460f570f",
"status": 500,
"error_message": "Internal Server Error. Contact MoEngage Team."
}

Add users to file segment

API Endpoint

PUT https://api-0X.moengage.com/v2/custom-segments/file-segment/add-users

Each customer is hosted on a different data center, you can find your data center number (value of X), by checking the data center and API endpoint mapping page here.

Request Headers

Use callback, emails, or both for better visibility and end-to-end integration capability.

Response

Example

PUT https://api-0X.moengage.com/v2/custom-segments/file-segment/add-users
Body
{
  "name": "custom_segment_unique_name",
  "attribute_name": "unique_identifier",
  "attribute_type": "string",
  "file_url": "https://s3.amazonaws.com/Sample_GAIDs.csv",
  "callback_url": "http://localhost:5000",
  "emails": ["abc@gmail.com", "xyz@wrx.com"]
}

Remove users from File Segment

API Endpoint

PUT https://api-0X.moengage.com/v2/custom-segments/file-segment/remove-users

Each customer is hosted on a different data center, you can find your data center number (value of X), by checking the data center and API endpoint mapping page here.

Request Body

Use callback, emails, or both for better visibility and end-to-end integration capability.

Response

Example

PUT https://api-0X.moengage.com/v2/custom-segments/file-segment/remove-users
Body
{
  "name": "custom_segment_unique_name",
  "attribute_name": "unique_identifier",
  "attribute_type": "string",
  "file_url": "https://s3.amazonaws.com/Sample_GAIDs.csv",
  "callback_url": "http://localhost:5000",
  "emails": ["abc@gmail.com", "xyz@wrx.com"]
}

Replace users from File Segment

API Endpoint

PUT https://api-0X.moengage.com/v2/custom-segments/file-segment/replace

Each customer is hosted on a different data center, you can find your data center number (value of X), by checking the data center and API endpoint mapping page here.

Request Body

Use callback, emails, or both for better visibility and end-to-end integration capability.

Response

Example

PUT https://api-0X.moengage.com/v2/custom-segments/file-segment/replace
Body
{
  "name": "custom_segment_unique_name",
  "attribute_name": "unique_identifier",
  "attribute_type": "string",
  "file_url": "https://s3.amazonaws.com/Sample_GAIDs.csv",
  "callback_url": "http://localhost:5000",
  "emails": ["abc@gmail.com", "xyz@wrx.com"]
}