This API is used to fetch a custom segment by specifying its name.
API Endpoint
GET https://api-0X.moengage.com/v3/custom-segments/
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
Basic authentication sends a Base64-encoded string containing username and password for all API requests.
Do the following when you are using the API for the first-time:
- Navigate to Settings > APIs > DATA API Settings.
- Click Generate Key.
- Save the details on the Data APIs settings page. User name - DATA API ID Password - DATA API KEY
For example, basic Authentication encodes a 'username:password' using base64 and prepends it with the string 'Basic'. The string is passed in the authorization header as follows:
{"Authorization":"Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U="}
Request Parameters
Key | Required | Type | Description |
---|---|---|---|
name |
Required |
String |
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 |
Required |
{"Content-Type": "application/json"} |
Set the Content-Type header to application/json. |
Authorization |
Required |
{"Authorization": "Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U=="} |
This is the authentication parameter for access control and needs to be passed along with the request. The APP KEY and API SECRET need to be picked up from the DATA API Settings in MoEngage Dashboard, and a Basic Authorization header needs to be created and set in the header. Navigation: Settings -> API -> General Settings -> DATA API section. For more information, refer to Authentication. |
MOE-APPKEY | Required |
{“MOE-APPKEY”: “APP ID”} |
This is the APP ID of your MoEngage account. The MOE-APPKEY has to be passed along with the request. You can find your MoEngage APP ID in the MoEngage Dashboard API Settings. Navigation: Settings -> APIs -> General Settings -> DATA API Settings section. For more information, refer to Authentication. |
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 request 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:
|
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 |
---|---|---|
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 50 request/minute, 200 requests/hour, and 1000 requests/day.
Sample cURL Request
curl --location --request GET 'https://api-0X.moengage.com/v3/custom-segments?name=example_segment' \
--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.