List Custom Segments API

This API is used to fetch a custom segment by specifying its name.

API Endpoint

API Endpoint

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.


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




This parameter represents the name of the custom filter segment and will be used to retrieve the custom filter segment whose name is an exact match. The query parameter should be URL encoded and passed.

Example: - If the name is ‘my custom segment’, the query parameter would be encoded and sent as follows.

Request Headers

Key Required Sample Values Description



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

Set the Content-Type header to application/json.



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



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


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_segment1_name>",

    "id": "<custom_segment1_id>",

    "created_time": "<creation_timestamp>",

    "type": "ELASTIC_SEARCH", 

    "source": "API"



    "name": "<custom_segment2_name>",

    "id": "<custom_segment2_id>",

    "created_time": "<creation_timestamp>",

    "type": "ELASTIC_SEARCH", 

    "source": "API"




For more information, refer to the request payload.

error JSOn Object

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


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

Request Payload

The request payload contains the list of custom segments fetched. Each element in the list contains the following fields:

  • name: This field contains the name of the custom segment
  • id: This field contains the id of the custom segment
  • created_time: This field contains the custom segment creation time
  • type: This field contains the type of the custom segment. This is used to classify custom segments logically into different categories.
  • source: This field contains the source of custom segment creation.

Response Codes

Status Code Request State Description



This response is returned when the request is processed successfully. An empty list is returned in case of no match.


Bad Request

This response is returned when the required parameter is missing from the request or when the provided param is invalid.


Authorization Failure

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


Rate Limit Breach

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


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 --location --request GET '' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U=' \

Sample Response

200 400 401 429 500
Sample Response for a successful request
    "data": [
            "name": "api_test_7",
            "id": "6388a97a02adb9071ca84ce9",
            "created_time": "2022-12-01T13:17:46.409000",
            "type": "ELASTIC_SEARCH",
            "source": "API"
    "response_id": "WYanfieM",
    "type": "custom_segment"

Postman Collections

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



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

How can we improve this article?