MoEngage Templates API

openapi: 3.2.0
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: []
tags:
- name: Templates
paths:
  /custom-templates/push:
    post:
      tags:
      - Templates
      summary: Create Push Template
      description: 'This API creates a new push notification template for one or more platforms (Android, iOS).

        '
      x-mint:
        content: "#### Rate Limit \nThe rate limit is 100 RPM (Requests Per Minute).  \n"
      operationId: createPushTemplate
      requestBody:
        description: A JSON object containing the template definitions for desired platforms and metadata.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ANDROID:
                  $ref: '#/components/schemas/AndroidPayload'
                IOS:
                  $ref: '#/components/schemas/IosPayload'
                meta_info:
                  $ref: '#/components/schemas/MetaInfoCreate'
              required:
              - meta_info
            examples:
              Stylized_Android_iOS:
                summary: 1. Stylized (Android & iOS)
                value:
                  ANDROID:
                    basic_details:
                      app_name_color_code: APP_NAME_COLOR_CODE
                      notification_control_color: Light/Dark
                      background_color_code: BG_COLOR_CODE
                      title: TITLE_OF_ANDROID_TEMPLATE
                      message: MESSAGE_OF_ANDROID_TEMPLATE
                      summary: SUMMARY
                      image_url: IMAGE_URL
                      default_click_action: DEEPLINKING/RICH_LANDING/NAVIGATE_TO_A_SCREEN
                      default_click_action_value: CLICK_ACTION_URL_HERE
                      key_value_pairs:
                      - key: KEY
                        value: ' VALUE'
                    buttons:
                    - btn_name: NAME_OF_THE_BUTTON
                      click_action_type: NAVIGATE_TO_A_SCREEN/DEEPLINKING/RICH_LANDING/CALL/SHARE/COPY/SET_USER_ATTRIBUTE/TRACK_EVENT/CUSTOM_ACTION/SNOOZE/REMIND_LATER
                      click_action_name: VALID_CLICK_ACTION_NAME_HERE
                      click_action_value: CLICK_ACTION_URL_HERE
                    advanced:
                      coupon_code: COUPON_CODE
                      icon_type_in_notification: appicon/url
                      large_icon_url: LARGE_ICON_URL_HERE IF icon_type_in_notification is url
                      auto_dismiss_notification: true
                      dismissal_time_multiplier: days/hours/minutes
                      dismissal_time_value: 1
                      make_notification_sticky: true
                      dismiss_button_text: DISMISS_BUTTON_TEXT_HERE
                    template_backup:
                      title: TITLE_OF_ANDROID_BACKUP_TEMPLATE
                      message: MESSAGE_OF_ANDROID_BACKUP_TEMPLATE
                      summary: SUMMARY
                      image_url: IMAGE_URL
                      default_click_action: DEEPLINKING/RICH_LANDING/NAVIGATE_TO_A_SCREEN
                      default_click_action_value: CLICK_ACTION_URL_HERE
                      key_value_pairs:
                      - key: KEY
                        value: ' VALUE'
                  IOS:
                    basic_details:
                      background_color_code: BG_COLOR_CODE
                      title: TITLE_OF_IOS_TEMPLATE
                      subtitle: SUBTITLE_OF_IOS_TEMPLATE
                      message: MESSAGE_OF_IOS_TEMPLATE
                      rich_media_value: RICH_MEDIA_URL_HERE
                      default_click_action: DEEPLINKING/RICH_LANDING/NAVIGATE_TO_A_SCREEN
                      default_click_action_value: CLICK_ACTION_URL_HERE
                      allow_bg_refresh: true
                    buttons:
                    - button_category: CATEGORY_OF_BUTTON
                    advanced:
                      coupon_code: COUPON_CODE
                      sound_file: SOUND_FILE
                      enable_ios_badge: true
                    template_backup:
                      title: TITLE_OF_IOS_TEMPLATE
                      subtitle: SUBTITLE_OF_IOS_TEMPLATE
                      message: MESSAGE_OF_IOS_TEMPLATE
                      rich_media_value: RICH_MEDIA_URL_HERE
                      default_click_action: DEEPLINKING/RICH_LANDING/NAVIGATE_TO_A_SCREEN
                      default_click_action_value: CLICK_ACTION_URL_HERE
                      allow_bg_refresh: true
                  meta_info:
                    platform:
                    - ANDROID
                    - IOS
                    template_style: BASIC/STYLIZED
                    template_id: 1234567890
                    template_name: NAME_OF_THE_TEMPLATE
                    template_version: VERSION_OF_THE_TEMPLATE
                    created_by: USER_CREATED
              Stylized_Android_Only:
                summary: 2. Stylized (Android Only)
                value:
                  ANDROID:
                    basic_details:
                      app_name_color_code: '#ffffff'
                      notification_control_color: Light
                      background_color_code: '#ffffff'
                      title: TITLE_OF_ANDROID_TEMPLATE
                      message: MESSAGE_OF_ANDROID_TEMPLATE
                      summary: SUMMARY
                      image_url: https://images.pexels.com/photos/248797/pexels-photo-248797.jpeg?w=1260&h=750&auto=compress&cs=tinysrgb
                      default_click_action: NAVIGATE_TO_A_SCREEN
                      default_click_action_value: com.moengage.sampleapp.info.InfoActivity
                      key_value_pairs:
                      - key: page
                        value: ' 28'
                    buttons:
                    - btn_name: button1
                      click_action_type: DEEPLINKING
                      click_action_name: click
                      click_action_value: https://www.google.com
                    advanced:
                      coupon_code: COUPON_CODE
                      icon_type_in_notification: appicon
                      auto_dismiss_notification: true
                      dismissal_time_multiplier: minutes
                      dismissal_time_value: 1
                      make_notification_sticky: true
                      dismiss_button_text: DISMISS_BUTTON_TEXT_HERE
                    template_backup:
                      title: TITLE_OF_ANDROID_BACKUP_TEMPLATE
                      message: MESSAGE_OF_ANDROID_BACKUP_TEMPLATE
                      summary: SUMMARY
                      image_url: https://images.pexels.com/photos/248797/pexels-photo-248797.jpeg?w=1260&h=750&auto=compress&cs=tinysrgb
                      default_click_action: NAVIGATE_TO_A_SCREEN
                      default_click_action_value: com.moengage.sampleapp.info.InfoActivity
                      key_value_pairs:
                      - key: KEY
                        value: ' VALUE'
                  meta_info:
                    platform:
                    - ANDROID
                    template_style: STYLIZED
                    template_id: '12340'
                    template_name: BT1
                    template_version: '1'
                    created_by: User
              Stylized_iOS_Only:
                summary: 3. Stylized (iOS Only)
                value:
                  IOS:
                    basic_details:
                      background_color_code: '#ffffff'
                      title: TITLE_OF_IOS_TEMPLATE
                      subtitle: SUBTITLE_OF_IOS_TEMPLATE
                      message: MESSAGE_OF_IOS_TEMPLATE
                      rich_media_value: RICH_MEDIA_URL_HERE
                      default_click_action: RICH_LANDING
                      default_click_action_value: https://www.google.com
                      allow_bg_refresh: true
                    buttons:
                    - button_category: CATEGORY_OF_BUTTON
                    advanced:
                      coupon_code: COUPON_CODE
                      sound_file: SOUND_FILE
                      enable_ios_badge: true
                    template_backup:
                      title: TITLE_OF_IOS_TEMPLATE
                      subtitle: SUBTITLE_OF_IOS_TEMPLATE
                      message: MESSAGE_OF_IOS_TEMPLATE
                      rich_media_value: RICH_MEDIA_URL_HERE
                      default_click_action: DEEPLINKING
                      default_click_action_value: https://www.google.com
                      allow_bg_refresh: true
                  meta_info:
                    platform:
                    - IOS
                    template_style: STYLIZED
                    template_id: '123404'
                    template_name: only IOS
                    template_version: '2'
                    created_by: User
              Basic_Android_iOS:
                summary: 4. Basic (Android & iOS)
                value:
                  ANDROID:
                    basic_details:
                      title: TITLE_OF_ANDROID_TEMPLATE
                      message: MESSAGE_OF_ANDROID_TEMPLATE
                      summary: SUMMARY
                      image_url: https://images.pexels.com/photos/248797/pexels-photo-248797.jpeg?w=1260&h=750&auto=compress&cs=tinysrgb
                      default_click_action: DEEPLINKING
                      default_click_action_value: https://www.google.com
                      key_value_pairs:
                      - key: KEY
                        value: ' VALUE'
                    buttons:
                    - btn_name: NAME_OF_THE_BUTTON
                      click_action_type: DEEPLINKING
                      click_action_name: Bhuvan
                      click_action_value: https://www.google.com
                    advanced:
                      coupon_code: COUPON_CODE
                      icon_type_in_notification: appicon
                      auto_dismiss_notification: true
                      dismissal_time_multiplier: minutes
                      dismissal_time_value: 1
                  IOS:
                    basic_details:
                      title: TITLE_OF_IOS_TEMPLATE
                      subtitle: SUBTITLE_OF_IOS_TEMPLATE
                      message: MESSAGE_OF_IOS_TEMPLATE
                      rich_media_value: RICH_MEDIA_URL_HERE
                      default_click_action: DEEPLINKING
                      default_click_action_value: https://www.google.com
                      allow_bg_refresh: true
                    buttons:
                    - button_category: CATEGORY_OF_BUTTON
                    advanced:
                      coupon_code: COUPON_CODE
                      sound_file: SOUND_FILE
                      enable_ios_badge: true
                  meta_info:
                    platform:
                    - ANDROID
                    - IOS
                    template_style: BASIC
                    template_id: '12345'
                    template_name: Basic template - Android and IOS
                    template_version: '1'
                    created_by: User1
              Basic_Android_Only:
                summary: 5. Basic (Android Only)
                value:
                  ANDROID:
                    basic_details:
                      title: TITLE_OF_ANDROID_TEMPLATE
                      message: MESSAGE_OF_ANDROID_TEMPLATE
                      summary: SUMMARY
                      image_url: https://images.pexels.com/photos/248797/pexels-photo-248797.jpeg?w=1260&h=750&auto=compress&cs=tinysrgb
                      default_click_action: DEEPLINKING
                      default_click_action_value: https:wwww.google.com
                      key_value_pairs:
                      - key: KEY
                        value: ' VALUE'
                    buttons:
                    - btn_name: NAME_OF_THE_BUTTON
                      click_action_type: DEEPLINKING
                      click_action_name: Bhuvan
                      click_action_value: https:wwww.google.com
                    advanced:
                      coupon_code: COUPON_CODE
                      icon_type_in_notification: appicon
                      auto_dismiss_notification: true
                      dismissal_time_multiplier: minutes
                      dismissal_time_value: 1
                  meta_info:
                    platform:
                    - ANDROID
                    template_style: BASIC
                    template_id: '12345642'
                    template_name: Basic_template-Only Android
                    template_version: '1'
                    created_by: User11
              Basic_iOS_Only:
                summary: 6. Basic (iOS Only)
                value:
                  IOS:
                    basic_details:
                      title: TITLE_OF_IOS_TEMPLATE
                      subtitle: SUBTITLE_OF_IOS_TEMPLATE
                      message: MESSAGE_OF_IOS_TEMPLATE
                      rich_media_value: RICH_MEDIA_URL_HERE
                      default_click_action: DEEPLINKING
                      default_click_action_value: https://www.google.com
                      allow_bg_refresh: true
                    buttons:
                    - button_category: CATEGORY_OF_BUTTON
                    advanced:
                      coupon_code: COUPON_CODE
                      sound_file: SOUND_FILE
                      enable_ios_badge: true
                  meta_info:
                    platform:
                    - IOS
                    template_style: BASIC
                    template_id: '1234567'
                    template_name: Basic template - Only IOS
                    template_version: '1'
                    created_by: User1
      responses:
        '200':
          description: This response is returned when the request is processed successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  external_template_id:
                    type: string
                    format: uuid
                    description: This field contains the unique template id corresponding to a successful template creation request and needs to be stored by you. This template id would be used for searching a specific template and updating it.
                    example: d05a44f0-a7cf-471a-bcb6-63054800a367
        '400':
          description: 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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ValidationFailure:
                  summary: Validation Failure
                  value:
                    error:
                      code: 400 Bad Request
                      message: Validation failed because of invalid request data
                      details:
                      - code: NotSupported
                        target: '[''summary'']'
                        message: '[''summary''] are not expected in this request.'
                      - code: MissingValue
                        target: platform
                        message: Template Body is missing for ANDROID.
                      - code: MissingValue
                        target: platform
                        message: IOS is missing in meta_info but template body is passed for IOS.
                      request_id: LMwPhRMB
                EmptyTemplateName:
                  summary: Empty Template Name
                  value:
                    error:
                      code: 400 Bad Request
                      message: Validation failed because of invalid request data
                      details:
                      - code: MissingValue
                        target: template_name
                        message: template_name value is required but value is passed empty.
                      request_id: jUxStmFn
                InvalidDataTypes:
                  summary: Invalid Data Types
                  value:
                    error:
                      code: 400 Bad Request
                      message: Validation failed because of invalid request data
                      details:
                      - code: InvalidValue
                        target: title
                        message: title value is invalid.
                      request_id: REQCNzcE
                MissingMandatoryFields:
                  summary: Missing Mandatory Fields
                  value:
                    error:
                      code: 400 Bad Request
                      message: Validation failed because of invalid request data
                      details:
                      - code: MissingValue
                        target: title
                        message: title value is required but value is passed empty.
                      request_id: eYXFWciv
                DuplicateTemplate:
                  summary: Duplicate Template
                  value:
                    error:
                      code: 400 Bad Request
                      message: Duplicate - template_id and template_version
                      details:
                      - code: InvalidValue
                        target: Duplicate - template_id and template_version
                        message: template_id:basicios12 template_version:12 is already present.
                      request_id: cLCcgLQj
                TemplateLimitBreach:
                  summary: Template Limit Breach
                  value:
                    error:
                      code: 400 Bad Request
                      message: Maximum Template limit exceeded
                      details:
                      - code: NotSupported
                        target: Maximum Template limit exceeded
                        message: You have already created maximum allowed template allowed for client
                      request_id: eLeZXIlW
        '401':
          description: This response is returned when the authorization parameters are missing in the HTTP Auth Header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleErrorResponse'
              example:
                title: Authentication required
                description: MOE-APPKEY missing in Authentication Header
        '415':
          description: This response is returned when the header Content-Type is not provided/is not supported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleErrorResponse'
              example:
                title: Unsupported media type
                description: Content type is not supported
        '429':
          description: This response is returned when the number of requests per minute has exceeded the rate limit or the number of templates has exceeded the allowed quota per channel.
          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'
    put:
      tags:
      - Templates
      summary: Update Push Template
      description: 'This API updates an existing push notification template by creating a new version.

        '
      x-mint:
        content: "#### Rate Limit\nThe rate limit is 100 RPM (Requests Per Minute).  \n"
      operationId: updatePushTemplate
      requestBody:
        description: A JSON object containing the template ID to update, the updated platform payloads, and new metadata.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                external_template_id:
                  type: string
                  format: uuid
                  description: This field contains the unique identifier that is generated during the creation of the template.
                update_campaigns:
                  type: boolean
                  default: false
                  description: 'This field contains a flag that is used to update all the campaigns that are currently using the template being updated to the newer version(that is being updated in this request). The default value for this flag is false.


                    When the update_campaigns flag is true, all the campaigns running with this template will get updated to the latest version of the template, and when it is false, the new version of the template will be created, but there will be no change made to the template used in the existing campaigns.

                    '
                ANDROID:
                  $ref: '#/components/schemas/AndroidPayload'
                  description: This field contains the updated definition of the template for the Android platform.
                IOS:
                  $ref: '#/components/schemas/IosPayload'
                  description: This field contains the updated definition of the template for the iOS platform.
                meta_info:
                  $ref: '#/components/schemas/MetaInfoUpdate'
              required:
              - external_template_id
              - meta_info
            examples:
              UpdateTemplate:
                summary: Update Android Template
                value:
                  external_template_id: d05a44f0-a7cf-471a-bcb6-63054800a367
                  update_campaigns: false
                  ANDROID:
                    basic_details:
                      title: Updated Basic Android Template
                      message: Updated Basic Android Template
                      summary: Updated Basic Android Template summary
                      image_url: ''
                      default_click_action: DEEPLINKING
                      default_click_action_value: https://www.google.com
                    buttons:
                    - btn_name: btn1
                      click_action_type: DEEPLINKING
                      click_action_name: btn1
                      click_action_value: https://www.google.com
                    advanced:
                      coupon_code: ''
                      icon_type_in_notification: url
                      large_icon_url: https://www.google.com
                      auto_dismiss_notification: true
                      dismissal_time_multiplier: minutes
                      dismissal_time_value: 5
                  meta_info:
                    platform:
                    - ANDROID
                    template_style: BASIC
                    updated_by: John.doe@yourbrand.com
                    template_name: Basic Android Template 2
                    template_version: '2.0'
      responses:
        '200':
          description: This response is returned when the request is processed successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  external_template_id:
                    type: string
                    format: uuid
                    description: This field contains the unique template id corresponding to a successful template updation request.
                    example: eca024b7-a8ea-4f31-9154-5b80c85d18a9
        '400':
          description: This response is returned when the required parameters are missing from the request or when the provided parameters are invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 400 Bad Request
                  message: Invalid template id
                  details:
                  - code: MissingValue
                    target: 9925c8
                    message: 9925c8 is invalid template id.
                  request_id: BTkUaYgU
        '429':
          description: Rate Limit Breach.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: This response is returned when the system runs into an unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
  /custom-templates/push/search:
    post:
      tags:
      - Templates
      summary: Search for Push Templates
      description: 'This API searches the push templates created in your MoEngage account.

        '
      x-mint:
        content: "<Note>\nWe are introducing mandatory pagination, effective November 15, 2025, all calls to this API must include the following two parameters:\n\n* **page**: The page number of the results you wish to fetch.\n* **entries**: The number of templates to return per page, with a  maximum value of 15.\n\nPlease 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.\n</Note>\n\n\n#### Rate Limit\nThe rate limit is 100 RPM (request per minute).  \n"
      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. \n**Note:** \n- You can send empty filters to fetch all the push templates.\n- 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

# --- truncated at 32 KB (67 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/moengage/refs/heads/main/openapi/moengage-templates-api-openapi.yml