Create Filter Segment

This API creates a new segment based on a set of filter conditions.

POST /v3/custom-segments

Create Filter Segment

cURL

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

201

Example

{
  "data": {
    "name": "segment name",
    "id": "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"
}

This API endpoint does not currently support Team-level scoping. All segments generated using this call will be assigned to the Default Team automatically.

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

name · string · required

A unique name for the segment.

included_filters · object · required

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

Show child attributes

Response

201

application/json

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

Show child attributes

response_id · string

A unique identifier for this API response.

type · string

The type of resource referenced in the response.

Example:

"custom_segment"