Update Custom Segment API

This API is used to update a custom segment by specifying its custom segment id.

API Endpoint

API Endpoint
PATCH https://api-0X.moengage.com/v3/custom-segments/{id:str}

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.

Authentication

The API request will be authenticated through Basic Authentication. Basic Authentication sends a Base64-encoded string containing your username and password with every API request. It encodes a 'username:password' string in Base64 and appends the encoded string with 'Basic '. This string is included in the authorization header as shown below:

{"Authorization":"Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U="}

The username and password details can be obtained from the MoEngage Dashboard. We've revamped the settings UI in the Dashboard. If you're using the API for the first time, follow these steps for the revamped and old UIs:

Revamped UI

  1. Navigate to Settings -> Account -> APIs.
  2. Click Generate Key in the Data tile in the API Keys section, and click Save.
  3. Use the Workspace ID as the username and the Data API Key as the password to generate the authentication header.

Old UI

  1. Navigate to Settings -> APIs -> DATA API Settings.
  2. Click Generate Key.
  3. Click Save on the Data APIs settings section. 
  4. Use the DATA API ID as the username and the DATA API KEY as the password to generate the authentication header.

Request Parameters

Key Required Type Description

id

Required

String

This parameter represents the id of the custom filter segment provided in the response of create custom segment request.

Request Headers

Key Required Sample Values Description

Content-Type

Required

{"Content-Type": "application/json"}

Set the Content-Type header to application/json.

Authorization

Required

{"Authorization": "Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U=="}

This authentication parameter, used for access control, must be passed along with the request. To generate the authentication header, refer to Authentication.

MOE-APPKEY Required

{“MOE-APPKEY”: “APP ID”}

This is the APP ID of your MoEngage account. You can find your MoEngage APP ID in the following navigation on the Dashboard:

Revamped UI: Settings -> Account -> APIs -> App ID

Old UI: Settings -> API -> General Settings -> DATA API

Request Body

Key Required Values Description
name Optional String

This field contains the name of the custom segment to be created; it should be unique across all custom segments.

included_filters Required JSON Object

This field contains the filtering criteria used for segmentation. The users satisfying this set of filters will be a part of the segment.

Example:

"included_filters": { 

     "filter_operator": <operator_name>,

      "filters": [ Array of JSON Objects]

}

Depending on the filter type and filter criteria, the payload format will vary. For more information, refer to Included Filters Object.

updated_by Optional(but recommended) String

This field contains the email id of the user updating the custom segment (In the case of API, can be something like admin@companyemail.com)

Included Filters Object

The included_filters contains information about the filters used to create the custom segment. It contains the following fields:

  • filter_operator - This is an Enum(String) that contains the logical operator (logical AND and logical OR operators) used to group the filters. Allowed Values: and, or. This is a mandatory field.
  • filters - This array contains the list of filters to be combined using the filter operator. The types of filters that can be combined are user attributes-based filters and action-based filters (with or without attributes). This is a mandatory field.

The following filter types are available:

Response

Key Data Type Description
response_id String This field contains the unique response id corresponding to the current request. This field is present in the case of both successful and failed requests.
type String This field contains the type of resource referenced in the current request. Default value: custom_segment
data JSON Object

This field contains information about the custom segment created for the request. This field is present in the response only for successful requests.

Structure of data object:

"data": {

    "name": "<custom_segment_name>",

    "id": "<custom_segment_id>",

    "created_time": "<creation_timestamp>",

    "updated_time": "updation_timestamp",

    "type": "ELASTIC_SEARCH", 

    "source": "API",

    "description": "<description of custom segment>"

     "included_filters": { 

         "filter_operator": <operator_name>,

          "filters": [ Array of JSON Objects]

     }

}

For more information, refer to the response payload.

error JSON Object

This field contains the reason for the request's failure.

Structure:

 "error": {

    "code": "<error_code>", 

    "message": "<error_message>" 

}

The error object contains the following fields:

  • code - This field contains the error code that provides a brief explanation of the error and is a String. For example, 400 - Invalid Request, 401- Authentication required, and so on. This field is present in the response only in the case of errors.
  • message - This field describes why the request has failed and is a String. For example, in the case of 401 errors, the following message will be present: 'APP_SECRET key mismatch. Please login to the dashboard to verify key'.

Response Payload

Key Data Type Description
created_time String (datetime ISO Format) This field contains the time of custom-segment creation. This field is present in the response only for successful requests.
updated_time String (datetime ISO Format) This field contains the time of custom-segment update. The updated time can change due to internally running services too. This field is present in the response only for successful requests.
type Enum(String)

This field contains a fixed value and is used for internal purposes. Value of field: ELASTIC_SEARCH

This field is present in the response only for successful requests.

source Enum(String)

This field contains the name of the custom-segment creation source and has a fixed value for internal use. Value of field: API

This field is present in the response only for successful requests.

description String This field contains the textual description summarising the custom-segment definition. This field is present in the response only for successful requests.
included_filters JSON Object This field contains the filter criteria for custom segment creation (the included_filters section in the request payload). This field is present in the response only for successful requests.

Response Codes

Status Code Request State Description

200

Success

This response is returned when the request is processed successfully. 

400

Bad Request

This response is returned when the required parameters are missing from the request or when the provided parameters are invalid.

401

Authorization Failure

This response is returned when the authorization fails due to incorrect values for the APP KEY/ HTTP Auth Header.

409

API SECRET not configured

This response is returned when the authorization fails due to the APP SECRET key not being set on the Dashboard.

413

Unsupported media type

This response is returned when the number of filters nested, or referenced filters in the query exceed the allowed limit.

429

Rate Limit Breach

This response is returned when the number of requests per minute has exceeded the rate limit.

5xx

Internal Server Error

This response is returned when the system runs into an unexpected error.

Rate Limit

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

Sample cURL Request

cURL
curl --location --request PATCH 'https://api-0X.moengage.com/v3/custom-segments/63d8cec0c085939e6c1ab727' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U=' \
--header 'MOE-APPKEY: EXAMPLE_APP_KEY_ID' \
--data-raw '{
    "name": "segment_example_name",
    "included_filters": {
        "filter_operator": "and",
        "filters": [
            {
                "filter_type": "user_attributes",
                "name": "Name",
                "data_type": "string",
                "operator": "is",
                "value": "chandan",
                "negate": false,
                "case_sensitive": false
            }
        ]
    },
    "updated_by": "eample_email@mycompany.com"
}'

Sample Response

200 400 401 403 404 409 412 413 429 500
{
    "data": {
        "name": "your custom-segment name",
        "id": "your 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 Feb 15, 2023 and Feb 24, 2023",
        "included_filters": {
            "filter_operator": "and",
            "filters": [
                {
                    "filter_type": "user_attributes",
                    "name": "Subscription Status 19Dec_7",
                    "data_type": "string",
                    "operator": "is",
                    "value": "active",
                    "value1": "",
                    "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"
}

Postman Collections

We have made it easy for you to test the APIs. Click here to view it in Postman.

Previous

Next

Was this article helpful?
0 out of 0 found this helpful

How can we improve this article?