File Segment API

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:

Request Headers

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

Header Type Description
Content-Type {"Content-Type": "application/json"} Set the Content-Type header to application/JSON for using the Data API.
Database MOE-DBNAME Set the database from which the data is available.
Authorization {"Authorization": "Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U="} Basic authentication is used for access control.

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 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
API_Authentication_RevampedUI.png

Authentication is performed using a client like Postman as follows:

df440da-f0c37fd-postman_new_sample.png

 

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

HTTP Status Code Response Reason
200 - OK Everything worked as expected.
202 - Accepted Request accepted for the required operation.
400 - Bad Request Request not accepted due to missing a required parameter.
The reason is passed in the description field.
401 - Unauthorized Signature is not valid.
404 - Entity not found The custom segment mentioned in the request does not exist.
409 - Conflict The request conflicts with another request.
429 - Too Many Requests The number of requests or the rate of requests exceeds the allowed limit.
500, 502, 503, 504 - Server Errors Something went wrong on MoEngage.

Limits

info

Note

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.

Rate Limit Name Rate Limit
total active segment The limit of the total number of active custom segments at a time for a client is 1000.
file_segment ops per hour The total number of file segment operations(which are create-segment/add-users/remove-users) per hour per client allowed is 10.
file_segment ops per day The total number of file segment operations(which are create-segment/add-users/remove-users) per day per client allowed is 100.
file_segment users per day The total number of users that can be uploaded via the File segment is limited to 2 million per day.
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.
info

Note

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

Create File Segment

API Endpoint

URL
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

Parameter Mandatory Description
name Yes The name of the custom segment. The name should be unique across all segments.
attribute_name Yes Name of the user attribute on which the segment is created.
For registered users, use ID (to indicate customer id) or any other unique attribute which uniquely identifies the user. For example, for Anonymous (not registered) users use email, mobile number, or any other identifier as the anonymous user identifier.
attribute_type Yes The type is string or double based on the type of attribute_name. For double attribute_type, the attribute values should be within 64-bit signed numeric values, that is [-9223372036854775808, 9223372036854775807]
file_url Yes CSV file from URL should be downloadable without authorization.
expiry_time Yes Segment expiry time in days.
 - All existing users are dropped from the created custom segment after the expiry time.
 - The custom segment is archived after expiry time.
callback_url No Callback URL to receive the result of segment creation.
emails No List of email ids to receive segment creation response.

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

info

Note

  • The attribute names should be separated by new lines. 
  • CSV should be a single column. CSV size should be less than 150MB.
  • Values should not end with a comma (,) For example, values in a row should be abcd and not abcd,
  • Values should not have duplicate, special characters. For string values use abcd and not "abcd". String value can not be a#bc.
  • File should not have empty rows or empty columns.
  • A user attribute value must uniquely identify a single user. If an attribute value identifies multiple users (e.g. a city attribute with the value 'London' may have many users) these multiple users may get mapped to a single attribute, become part of the segment, and may block other users from being included in the segment.
    For example, if you upload 5 emails and the first email matches with 3 users, the rest 4 emails match with one user each. In this case, the system will randomly pick 5 users to be added to the file segment. The system does this processing in batches of 2000.
  • Sample File Link

Response

Status Code Request State Description Response Body
HTTP 202 Success File-segment creation request accepted. { "message": "File-segment creation request accepted", "success": true, "cs_name": <custom_segment_unique_name> }
HTTP 401 Failure Authentication or Authorization Failure. Invalid key or Secretor Database Name or Authorization Header. { "title": "Authentication required", "description": <message> }
HTTP 409 Failure File-segment creation attempt with duplicate name. { "title": "Resource not created", "description": "Name already exists : <custom_segment_name>" }
HTTP 429 Failure The number of requests or the rate of requests exceeds the allowed limit. { "title": "Too Many Requests", "description": <appropriate message> }
HTTP 5xx Failure Server issue { "title": "Internal Server Error", ... }

Example

HTTP
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

Success Failure-1 Failure-2 Failure-3
{
"db_name": "test_db",
"segment_name": "test_segment_name",
"request_id": "d5a263c4ef1198ae3d8496c0460f570f",
"values_found":80 ,
"values_processed": 70,
"user_count": 60,
"status": 201
}
info

Note - Segment Processing & 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.

 

Add users to file segment

API Endpoint

URL
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

Parameter Mandatory Description
name Yes Name of the custom segment to which the users are added.
attribute_name Yes Name of the user attribute on which the segment is added.
For registered users, use ID (to indicate customer id) or any other unique attribute which uniquely identifies the user. For example, for Anonymous (not registered) users use email, mobile number, or any other identifier as the anonymous user identifier.
attribute_type Yes The type is string or double based on type of attribute_name. For double attribute_type, the attribute values should be within 64-bit signed numeric values, that is [-9223372036854775808, 9223372036854775807]
file_url Yes URL of the CSV file.
- The attribute names should be separated by new lines.
- CSV size should be less than 150MB.
- CSV should be downloadable without authorization.
callback_url No Callback URL to receive the result of updated segment.
emails No List of email ids to receive segment response.

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

Response

Status Code Request State Description Response Body
HTTP 202 Success File-segment creation request accepted. { "message": "File-segment user-add request accepted", "success": true, "cs_name": <custom_segment_unique_name> }
HTTP 400 Failure Invalid file-segment request(invalid payload format). { "title": "Invalid Request", "description": <message> }
HTTP 401 Failure Authentication or Authorization Failure. Invalid key or Secretor Database Name or Authorization Header. { "title": "Authentication required", "description": <message> }
HTTP 404 Failure The custom-segment name used in the request does not exist. { "title": "Entity Not Found", "description": "Custom segment not found with the given name: <custom_segment_unique_name>" }
HTTP 429 Failure The number of requests or the rate of requests exceeds the allowed limit. { "title": "Too Many Requests", "description": <appropriate message> }
HTTP 5xx Failure Server issue { "title": "Internal Server Error", ... }

Example

HTTP
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

URL
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

Parameter Mandatory Description
name Yes Name of the custom segment from which the users are removed.
attribute_name Yes Name of the user attribute on which the segment is removed.
For registered users, use ID (to indicate customer id) or any other unique attribute which uniquely identifies the user. For example, for Anonymous (not registered) users use email, mobile number, or any other identifier as the anonymous user identifier.
attribute_type Yes The type is string or double based on type of attribute_name. For double attribute_type, the attribute values should be within 64-bit signed numeric values, that is [-9223372036854775808, 9223372036854775807]
file_url Yes URL of the CSV file.
- The attribute names should be separated by new lines.
- CSV size should be less than 150MB.
- CSV should be downloadable without authorization.
callback_url No Callback URL to receive the result of segment deletion.
emails No List of email ids to receive segment deletion response.

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

Response

Status Code Request State Description Response Body
HTTP 202 Success File-segment creation request accepted. { "message": "File-segment user-remove request accepted", "success": true, "cs_name": <custom_segment_unique_name> }
HTTP 400 Failure Invalid file-segment request(invalid payload format). { "title": "Invalid Request", "description": <message> }
HTTP 401 Failure Authentication or Authorization Failure. Invalid key or Secretor Database Name or Authorization Header. { "title": "Authentication required", "description": <message> }
HTTP 404 Failure The custom-segment name used in the request does not exist. { "title": "Entity Not Found", "description": "Custom segment not found with the given name: <custom_segment_unique_name>" }
HTTP 429 Failure The number of requests or the rate of requests exceeds the allowed limit. { "title": "Too Many Requests", "description": <appropriate message> }
HTTP 5xx Failure Server issue { "title": "Internal Server Error", ... }

Example

HTTP
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

URL
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

Parameter Mandatory Description
name Yes Name of the custom segment from which all the previous users are removed and new users are added.
attribute_name Yes Name of the user attribute on which the segment is removed.
For registered users, use ID (to indicate customer id) or any other unique attribute which uniquely identifies the user. For example, for Anonymous (not registered) users use email, mobile number, or any other identifier as the anonymous user identifier.
attribute_type Yes The type is string or double based on type of attribute_name. For double attribute_type, the attribute values should be within 64-bit signed numeric values, that is [-9223372036854775808, 9223372036854775807]
file_url Yes URL of the CSV file.
- The attribute names should be separated by new lines.
- CSV size should be less than 150MB.
- CSV should be downloadable without authorization.
callback_url No Callback URL to receive the result of segment deletion.
emails No List of email ids to receive segment deletion response.

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

Response

Status Code Request State Description  
HTTP 202 Success Replace users request accepted. {
"message": "File-segment user-replace request accepted",
"success": true,
"cs_name": <custom_segment_unique_name>
}
HTTP 400 Failure Invalid file-segment request(invalid payload format). {
"title": "Invalid Request",
"description":
}
HTTP 401 Failure Authentication or Authorization Failure. Invalid key or Secretor Database Name or Authorization Header {
"title": "Authentication required",
"description":
}
HTTP 404 Failure The custom-segment name used in the request does not exist. {
"title": "Entity Not Found",
"description": "Custom segment not found with the given name: <custom_segment_unique_name>"
}
HTTP 429 Failure The number of requests or the rate of requests exceeds the allowed limit. {
"title": "Too Many Requests",
"description": ,
"actual_count": ,
"limit":
}
HTTP 5XX Failure Server issue {
"title": "Internal Server Error",
...
}

Example

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

Note

  1. Replace users API drops all the existing user of the custom segment and add new users which are provided in the file URL.
  2. Only the newly added users are counted towards the daily file_segment_user limit.

Archive Custom Segment

API Endpoint

URL
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 Body

Parameter Mandatory Description
name Yes The name of the custom segment to be archived.

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

Response

Status Code Request State Description Response Body
HTTP 202 Success File-segment creation request accepted. { "message": "Successfully archived the custom segment", "success": true, "cs_name": <custom_segment_unique_name> }
HTTP 400 Failure Invalid file-segment request(invalid payload format). { "title": "Invalid Request", "description": <message> }
HTTP 401 Failure Authentication or Authorization Failure. Invalid key or Secretor Database Name or Authorization Header. { "title": "Authentication required", "description": <message> }
HTTP 404 Failure The custom-segment name used in the request does not exist. { "title": "Entity Not Found", "description": "Custom segment not found with the given name: <custom_segment_unique_name>" }
HTTP 5xx Failure Server issue { "title": "Internal Server Error", ... }

Example

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

Note

All the users from the archived file custom segment dropped after 30 days of archival.

UnArchive Custom Segment

API Endpoint

URL
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 Body

Parameter Mandatory Description
name Yes Name of the custom segment not archived.

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

Response

Status Code Request State Description Response Body
HTTP 202 Success File-segment creation request accepted. { "message": "Successfully unarchived the custom segment", "success": true, "cs_name": <custom_segment_unique_name> }
HTTP 400 Failure Invalid file-segment request(invalid payload format). { "title": "Invalid Request", "description": <message> }
HTTP 401 Failure Authentication or Authorization Failure. Invalid key or Secretor Database Name or Authorization Header. { "title": "Authentication required", "description": <message> }
HTTP 404 Failure The custom-segment name used in the request does not exist. { "title": "Entity Not Found", "description": "Custom segment not found with the given name: <custom_segment_unique_name>" }
HTTP 5xx Failure Server issue { "title": "Internal Server Error", ... }

Example

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

Previous

Next

Was this article helpful?
0 out of 1 found this helpful

How can we improve this article?