API Endpoint

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

The username and password details can be obtained from the MoEngage Dashboard. If you're using the API for the first time, follow these steps:

Navigate to Settings -> Account -> APIs.
Copy the following details:
- Username: Under Workspace ID (earlier app id), click the copy icon to copy the username.
- Password: In the API keys section, click the copy icon in the Data tile to copy the API key.
Use these details to authenticate the API requests.

Request Parameters

Key	Required	Type	Description
id	Required	String	This parameter represents the ID of the custom segment that will be used to retrieve the custom segment whose ID is an exact match.

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 Base64_ENCODED_WORKSPACEID_APIKEY=="}	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”: “Workspace ID”}	This is the Workspace ID of your MoEngage account. You can find your MoEngage Workspace ID at Settings -> Account -> APIs -> Workspace ID (earlier app id).

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_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 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 the key'.

Response 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
200	Success	This response is returned when the request is processed successfully. An empty list is returned in case of no match.
400	Bad Request	This response is returned when the required parameter is missing from the request or when the provided param is invalid.
401	Authorization Failure	This response is returned when the authorization fails due to incorrect values for the APP KEY/ HTTP Auth Header.
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 100 requests/minute, 1000 requests/hour, and 4000 requests/day.

Sample cURL Request

curl --location --request GET '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'

Sample Response

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

Sample Response for Invalid path parameters
{
    "response_id": "xFyVHeOr",
    "type": "custom_segment",
    "error": {
        "code": "Invalid request",
        "message": "Invalid request format. Please check the documentation to ensure that the request has been formed correctly."
    }
}
Sample Response for Invalid db-name/app-key
{
    "response_id": "FkrgtCVr",
    "type": "custom_segment",
    "error": {
        "code": "Request Error",
        "message": "MoEngage Client not found. Please check values for headers - MOE-APPKEY or MOE-DBNAME"
    }
}

Sample Response for Authentication/Authorization failure
{
    "response_id": "SzFRAzwK",
    "type": "custom_segment",
    "error": {
        "code": "Authentication required",
        "message": "APP_SECRET key mismatch. Please login to the dashboard to verify key"
    }
}
Sample Response for App-Key/DB-Name and Auth Secret mismatch
{
    "response_id": "bUfoyyhN",
    "type": "custom_segment",
    "error": {
        "code": "Authentication required",
        "message": "Invalid APP_KEY used in Authentication Header"
    }
}

Sample Response for Rate Limit Breach
{
    "response_id": "OUUkHvcn",
    "type": "custom_segment",
    "error": {
        "code": "Too Many Requests",
        "message": "API rate limit breached. Current limit: n/m mins"
    }
}

Sample Response for server side errors
{
    "response_id": "HKWwUkvM",
    "type": "custom_segment",
    "error": {
        "code": "Internal Server Error",
        "message": "An unexpected error was encountered while processing this request. Please contact MoEngage Team"
    }
}

Postman Collections

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