File Segment API

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

Basic authentication sends a Base64-encoded string containing username and password for all API requests.

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

Username and password are available at Settings > APIs > DATA API Settings.

Do the following when you are using the API for the first-time authentication:

Navigate to Settings > APIs > DATA API Settings.
Click Generate Key
Save the details on the Data APIs settings page. User name - DATA API ID Password - DATA API KEY

For example, basic Authentication encodes a 'username:password' using base64 and prepends it with the string 'Basic '. The string is passed in the authorization header as follows:
{"Authorization":"Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U="}

bcfd9ca-d205ad9-B33zNd8vQFCkugDwITCz_Screen_Shot_2016-06-10_at_6.28.23_pm.png

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

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

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

CSV should be a single column.
Values should not end with a comma (,) For example, values in a row should be abcd and not abcd,
Values should not be enclosed in quotes. For string values use abcd and not "abcd".
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.

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

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

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

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

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

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

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

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

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 Replace users API drops all the existing user of the custom segment and add new users which are provided in the file URL. Only the newly added users are counted towards the daily file_segment_user limit.

Archive Custom Segment

API Endpoint

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

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

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

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