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
• Archive an existing Custom Segment
• UnArchive an existing Custom Segment.

Request Headerslink

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

Authenticationlink

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 bmF2ZWVua3VtYXI6bW9lbmdhZ2U="}

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 App 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 Codeslink

Limitslink

Create File Segmentlink

API Endpointlink

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 Bodylink

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

Responselink

Examplelink

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 segmentlink

API Endpointlink

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 Headerslink

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

Responselink

Examplelink

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 Segmentlink

API Endpointlink

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 Bodylink

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

Responselink

Examplelink

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 Segmentlink

API Endpointlink

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 Bodylink

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

Responselink

Examplelink

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"]
}

Archive Custom Segmentlink

API Endpointlink

PATCH https://api-0X.moengage.com/v2/custom-segments/archive

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 Bodylink

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

Responselink

Examplelink

PATCH https://api-0X.moengage.com/v2/custom-segments/archive
Body
{
  "name": "custom_segment_unique_name"
}

UnArchive Custom Segmentlink

API Endpointlink

PATCH https://api-0X.moengage.com/v2/custom-segments/unarchive

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 Bodylink

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

Responselink

Examplelink

PATCH https://api-0X.moengage.com/v2/custom-segments/unarchive Body { "name": "custom_segment_unique_name" }