Custom File Segment API

Custom File Segment API helps create, update, archive, and unarchive custom segments as CSV using an API.

Custom File Segment API Endpoints

MoEngage supports multiple data centers with different dashboards and API endpoints. When you sign up with MoEngage, you will be assigned a particular data center and the relevant dashboard is displayed. Use the data API endpoints associated with the data center.

For more information about your data center, contact [email protected]

You can find out which data center you are assigned to when you log in to the dashboard. The following table describes the dashboard URL and API endpoint associated with the data center.

Two versions of the dashboard URL and API endpoints are provided by MoEngage.

Data Centers and API Endpoints

Syntax

The API requires authentication and the response format for the API is in JSON.

https://api-01.moengage.com/v2/custom-segments/file-segment
https://api-02.moengage.com/v2/custom-segments/file-segment
https://api-03.moengage.com/v2/custom-segments/file-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:

 1. Navigate to Settings > APIs > [DATA API Settings](https://app.moengage.com/v3/#/settings/1/0).

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

Authentication is performed using a client like Postman as follows:

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.

📘

Note

  • 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

Syntax

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

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.

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.

📘

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".
  • The attribute value must uniquely identify a user. If an attribute value identifies multiple users (for example, a city attribute with 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 be 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

POST https://api.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": ["[email protected]", "[email protected]"],
  "expiry_time": 30
}

📘

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

Syntax

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

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

PUT https://api.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": ["[email protected]", "[email protected]"]
}

Remove users from File Segment

Syntax

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

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

PUT https://api.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": ["[email protected]", "[email protected]"]
}

Replace users from File Segment

Syntax

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

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

PUT https://api.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": ["[email protected]", "[email protected]"]
}

📘

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

Syntax

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

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.moengage.com/v2/custom-segments/archive
Body
{
  "name": "custom_segment_unique_name"
}

Unarchive Custom Segment

Syntax

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

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.moengage.com/v2/custom-segments/unarchive
Body
{
  "name": "custom_segment_unique_name"
}

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