1. Developer Guide
  2. API
  3. Campaign API
  4. Get Campaign Details
Get SMS Campaign Details

You can use this API to fetch the list of SMS campaigns with all the current fields and the current status. You can pass multiple filters in this API to fetch a particular campaign.

info

Information

If this API is not enabled for your account, contact your MoEngage Customer Success Manager (CSM) or the Support team to request enablement.

API Endpoint

Method: POST

API Endpoint
https://api-0X.moengage.com/core-services/v1/campaigns/search

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

You can obtain the username and password details from the MoEngage UI.

  1. Navigate to Settings -> Account -> APIs.
  2. 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 Campaign report/Business events/Custom templates tile to copy the API key.
  3. Use these details to authenticate the API requests.

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

This authentication parameter, used for access control, must be passed in the request. To generate the authentication header, refer to Authentication.
MOE-APPKEY Required

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

 This is the workspace ID (earlier APP ID) of your MoEngage workspace. The MOE-APPKEY must be passed in the request. You can find your MoEngage Workspace ID in the MoEngage UI at

Settings -> Account -> APIs -> Workspace ID (earlier app id).

For more information, refer to Authentication.

Request Body

Key Required Values Description
campaign_fields Optional JSON Object This object contains the campaign fields. For more information, refer to Campaign Fields Details.
include_child_campaigns Optional Boolean

This field denotes whether to include child campaigns. By default, the value is false. However, you must pass it as true to fetch the details of periodic child campaigns and flow campaign notes.
include_archive_campaigns Optional Boolean

This field denotes whether to include the archived campaigns. By default, the value is false.
limit Required Numeric

This field denotes the number of campaigns to be displayed on a page. The maximum limit is 15.
page Required Numeric This field denotes the number of pages to display the campaigns based on the limit. For example, if there are 200 campaigns and you set the limit to 10, there will be 20 pages.
request_id Required String This field denotes the request ID for which the campaign is fetched.

Campaign Fields Details

The campaign_fields JSON object contains the following information:

Key Required Values Description
channels Optional Array This field denotes the type of channel. For example, SMS.
created_by Optional Array

This field denotes the Email ID of the user who created the campaign.

Note: The supported value is email ID only.
created_date Optional JSON Object This field denotes the campaign creation date in ISO 8601 format. This object contains the following fields:
  • from_date - This field is of String type and indicates the starting point of the date range in which the campaigns are created.
  • to_date - This field is of String type and indicates the ending point of the date range in which the campaigns are created.

Note: The recommended format is YYYY-MM-DD.
delivery_type Optional Array This field denotes the delivery type of the campaign. Supported values are:
  • ONE_TIME
  • PERIODIC
  • EVENT_TRIGGERED
  • BUSINESS_EVENT_TRIGGERED
id Optional String This field denotes the ID of the campaign.
name Optional String This field denotes the name of the campaign.
status Optional Array This field denotes the status of the campaign. For example, Active.
tags Optional Array This field denotes the tags added in the campaign. 

Response

Key Data Type Description
message JSON Object If the request is successful, this field contains a brief description of its status. For more information, refer to Response Codes.
error JSON Object

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

Structure:

 "error": {

    "code": "<error_code>", 

    "message": "<error_message>",

    "target": "<target>",

    "details": [

         {

             "target": "<target>",

             "message": "<error_message>"

          }

    ],

    "request_id": "<request_id>"

    }

}

The error object contains the following fields:

  • code - This field is of String type and contains the error code that provides a brief explanation of the error. For example, 400 - Bad Request, 401- Authentication required, and so on. This field is present in the response only in the case of errors.
  • message - This field is of String type and describes why the request has failed.
  • target - This field is of String type and denotes the target of the error.
  • details - This object provides the error details and contains the following information:
    • target - This field is of String type and denotes the target of the error.
    • message - This field is of String type and describes why the request has failed.
  • request_id: This field denotes the request ID.

Response Codes

Status Code Request State Description
200 Success This response is returned when the request is processed successfully. For more information, refer to 200 - Success Response.
400 Bad Request This response is returned when the required parameters are missing from the request, or when the provided parameters are invalid, or when a template already exists with the same version, name, or ID.
401 Authentication Failure This response is returned when the authorization parameters are missing in the HTTP Auth Header.
500 Internal Server Error This response is returned when the system runs into an unexpected error.

200 - Success Response

Key Values Description
campaign_id String This field indicates the campaign ID.
status String This field indicates the status of the campaign. For example, Active, Scheduled, Paused, Sent, and Stopped.
basic_details JSON Object This object contains the basic details of the campaign. For more information, refer to Basic Details.
campaign_content JSON Object This object contains the campaign content. For more information, refer to Campaign Content.
campaign_delivery_type String

This field indicates the campaign delivery type. Supported values are:

  • ONE_TIME
  • PERIODIC
  • EVENT_TRIGGERED
  • BUSINESS_EVENT_TRIGGERED
channel String This field indicates the channel. For example, SMS.
created_by String This field indicates the Email of the user who created the campaign.
created_at String This field indicates the time when the campaign was created.
sent_time String This field indicates the time when the campaign was sent.
flow_id String This field indicates the flow ID. It is applicable only for flow campaigns when the include_child_campaign is passed as true.
flow_name String This field indicates the flow name. It is applicable only for flow campaigns when the include_child_campaign is passed as true.
parent_id String

This field denotes the campaign ID of the parent if the include_child_campaign is passed as true. It is applicable only for periodic campaigns.
trigger_condition JSON Object This object contains the trigger condition details. For more information, refer to Trigger Conditions.
segmentation_details JSON Object This object contains the segmentation details. For more information, refer to Segmentation Details.
control_group_details JSON Object This object contains the control group details. For more information, refer to Control Group Details.
scheduling_details JSON Object This object contains the scheduling details. For more information, refer to Scheduling Details.
conversion_group_details JSON Object This object contains the conversion goal details. For more information, refer to Conversion Goal Details.
delivery_controls JSON Object This object contains the delivery control details. For more information, refer to Delivery Controls.
sender_name String This field denotes the sender name configured for this SMS campaign.
connector String This field denotes the connector configured for this SMS campaign.
utm_params JSON Object This object contains the UTM params details. For more information, refer to UTM params.
campaign_audience_limit JSON Object This object contains the campaign audience limit details. For more information, refer to Campaign Audience limit.

Basic Details

The basic_details JSON object contains the following information:

Key Values Description
business_event String

This field denotes the business event to be mapped to the campaign.
name String This field denotes the name of the campaign.
tags Array

This field provides context about the campaigns and describes the nature of the campaign or the campaign's central theme.
team String This field denotes the name of a group of users collaborating on the same campaign. For more information, refer to Teams.
user_attribute_identifier String

This field denotes the user attribute that stores the email address.

MoEngage standard user attribute identifier is MOE_EMAIL_ID. This is a standard attribute where the name is provided by MoEngage and the value is provided by the client.

Campaign Content

The campaign_content JSON object contains the following information:

Key Values Description
content JSON Object This object has the sms object. For more information, refer SMS Details.
locales Array

This field includes locale information. You can send SMS campaigns in multiple languages using locales.
variation_details JSON Object This field includes variation details. For more information, refer to Variation Details.

SMS Details

The sms JSON object contains the following information:

Key Values Description
template_id String

This field denotes the ID of the SMS template.
message String

This field denotes the content of the SMS message.
shorten_and_track_url Array

This field indicates the URLs to be shortened and tracked.
opt_out_status Boolean This field indicates the opt-out status for the SMS campaign.
custom_template_id String

This field denotes the ID of the custom template.
custom_template_version Integer This field denotes the version of the custom template.

Variation Details

The variation_details JSON object contains the following information:

Key Values Description
distribution_type String

This field denotes the distribution type. Supported values are:

  • SHERPA
  • MANUAL
manual_distribution_percentage JSON Object This object denotes the percentage of manual distribution. This object contains the following fields:
  • 0: This field is of String type and indicates the percentage of user category you want to send for the zero variation.
  • 1: This field is of String type and indicates the percentage of user category you want to send for the first variation.
no_of_variations Number This field denotes the number of variations of the campaign.

Trigger Conditions Details

The trigger_condition is used for event-triggered campaigns. This JSON object contains the following information:

Key Values Description
included_filters JSON Object This object denotes the segmentation filters that help you choose the trigger condition for your campaign.
secondary_included_filters JSON Object

This object denotes the segmentation filters that help you choose the secondary trigger condition for your campaign.

Note: Secondary include filters will be used when the secondary events are used in the event-triggered campaigns.
trigger_delay_type String

This field denotes the type of triggered delay. Supported values are:

  • DELAY
  • ASAP

Note: When you pass a DELAY value in this parameter, the following fields are mandatory:

  • trigger_delay_value
  • trigger_delay_granularity
  • trigger_relation
trigger_delay_value Integer This field denotes the value of the triggered delay.
trigger_delay_granularity String

This field denotes the granularity of the triggered delay. Supported values are:

  • DAYS
  • HOURS
  • MINUTES
trigger_relation String

This field denotes the trigger relation with a delay. Supported values are:

  • BEFORE
  • AFTER
trigger_attr JSON Object This object denotes the attribute value of the trigger.

Segmentation Details

The segmentation_details JSON object contains the following information: 

Key Values Description
included_filters JSON Object

This object denotes the details about the defined filter operators and filters for the included filters of your campaign. 
excluded_filters JSON Object

This object denotes the details about the defined filter operators and filters for the excluded filters of your campaign.
is_all_user_campaign Boolean

This field indicates whether all users should be included in the campaign.
send_campaign_to_opt_out_users Boolean

This field indicates if the campaign is sent to users who have opted out.

Control Group Details

The control_group_details JSON object contains the following information:

Key Values Description
is_campaign_control_group_enabled Boolean This field denotes whether the campaign control group is enabled or not.
campaign_control_group_percentage Integer

This field denotes the percentage of users added to an exclusion list.

Note: If is_campaign_control_group_enabled is True, the campaign_control_group_percentage field is required.
is_global_control_group_enabled Boolean This field denotes whether the global control group is enabled or not.

Scheduling Details

The scheduling_details JSON object contains the following information: 

Key Values Description
bts_details  JSON Object This field contains the details about the best time to send. For more information, refer to Best Time to Send (BTS) Details.
delivery_type String

This field denotes the type of delivery schedule for your campaign. Supported values are:

  • ONE_TIME
  • PERIODIC
  • EVENT_TRIGGERED
  • BUSINESS_EVENT_TRIGGERED
start_time String This field denotes the start time for the campaign in ISO 8601 format.
periodic_details JSON Object

This object denotes the periodic details of the campaign. For more information, refer to Periodic Details.
expiry_time String This field denotes the expiry time for the campaign in ISO 8601 format.
user_timezone_details JSON Object This object denotes the user's time zone details. For more information, refer to User Timezone Details.

Best Time to Send (BTS) Details

Best Time to Send (BTS) provides a prescriptive time slot for sending a campaign to the user to increase the chance of interaction or user response. For more information, refer to Best time to send. The bts_details JSON object contains the following information:

Key Values Description
if_user_bts_is_not_available String This field denotes when to send the campaign if the user's best time is not available.
if_user_bts_outside_time_window String This field denotes when to send the campaign if the user's best time is outside this time window.
send_in_bts Boolean This field denotes whether to send a campaign at the best time or not.
window_end_time String This field denotes the window end time. 

User Timezone Details

The user_timezone_details JSON object contains the following information:

Key Values Description
send_if_user_timezone_has_passed Boolean This field denotes whether to send the campaign if the user's time zone has passed.
send_in_user_timezone Boolean This field denotes whether to send the campaign on a specific date and time within the time zone of the user.

Periodic Details

The periodic_details JSON object contains the following information:

Key Values Description
no_of_occurences Number This field denotes the number of occurrences of the campaign.
repeat_frequency Number This field denotes the repeat frequency of the campaign. 
repeat_on_date_of_month Array

This field indicates the date of the month on which the campaign should be repeated.

For example, to send the campaign on the 5th and the 25th of a month, pass 5 and 25.
repeat_on_days_of_week_for_month Array

This field denotes which days of the week for a month the campaign should repeat.

This array contains the following item fields: 

  • week_granularity: This field is of String type and indicates the days on which the campaign should be sent. For example, SECOND, FIRST, and LAST.
  • repeat_on_days_of_week: This field indicates the days of the week on which the campaign should be repeated and is an Array. For example, MONDAY.
repeat_on_days_of_week Array

This field denotes which days of the week the campaign repeats. 

For example, if you wish to send the campaign every Monday and Friday, pass these days in this field as MONDAY and FRIDAY.
sending_frequency String

This field denotes the frequency of sending the campaign. Supported values are:

  •  “DAILY”
  • “MONTHLY”
  • “WEEKLY” 

Conversion Goal Details

The conversion_goal_details JSON object contains the following information:

Key Values Description
attribution_window_in_hours Number This field denotes the attribution window in hours.
goals Array This field has the items object. For more information on its structure, refer to Conversion Goal.

Conversion Goal

The items JSON object contains the following information:

Key Values Description
goal_event_attribute JSON Object This object denotes the goal event attribute. For more information, refer to Goal Event Attributes.
goal_event_name String This field denotes the goal event name.
goal_name String This field denotes the goal name.
is_primary_goal Boolean This field denotes whether this is a primary goal or not.
revenue_attribute String This field denotes the revenue attribute.
revenue_currency String This field denotes the revenue currency.

Goal Event Attributes

The goal_event_attribute JSON object contains the following information:

Key Values Description
condition String This field denotes the condition used while creating a goal. 
is_case_sensitive Boolean This field denotes whether the goal event attribute is case-sensitive or not.
name String This field denotes the name of the goal event attribute.
value String This field denotes the value of the goal event attribute.

Delivery Controls

The delivery_controls JSON object contains the following information: 

Key Values Description
bypass_dnd Boolean This field denotes whether you want to bypass Do Not Disturb (DND). It is required when the campaign is created with an event-triggered delivery type.
campaign_throttle_rpm Number

This field denotes the campaign throttle RPM. It is not applicable when the campaign is created with the following delivery types:

  • device-triggered
  • location-triggered
  • event-triggered.

Sample value: "50000", "70000".

For more information, refer here.
count_for_frequency_capping Boolean This field denotes whether you want to count the channel message sent by a particular Flow for frequency capping.
ignore_frequency_capping Boolean This field denotes whether you want to ignore frequency capping or not.
minimum_delay_between_two_notification_in_hour Numeric This field denotes the minimum delay between two notifications in an hour. It applies to Push campaigns created with event-triggered and device-triggered delivery types.

UTM Parameters

The utm_params JSON object contains the following information:

Key Values Description
utm_source String

This field denotes the source of the traffic. It helps to track where the traffic came from. The source can be a website, app, or link. For example, YouTube, Instagram, and Google.

Note: When you are using the utm_params JSON object, this field is required.
utm_medium String

This field denotes the channel type. It helps to track the channel from where the user came. For example, Push, SMS, Email.

Note: When you are using the utm_params JSON object, this field is required.
utm_campaign String

This field denotes the name of the campaign. It helps to track the performance of a specific campaign. For example, Newyear, Bigbillionday.
utm_term String

This field denotes search terms for paid traffic. It helps to search for the keyword or term that led the audience to visit your site. For example, Mobile+sale.
utm_content String

This field denotes the content. It is the element that differentiates links pointing to the same URL. It helps to identify the exact element on your campaign that was clicked. It is useful for A/B testing. For example, banner, video, product image.
utm_custom String

This field denotes the custom UTM parameter. You can pass a maximum of five custom UTM parameters.

Campaign Audience Limit

The campaign_audience_limit JSON object contains the following information:

Key Values Description
limit Integer This field denotes a numerical threshold for the campaign audience. It specifies the maximum number of times an audience can be included or targeted within the campaign.
metrics String This field denotes the type of measurement or data points that are being tracked or used to evaluate the campaign audience. Examples could include impressions, clicks, conversions, or other relevant performance indicators.
frequency String This field denotes how often the limit and metrics are applied or measured. It could specify a time period (for example, daily, weekly, monthly) or another recurring interval.

Sample cURL Request

The following are sample codes to:

  • Get campaigns by the channel
  • Get campaigns by the campaign name
  • Get campaigns by the campaign ID
  • Get campaigns by the delivery type
  • Get campaigns by the created date
ChannelCampaign Name Campaign ID Delivery Type Created Date 
curl --location 'https://api-0X.moengage.com/core-services/v1/campaigns/search' \
--header 'MOE-APPKEY: {{Workspace_ID or APP_ID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{Authorization_Key}}' \
--data '{
	    "campaign_fields": {
	        "channels": [
	            "SMS"
	        ]
	    },
	    "limit": 15,
	    "page": 1,
	    "request_id": "{{request_id}}"
	}'

Sample Response

200 400 401 500 
{
    "campaign_id": "{{campaign_id}}",
    "status": "Active",
    "basic_details": {
      "business_event": "abc",
      "name": "campaign name",
      "tags": [
        "tag_name1",
        "tag_name2"
      ],
      "team": "team1",
      "user_attribute_identifier": "Mobile Number(Standard)"
    },
    "campaign_content": {
      "content": {
        "locale_name_1": {
          "variation_1": {
            "sms": {
              "template_id": "{{template_id}}",
              "message": "Hi, To get the 20% discount please click on the link https://google.com",
              "shorten_and_track_url": [
                {
                  "url": "https://google.com",
                  "is_click_tracking_enabled": true
                }
              ],
              "opt_out_status": false
            }
          },
          "variation_2": {
            "sms": {
              "custom_template_id": "string",
              "custom_template_version": 0
            }
          }
        },
        "locale_name_2": {
          "variation_1": {
            "sms": {
              "template_id": "{{template_id}}",
              "message": "Hi, To get the 20% discount please click on the link https://google.com",
              "shorten_and_track_url": [
                {
                  "url": "https://google.com",
                  "is_click_tracking_enabled": false
                }
              ],
              "opt_out_status": true
            }
          },
          "variation_2": {
            "sms": {
              "template_id": "{{template_id}}",
              "message": "Hi, To get the 20% discount please click on the link https://google.com",
              "shorten_and_track_url": [
                {
                  "url": "https://google.com",
                  "is_click_tracking_enabled": false
                }
              ],
              "opt_out_status": false
            }
          }
        },
        "default": {
          "variation_1": {
            "sms": {
              "template_id": "{{template_id}}",
              "message": "Hi, To get the 20% discount please click on the link https://google.com",
              "shorten_and_track_url": [
                {
                  "url": "https://google.com",
                  "is_click_tracking_enabled": false
                }
              ],
              "opt_out_status": false
            }
          },
          "variation_2": {
            "sms": {
              "template_id": "{{template_id}}",
              "message": "Hi, To get the 20% discount please click on the link https://google.com",
              "shorten_and_track_url": [
                {
                  "url": "https://google.com",
                  "is_click_tracking_enabled": true
                }
              ],
              "opt_out_status": false
            }
          }
        }
      },
      "locales": [
        "locale_name_1",
        "locale_name_2"
      ],
      "variation_details": {
        "no_of_variations": 2,
        "variation_distribution": {
          "distribution_type": "SHERPA/MANUAL",
          "manual_distribution_percentage": {
            "variation_1": "45",
            "variation_2": "50"
          }
        }
      }
    },
    "sender_name": "test_sender",
    "utm_params": {
      "utm_source": "web",
      "utm_medium": "web2"
    },
    "campaign_audience_limit": {
      "limit": 0,
      "metric": "string",
      "frequency": "string"
    },
    "control_group_details": {
      "campaign_control_group_percentage": "5",
      "is_campaign_control_group_enabled": true,
      "is_global_control_group_enabled": false
    },
    "campaign_delivery_type": "ONE_TIME",
    "channel": "SMS",
    "created_by": "abc@gmail.com",
    "created_at": "2024-05-20 06:04:50.505000",
    "sent_time": "2024-05-20 06:04:50.505000",
    "scheduling_details": {
      "bts_details": {
        "if_user_bts_is_not_available": "SEND_MESSAGE_AT_START_TIME",
        "if_user_bts_outside_time_window": "SEND_MESSAGE_AT_START_OR_END_TIME",
        "send_in_bts": true,
        "window_end_time": "2025-09-01T11:32:12.919Z"
      },
      "delivery_type": "ASAP",
      "expiry_time": "2025-09-01T11:32:12.919Z",
      "periodic_details": {
        "no_of_occurences": 0,
        "repeat_frequency": 0,
        "repeat_on_date_of_month": [
          1,
          12,
          15
        ],
        "repeat_on_days_of_week_for_month": [
          {
            "week_granularity": "SECOND",
            "repeat_on_days_of_week": [
              "MONDAY"
            ]
          }
        ],
        "repeat_on_days_of_week": [
          "MONDAY"
        ],
        "sending_frequency": "DAILY"
      },
      "start_time": "2025-09-01T11:32:12.919Z",
      "user_timezone_details": {
        "send_if_user_timezone_has_passed": true,
        "send_in_user_timezone": true
      }
    },
    "conversion_goal_details": {
      "attribution_window_in_hours": 2,
      "goals": [
        {
          "goal_event_attribute": {
            "condition": "is",
            "is_case_sensitive": true,
            "name": "string",
            "value": "string"
          },
          "goal_event_name": "string",
          "goal_name": "string",
          "is_primary_goal": true,
          "revenue_attribute": "string",
          "revenue_currency": "WDO"
        }
      ]
    },
    "delivery_controls": {
      "bypass_dnd": true,
      "campaign_throttle_rpm": 0,
      "count_for_frequency_capping": true,
      "ignore_frequency_capping": true,
      "minimum_delay_between_two_notification_in_hour": 0
    },
    "segmentation_details": {
      "excluded_filters": {
        "filter_operator": "and",
        "filters": [
          {
            "filter_type": "string",
            "name": "string",
            "data_type": "string",
            "operator": "is",
            "value": "string",
            "negate": true,
            "case_sensitive": true
          }
        ]
      },
      "included_filters": {
        "filter_operator": "and",
        "filters": [
          {
            "filter_type": "string",
            "name": "string",
            "data_type": "string",
            "operator": "is",
            "value": "string",
            "negate": true,
            "case_sensitive": true
          }
        ]
      },
      "is_all_user_campaign": true,
      "send_campaign_to_opt_out_users": true
    },
    "trigger_condition": {
      "included_filters": {
        "filter_operator": "and",
        "filters": [
          {
            "filter_type": "string",
            "action_name": "string",
            "execution": {
              "count": 0,
              "type": "atleast"
            },
            "executed": true,
            "attributes": {
              "filters": [
                "string"
              ],
              "filter_operator": "and"
            },
            "condition": "IF"
          }
        ]
      },
      "trigger_delay_type": "ASAP",
      "trigger_delay_value": "string",
      "trigger_delay_granularity": "DAYS",
      "trigger_relation": "BEFORE",
      "trigger_attr": "string"
    }
  }

Postman Collections

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

FAQs

arrow_drop_down Can I fetch flow campaign node information for the SMS channel?

Yes. To fetch flow node campaigns, you must pass the include_child_campaigns key value as true.

arrow_drop_down How do I identify which campaign is from a flow?

Use the flow_name and flow_id keys in the response. These keys indicate that the campaign is part of a flow.

arrow_drop_down Can I fetch campaign information for a specific sender?

No, we currently do not have any filter in the request body for the sender name.

arrow_drop_down Can I fetch archived campaign information?

Yes. To fetch flow node campaigns, you must pass the include_archived_campaigns key value as true.

All MoEngage AI products, which were previously referred to as Sherpa AI, are now known as Merlin AI.

Previous

Next

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

How can we improve this article?