Custom File Segment API

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

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:

  1. Navigate to Settings > APIs > DATA API Settings.
  2. Click Generate Key
  3. 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:

df440da-f0c37fd-postman_new_sample.png

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

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 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.
 
  • Breaching of 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 Name of the custom segment, should be unique across all segments.
attribute_name Yes Name of the user attribute on which the segment is created.
For registered users, use 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.
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.

 
  • 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".
  • The attribute value must uniquely identify a user. If an attribute value identifies multiple users (for example, a city attribute with the value London may have many users), these users will become part of the segment and remove the right user from getting 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 only process the first 5 users (3+1+1) and the last 2 users (1+1) will not 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

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
}

 

 

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

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" }
Was this article helpful?
0 out of 0 found this helpful