Skip to main content
POST
/
v3
/
custom-segments
Create Filter Segment
curl --request POST \
  --url https://api-{dc}.moengage.com/v3/custom-segments \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'MOE-APPKEY: <moe-appkey>' \
  --data '
{
  "name": "segment_example_name",
  "included_filters": {
    "filter_operator": "and",
    "filters": [
      {
        "filter_type": "user_attributes",
        "name": "Name",
        "data_type": "string",
        "operator": "in",
        "value": [
          "Chandan",
          "Kumar"
        ],
        "negate": false,
        "case_sensitive": false
      }
    ]
  }
}
'
{
  "data": {
    "name": "custom-segment name",
    "id": "custom-segment id",
    "created_time": "2022-12-20T06:21:44.112000",
    "updated_time": "2022-12-20T06:21:44.160000",
    "type": "ELASTIC_SEARCH",
    "source": "API",
    "description": "Subscription Status 19Dec_7  is active  (case insensitive) AND Has executed Email Sent atleast 1 time in-between Jan 05, 2021 and Jan 08, 2021",
    "included_filters": {
      "filter_operator": "and",
      "filters": [
        {
          "filter_type": "user_attributes",
          "name": "Subscription Status 19Dec_7",
          "data_type": "string",
          "operator": "in",
          "value": [
            "active"
          ],
          "negate": false,
          "case_sensitive": false
        },
        {
          "filter_type": "actions",
          "attributes": {
            "filter_operator": "and",
            "filters": []
          },
          "executed": true,
          "primary_time_range": {
            "type": "between",
            "value": "2023-02-15T00:00:00.000Z",
            "value1": "2023-02-24T23:59:59.999Z",
            "value_type": "absolute",
            "period_unit": "days"
          },
          "action_name": "MOE_EMAIL_SENT",
          "execution": {
            "count": 1,
            "type": "atleast"
          }
        }
      ]
    }
  },
  "response_id": "cNjnTEJw",
  "type": "custom_segment"
}

​
Generate Request from Dashboard

To simplify the request generation, MoEngage has added an option in the dashboard where you can specify filters as per your requirement and generate the payload.
  1. Login to the MoEngage dashboard.
  2. Click Test & Debug at the lower left in the side panel.
  3. Click Segment Payload.
  4. Specify the name for your segment payload and provide the required filters.
  5. Click Generate payload button.

​
Rate Limit

The rate limit is 50 request/minute, 200 requests/hour, and 1000 requests/day.

Authorizations

​
Authorization
string
header
required

Authentication is done via Basic Auth. This requires a base64-encoded string of your credentials in the format 'username:password'.

  • Username: Use your MoEngage workspace ID (also known as the App ID). You can find it in the MoEngage dashboard at Settings > Account > APIs > Workspace ID (earlier app id).
  • Password: Use your API Key, which you can find within the Data tile.

For more information on authentication and getting your credentials, refer here.

Headers

​
MOE-APPKEY
string
required

This is the Workspace ID of your MoEngage account that must be passed with the request. You can find it in the MoEngage dashboard at Settings > Account > APIs > Workspace ID (earlier app id).

Body

application/json

The filter definition for the new segment.

Request schema for creating a filter-based custom segment.

​
name
string
required

A unique name for the custom segment.

​
included_filters
object
required

The filtering criteria used for segmentation. Users satisfying this set of filters will be part of the segment.

Response

Custom segment created successfully. Returns the newly created segment details including its unique ID, filter definition, and metadata.

Response schema for filter segment operations (create/update).

​
data
object

Information about the custom segment.

​
response_id
string

A unique identifier for this API response.

​
type
string

The type of resource referenced in the response.

Example:

"custom_segment"