> ## Documentation Index
> Fetch the complete documentation index at: https://moengage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Search for Push Templates
> This API searches the push templates created in your MoEngage account.
We are introducing mandatory pagination, effective November 15, 2025, all calls to this API must include the following two parameters:
* **page**: The page number of the results you wish to fetch.
* **entries**: The number of templates to return per page, with a maximum value of 15.
Please update all integrations to include these parameters. API requests submitted without them after the effective date will result in an error and fail to execute.
#### Rate Limit
The rate limit is 100 RPM (request per minute).
## OpenAPI
````yaml /api/push-templates/push-templates.yaml post /custom-templates/push/search
openapi: 3.0.3
info:
title: Push Templates API
description: >
An API for creating, updating, and searching for push notification templates
for Android and iOS platforms.
version: '1.0'
x-logo:
url: >-
https://images.g2crowd.com/uploads/product/image/social_landscape/social_landscape_4cb13a53c5240c218206532439a2f15a/moengage.png
altText: MoEngage Logo
servers:
- url: https://api-{dc}.moengage.com/v1.0
description: MoEngage API Server.
variables:
dc:
default: '01'
description: >-
The ‘dc’ in the API Endpoint URL refers to the MoEngage Data Center
(DC). MoEngage hosts each customer in a different DC. You can find
your DC number and replace the value of ‘dc’ in the URL by referring
to the DC and API endpoint mapping
[here](/api/introduction#data-centers). Your MoEngage Data Center (DC)
can be 01, 02, 03, 04, 05, 06, or 101.
security:
- BasicAuth: []
paths:
/custom-templates/push/search:
post:
tags:
- Templates
summary: Search for Push Templates
description: |
This API searches the push templates created in your MoEngage account.
operationId: searchPushTemplates
requestBody:
description: >-
A JSON object containing filters for the search. **You can send empty
filters to fetch all the push templates.** Searches for push templates
based on a variety of filter criteria.
**Note:**
- You can send empty filters to fetch all the push templates.
- You can send only template_ids if you want specific older versions
of the push template. In other cases, you will receive the latest
version of the template.
required: true
content:
application/json:
schema:
type: object
required:
- page
- entries
properties:
page:
type: integer
description: The page number of the results you wish to fetch.
default: 1
entries:
type: integer
description: >-
The number of templates to return per page, with a maximum
value of 15.
default: 10
maximum: 15
template_name:
type: string
description: >-
This field indicates the name of the template. When this
value is specified, the template that matches the name
specified in this field will be returned.
platform:
type: array
items:
type: string
enum:
- ANDROID
- IOS
description: >-
This field indicates the list of platforms. Allowed values:
ANDROID, IOS. When specified, the templates whose platform
matches that specified in this list will be returned.
template_source:
type: array
items:
type: string
enum:
- API
- MOENGAGE
description: >-
This field indicates the template source that created the
template. For example: ["API", "MOENGAGE"]. When specified,
the templates whose source matches that specified in this
list will be returned.
template_style:
type: array
items:
type: string
enum:
- BASIC
- STYLIZED
description: >-
This field indicates the template style. Allowed values:
BASIC, STYLIZED. When specified, the templates whose
template style matches that specified in this list will be
returned.
template_type:
type: array
items:
type: string
enum:
- CUSTOM
- PRE_BUILT
description: >-
This field indicates whether the template is a custom one or
a pre-built one. Allowed values: CUSTOM, PRE_BUILT. When
specified, the templates whose template type matches that
specified in this list will be returned.
created_by:
type: array
items:
type: string
format: email
description: >-
This field indicates the user who created the template. When
specified, the templates for which the created_by user
information matches that specified in this list will be
returned. Example: ["user1@moengage.com",
"user2@moengage.com"]
updated_by:
type: array
items:
type: string
format: email
description: >-
This field indicates the user who updated the template. When
specified, the templates for which the updated_by user
information matches that specified in this list will be
returned. Example: ["user1@moengage.com",
"user2@moengage.com"]
sort_params:
type: array
items:
type: object
properties:
template_name:
type: string
enum:
- ASCENDING
- DESCENDING
description: Sort by Template Name
last_modified_date:
type: string
enum:
- ASCENDING
- DESCENDING
description: Sort by Last Modified Date
last_modified_by:
type: string
enum:
- ASCENDING
- DESCENDING
description: Sort by Last Modified By
description: >-
This field indicates the sorting parameters for the search
result and the sort order. Example:
"sort_params":[{"template_name":
"ASCENDING","last_modified_date":
"ASCENDING","last_modified_by": "ASCENDING"}]
template_ids:
type: array
items:
type: object
properties:
external_template_id:
type: string
format: uuid
description: The unique identifier of the template.
version:
type: integer
description: The version number of the template.
description: >-
This field indicates the list of the template ids that must
be fetched. When this value is specified, the template that
matches the id specified in this field will be returned. You
can send only template_ids if you want specific older
versions of the push template. In other cases, you will
receive the latest version of the template. Example:
"template_ids":[{"external_template_id":
"e1c95cb8-4f15-4f22-ae73-e9f47c9925c8", "version": 1}]
examples:
ComplexSearch:
summary: Complex Search Filter
value:
page: 1
entries: 10
template_name: NAME_OF_THE_TEMPLATE(PARTIAL SEARCH)/ID_OF_TEMPLATE
platform:
- ANDROID
- IOS
template_source:
- API
- MOENGAGE
template_style:
- BASIC
- STYLIZED
template_type:
- CUSTOM
- PRE_BUILT
created_by:
- user1@moengage.com
- user2@moengage.com
updated_by:
- user1@moengage.com
- user2@moengage.com
sort_params:
- last_modified_date: DESCENDING
template_ids:
- external_template_id: ID_OF_TEMPLATE
version: 1
responses:
'200':
description: >-
This response is returned when the request is processed
successfully.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
external_template_id:
type: string
format: uuid
description: Unique template identifier.
version:
type: integer
description: Template version number.
ANDROID:
$ref: '#/components/schemas/AndroidPayload'
IOS:
$ref: '#/components/schemas/IosPayload'
meta_info:
type: object
description: Meta information about the template.
properties:
platform:
type: array
items:
type: string
description: List of supported platforms.
template_style:
type: string
description: Style of the template.
template_id:
type: string
description: Template Identifier.
template_name:
type: string
description: Name of the template.
template_version:
type: string
description: Version string of the template.
updated_by:
type: string
description: User who updated the template.
channel:
type: string
description: Channel type (e.g., PUSH).
template_source:
type: string
description: Source of the template (e.g., API).
template_type:
type: string
description: Type of template (e.g., CUSTOM).
created_by:
type: string
description: User who created the template.
created_at:
type: string
format: date-time
description: Creation timestamp.
updated_by:
type: string
description: User who updated the template.
updated_at:
type: string
format: date-time
description: Last update timestamp.
description: >-
This field contains the list of push templates that
satisfy the search criteria.
example:
data:
- external_template_id: 9b09875c-edda-42e9-8f9f-a7d0a9a2aa26
version: 2
ANDROID:
basic_details:
background_color_code: '#ffffff'
notification_control_color: Dark
apply_background_color: false
title: Winter Sale 50% Off
message: Sample Message
summary: Sample Summary
image_url: ''
default_click_action: RICH_LANDING
default_click_action_value: https://www.google.com
buttons:
- btn_name: View Offers
click_action_type: RICH_LANDING
click_action_value: https://www.google.com
- btn_name: Show More Like This
click_action_type: RICH_LANDING
click_action_value: https://www.google.com
advanced:
icon_type_in_notification: appicon
make_notification_sticky: true
dismiss_button_text: Dismiss
auto_dismiss_notification: true
dismissal_time_value: 24
dismissal_time_multiplier: hours
template_backup:
title: Stylized Android Template
message: Sample Stylized Android Template
default_click_action: RICH_LANDING
default_click_action_value: https://www.google.com
IOS:
basic_details: {}
meta_info:
platform:
- ANDROID
template_style: STYLIZED
template_id: Stylizedandroid1
template_name: Stylized Android Template 2
template_version: '1'
updated_by: Jane Doe
channel: PUSH
template_source: API
template_type: CUSTOM
created_by: John Doe
created_at: '2023-02-27T12:33:05.575000'
updated_by: Jane Doe
updated_at: '2023-02-27T12:33:05.575000'
'400':
description: Bad Request.
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleErrorResponse'
example:
title: Invalid Field Value
description: Some of the field values are invalid
code: nGpUNpDQ
'429':
description: >-
This response is returned when the number of requests per minute has
exceeded the rate limit.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
response_id: OUUkHvcn
type: custom_template
error:
code: Too Many Requests
message: 'API rate limit breached. Current limit: n/m mins'
'500':
description: >-
This response is returned when the system runs into an unexpected
error.
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
components:
schemas:
AndroidPayload:
type: object
description: >
This field contains the definition of the template for the Android
platform.
properties:
basic_details:
type: object
description: >-
The basic_details JSON object contains the core information like
title, message, and summary.
required:
- title
- message
- default_click_action
- default_click_action_value
properties:
title:
type: string
description: This field contains the title of the message.
message:
type: string
description: This field contains the message content.
summary:
type: string
description: This field contains a brief description of the message content.
app_name_color_code:
type: string
description: >
This field contains the specification for the color of the app
name in the push notification. This is available only for the
Android platform. This option is not available for the Basic
Notification template. Example: "app_name_color_code": "#5450ea"
**Note**: Only hexadecimal values are supported.
notification_control_color:
type: string
enum:
- Light
- Dark
description: >-
This field contains the specification for the notification
control color. Allowed Values, Light, Dark. This is available
only for the Android platform. This option is not available for
the Basic Notification template.
background_color_code:
type: string
description: >
This field contains the specification for the background color
of the message in the push notification. This is available only
for the Android platform. This option is not available for the
Basic Notification template. Example: "background_color_code":
"#f5e6cd"
**Note**: Only hexadecimal values are supported.
apply_background_color:
type: boolean
description: >-
This field contains information about whether the background
color should be applied to the fields with a text editor (Title,
Message, and Summary). It is recommended to enable this option
for lighter font colors. This option is not available for the
Basic Notification template.
image_url:
type: string
format: uri
description: >-
This field contains the URL of the image to be added to the
notification. Allowed file formats, jpg, jpeg, png, gif.
input_gif_url:
type: string
format: uri
description: >-
This field contains the URL of the image to be added to the
notification. This is supported only for Android Basic Template.
default_click_action:
type: string
enum:
- NAVIGATE_TO_A_SCREEN
- DEEPLINKING
- RICH_LANDING
description: >
This field describes the default action that should happen when
a user clicks on the push notification. The allowed values are:
1. NAVIGATE_TO_A_SCREEN
2. DEEPLINKING
3. RICH_LANDING
default_click_action_value:
type: string
description: >-
This field contains information about which screen or URL or the
rich landing URL information the user should navigate to based
on the click action defined above. For example, if
default_click_action is NAVIGATE_TO_A_SCREEN, the screen details
in the app that the user should land on when they click on the
push notification should be specified in
default_click_action_value.
key_value_pairs:
type: array
items:
$ref: '#/components/schemas/KeyValue'
description: |
This field contains the list of key-value pairs. For example:
[{"key" : "user","value": "john"}]
buttons:
type: array
items:
$ref: '#/components/schemas/AndroidButton'
description: >-
The buttons object contains the list of buttons in the notification
and is optional.
advanced:
type: object
description: >-
The advanced JSON object contains options like coupon codes, icon
types, and dismissal settings.
properties:
coupon_code:
type: string
description: This field contains the coupon code.
icon_type_in_notification:
type: string
enum:
- appicon
- upload
- url
description: >-
This field contains the type of icon to be used in the
notification. Allowed Values: appicon, upload, url.
large_icon_url:
type: string
format: uri
description: >-
This field contains the URL that contains the large icon to be
added to the notification.
auto_dismiss_notification:
type: boolean
description: >-
This field contains information about whether notification
should be auto-dismissed from the user's notification tray.
dismissal_time_multiplier:
type: string
enum:
- DAYS
- HOURS
- MINUTES
description: >-
This field contains the time duration in days, hours, or
minutes, and this will be multiplied with the
dismissal_time_value to calculate the duration, after which the
notification will automatically be removed from the user's
notification tray after the push notification is delivered to
the user. Allowed Values: DAYS, HOURS, MINUTES. For example, if
you want the notification to be dismissed in two hours, specify
the dismissal_time_multiplier as HOURS and the
dismissal_time_value as 2.
dismissal_time_value:
type: integer
description: >-
This field contains the value that will be multiplied with the
dismissal_time_multiplier to arrive at the time duration, after
which the notification will automatically be removed from the
user's notification tray after the push notification is
delivered to the user. For example, if you want the notification
to be dismissed in thirty minutes, specify the
dismissal_time_multiplier as MINUTES and the
dismissal_time_value as 30.
make_notification_sticky:
type: boolean
description: >-
This field contains information about whether the notification
should be made sticky in the user's notification tray. If this
value is true, the notifications cannot be dismissed by swiping
or clicking. The user would have to click on the dismiss button
provided in the notification to dismiss it. This option is not
available for the Basic Notification template.
dismiss_button_text:
type: string
description: >-
This field contains the name of the dismiss button when sticky
notifications are turned on. This option is not available for
the Basic Notification template.
group_key:
type: string
description: >
This field denotes the group key used to identify and categorize
related push notifications.
**Note**:
* Ensure you use the same group key for all push notifications
you want to group.
* MoEngage automatically modifies the group key to ensure it
does not exceed the 45-character limit. MoEngage removes
non-Latin scripts, special characters, and spaces to restrict
the key composition to ASCII characters exclusively.
collapse_replace_key:
type: string
description: >-
This field denotes the update key used to identify and update
related push notifications. Ensure you use the same update key
for all push notifications intended to update each other.
template_backup:
type: object
description: >-
Some of the options available in the higher SDK versions are not
supported for devices that have lower SDK versions (versions lesser
than **Android SDK version 10.3.00**). In such cases, a backup
notification is sent, and this information is configured in the
Template Backup section. **Note**: This option does not apply to the
Basic notification template and is applicable only to the Stylized
basic template.
properties:
title:
type: string
description: This field contains the title of the message.
message:
type: string
description: This field contains the message content.
summary:
type: string
description: This field contains a brief description of the message content.
image_url:
type: string
format: uri
description: >-
This field contains the URL of the image to be added to the
notification. Allowed file formats: jpg, jpeg, png, gif
default_click_action:
type: string
enum:
- NAVIGATE_TO_A_SCREEN
- DEEPLINKING
- RICH_LANDING
description: >
This field describes the default action that should happen when
a user clicks on the push notification. The allowed values are:
1. NAVIGATE_TO_A_SCREEN
2. DEEPLINKING
3. RICH_LANDING
default_click_action_value:
type: string
description: >-
This field contains information about which screen or URL or the
rich landing URL information the user should navigate to based
on the click action defined above. For example, if
default_click_action is NAVIGATE_TO_A_SCREEN, the screen details
in the app that the user should land on should be specified in
default_click_action_value.
key_value_pairs:
type: array
items:
$ref: '#/components/schemas/KeyValue'
description: |
This field contains the list of key-value pairs. For example:
[{"key" : "user","value": "john"}]
required:
- title
- message
- default_click_action
- default_click_action_value
IosPayload:
type: object
description: |
This field contains the definition of the template for the iOS platform.
properties:
basic_details:
type: object
description: >-
The basic_details JSON object contains the core information like
title, subtitle, and message.
required:
- title
- message
- default_click_action_value
properties:
title:
type: string
description: This field contains the title of the message.
subtitle:
type: string
description: This field contains the subtitle of the message.
message:
type: string
description: This field contains the message.
background_color_code:
type: string
example: '#f5e6cd'
description: >-
This field contains the specification for the background color
of the message in the push notification. This option is not
available for the Basic Notification template. Example:
"background_color_code": "#f5e6cd"
apply_background_color:
type: boolean
description: >-
This field contains information about whether the background
color should be applied to the fields with a text editor (Title,
Subtitle, and Message). It is recommended to enable this option
for lighter font colors. This option is not available for the
Basic Notification template.
default_click_action:
type: string
enum:
- NAVIGATE_TO_A_SCREEN
- DEEPLINKING
- RICH_LANDING
description: >
This field describes the default action that should happen when
a user clicks on the push notification. The allowed values are:
1. NAVIGATE_TO_A_SCREEN
2. DEEPLINKING
3. RICH_LANDING
The NAVIGATE_TO_A_SCREEN option should be used to take the user
to the specified navigation screen, DEEPLINKING should be used
to take to user to a deep-linked URI, and RICH_LANDING option
should be used to take the user to a rich landing page (Web View
in App).
default_click_action_value:
type: string
description: >-
This field contains information about which screen or URL or the
rich landing URL information the user should navigate to based
on the click action defined above. For example, if
default_click_action is NAVIGATE_TO_A_SCREEN, the screen details
in the app that the user should land on when they click on the
push notification should be specified in
default_click_action_value.
key_value_pairs:
type: array
items:
$ref: '#/components/schemas/KeyValue'
description: >-
This field contains the list of key-value pairs. For example:
[{"key" : "user","value": "john"}]
rich_media_type:
type: string
enum:
- IMAGE
- AUDIO
- VIDEO
- GIF
description: >-
This field contains the type of rich media to be added to the
notification. Allowed values: IMAGE, AUDIO, VIDEO, GIF. This
option is not available for the Stylized Basic template.
rich_media_value:
type: string
format: uri
description: >-
This field contains the URL of the rich media to be added to the
notification. This option is not available for the Stylized
Basic template.
allow_bg_refresh:
type: boolean
description: >-
This field indicates whether the app should be allowed to
refresh in the background.
buttons:
type: array
items:
$ref: '#/components/schemas/IosButton'
description: >-
The buttons object contains the list of buttons in the notification
and is optional.
advanced:
type: object
description: >-
The advanced JSON object contains options like coupon code and sound
files.
properties:
coupon_code:
type: string
description: This field contains the coupon code.
sound_file:
type: string
description: >-
This field contains the details of the sound file to be used for
the notification in the user's device. This would be the sound
the user would hear on their device upon receiving the
notification.
enable_ios_badge:
type: boolean
description: >-
This field indicates whether the badge count should be shown in
the app.
group_key:
type: string
description: >
This field denotes the group key used to identify and categorize
related push notifications.
**Note**:
* Ensure you use the same group key for all push notifications
you want to group.
* MoEngage automatically modifies the group key to ensure it
does not exceed the 45-character limit. MoEngage removes
non-Latin scripts, special characters, and spaces to restrict
the key composition to ASCII characters exclusively.
collapse_replace_key:
type: string
description: >-
This field denotes the update key used to identify and update
related push notifications. Ensure you use the same update key
for all push notifications intended to update each other.
template_backup:
type: object
description: >-
Some of the options available in the higher SDK versions are not
supported for devices that have lower SDK versions (versions lesser
than **iOS version 6.2.0**). In such cases, a backup notification is
sent, and this information is configured in the Template Backup
section. **Note**: This option does not apply to the Basic
notification template and is applicable only to the Stylized basic
template.
properties:
title:
type: string
description: This field contains the title of the message.
subtitle:
type: string
description: This field contains the message content.
message:
type: string
description: This field contains a brief description of the message content.
default_click_action:
type: string
enum:
- NAVIGATE_TO_A_SCREEN
- DEEPLINKING
- RICH_LANDING
description: >
This field describes the default action that should happen when
a user clicks on the push notification. The allowed values are:
1. NAVIGATE_TO_A_SCREEN
2. DEEPLINKING
3. RICH_LANDING
default_click_action_value:
type: string
description: >-
This field contains information about which screen or URL or the
rich landing URL information the user should navigate to based
on the click action defined above. For example, if
default_click_action is NAVIGATE_TO_A_SCREEN, the screen details
in the app that the user should land on when they click on the
push notification should be specified in
default_click_action_value.
key_value_pairs:
type: array
items:
$ref: '#/components/schemas/KeyValue'
description: >-
This field contains the list of key-value pairs. For example:
[{"key" : "user","value": "john"}]
rich_media_type:
type: string
enum:
- IMAGE
- AUDIO
- VIDEO
description: >-
This field contains the type of rich media to be added to the
notification. Allowed values: IMAGE, AUDIO, VIDEO. This option
is not available for the Stylized Basic template.
rich_media_value:
type: string
format: uri
description: >-
This field contains the URL of the rich media to be added to the
notification. This option is not available for the Stylized
Basic template.
allow_bg_refresh:
type: boolean
description: >-
This field indicates whether the app should be allowed to
refresh in the background.
required:
- title
- message
- default_click_action
- default_click_action_value
SimpleErrorResponse:
type: object
properties:
title:
type: string
example: Authentication required
description:
type: string
example: MOE-APPKEY missing in Authentication Header
ErrorResponse:
type: object
properties:
error:
type: object
description: This field contains the reason for the request's failure.
properties:
code:
type: string
example: 400 Bad Request
description: >-
This field contains the error code that provides a brief
explanation of the error and is a String. 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:
type: string
example: Validation failed because of invalid request data
description: >-
This field describes why the request has failed and is a String.
For example, in the case of a duplicate request (400- Bad
Request), the following message will be present: 'Duplicate -
template_id and template_version'.
details:
type: array
description: This is a List of the error details objects.
items:
type: object
properties:
code:
type: string
example: MissingValue
description:
target:
type: string
example: template_name
description: >-
message:
type: string
example: template_name value is required but value is passed empty.
description:
request_id:
type: string
example: jUxStmFn
description: This field contains the unique id pertaining to the request.
InternalServerErrorResponse:
type: object
properties:
title:
type: string
example: Internal Server Error
message:
type: string
example: >-
An unexpected error was encountered while processing this request.
Please contact MoEngage Team
KeyValue:
type: object
properties:
key:
type: string
description: The key for the data pair.
value:
type: string
description: The value for the data pair.
required:
- key
- value
AndroidButton:
type: object
properties:
btn_name:
type: string
description: This field contains the name of the button.
click_action_type:
type: string
description: >
This field contains the click action associated with the button. The
allowed values are:
1. NAVIGATE_TO_A_SCREEN
2. DEEPLINKING
3. RICH_LANDING
4. CALL
5. SHARE
6. COPY
7. SET_USER_ATTRIBUTE
8. TRACK_EVENT
9. CUSTOM_ACTION
10. SNOOZE
11. REMIND_LATER
For more information, refer to [Click Actions Supported for
Android](/user-guide/campaigns-and-channels/mobile-push/notification-features-and-behavior/notification-actions).
enum:
- NAVIGATE_TO_A_SCREEN
- DEEPLINKING
- RICH_LANDING
- CALL
- SHARE
- COPY
- SET_USER_ATTRIBUTE
- TRACK_EVENT
- CUSTOM_ACTION
- SNOOZE
- REMIND_LATER
click_action_name:
type: string
description: >-
This field is used when the click action is chosen as
SET_USER_ATTRIBUTE or TRACK_EVENT. In both these cases, a KV pair
input is required, and the key is set in this field while the value
is set for the same in click_action_value.
click_action_value:
type: string
description: >-
This field contains information about which screen or URL the user
should navigate to or the action that should happen for the click
action type defined for the button. For example, if
click_action_type is NAVIGATE_TO_A_SCREEN, the screen details in the
app that the user should land on when they click the button should
be specified in click_action_value.
key_value_pairs:
type: array
items:
$ref: '#/components/schemas/KeyValue'
description: |
This field contains the list of key-value pairs. For example:
[{"key" : "user","value": "john"}]
required:
- btn_name
- click_action_type
- click_action_value
IosButton:
type: object
properties:
button_category:
type: string
description: >-
This field contains the category of the button. To add a
button_category, you will need to implement an actionable
notification.
securitySchemes:
BasicAuth:
type: http
scheme: basic
description: >
Authentication is done via Basic Auth. This requires a base64-encoded
string of your credentials in the format 'username:password'.
- **Username**: Use your MoEngage workspace ID (also known as the App
ID). You can find it in the MoEngage dashboard at **Settings** >
**Account** > **APIs** > **Workspace ID (earlier app id)**.
- **Password**: Use your API Key, which you can find within the
**Campaign report/Business events/Custom templates/Catalog API/Inform
Report** tile.
For more information on authentication and getting your credentials,
refer
[here](https://www.moengage.com/docs/api/introduction#getting-your-credentials).
````