openapi: 3.0.3 info: title: MoEngage On-Site Messaging (OSM) Template API version: '1.0' description: API for creating, updating, and searching On-Site Messaging (OSM) templates within the MoEngage platform. tags: - name: OSM Templates description: Operations to manage On-Site Messaging (OSM) templates. servers: - url: https://api-{dc}.moengage.com/v1.0 description: MoEngage Custom Templates 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/osm: post: tags: - OSM Templates summary: Create OSM Template description: This API creates a new On-Site Messaging (OSM) template. You can use this API to upload templates created outside the MoEngage ecosystem to MoEngage and use them for campaign creation. x-mint: content: | API templates cannot be used in the Drag and Drop Editor in the MoEngage Dashboard. They are only supported for the Custom HTML Editor. #### Rate Limit The rate limit is 100 RPM. You can upload a maximum of 100 templates per minute. requestBody: required: true description: The details of the OSM template to be created. content: application/json: schema: $ref: '#/components/schemas/CreateOsmTemplateRequest' example: basic_details: payload:

Your HTML Content Here

template_type: BANNER meta_info: created_by: testuser@moengage.com template_id: '123123123' template_name: Test template_version: '1' responses: '200': description: Template created successfully. content: application/json: schema: type: object properties: external_template_id: type: string format: uuid description: The unique ID assigned to the newly created template by MoEngage. This ID is used for subsequent updates or searches. example: external_template_id: d05a44f0-a7cf-471a-bcb6-63054800a367 '400': description: Bad Request. Returned when required parameters are missing, invalid, or when a template already exists with the same version, name, or ID. content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' example: 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:13343440 template_version:1 is already present." request_id: xZLmJvUi '401': description: Authentication Failure. Returned when authorization parameters are missing or invalid. content: application/json: schema: $ref: '#/components/schemas/SimpleErrorResponse' example: title: Authentication required description: MOE-APPKEY missing in Authentication Header '415': description: Unsupported Media Type. Returned when the header Content-Type is not provided or is not supported. content: application/json: schema: $ref: '#/components/schemas/SimpleErrorResponse' example: title: Unsupported media type description: Content type is not supported '429': description: Rate limit breached. Returned when requests per minute exceed the limit or template quota is exceeded. content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' example: response_id: OUUkHvcn type: custom_template error: code: Too Many Requests message: "API rate limit breached. Current limit: n/m mins" '5XX': description: Internal Server Error. Returned when the system runs into an unexpected error. content: application/json: schema: $ref: '#/components/schemas/SimpleErrorResponse' example: title: Internal Server Error message: An unexpected error was encountered while processing this request. Please contact MoEngage Team put: tags: - OSM Templates summary: Update OSM Template description: This API updates an OSM template as per your requirements. x-mint: content: | #### Rate Limit The rate limit is 100 RPM. requestBody: required: true description: The updated details for the OSM template. content: application/json: schema: $ref: '#/components/schemas/UpdateOsmTemplateRequest' example: external_template_id: 81e1a740-3e57-4c70-8ec7-ffc84d576498 update_campaigns: false basic_details: payload:

Updated HTML Content

meta_info: template_name: AD template updated API 1 template_id: '133434477456' template_version: '2' updated_by: testuser@moengage.com responses: '200': description: Template updated successfully. content: application/json: schema: type: object properties: external_template_id: type: string format: uuid description: The unique ID of the updated template. example: external_template_id: 4a1afbc5-4c31-4f19-8c23-793e27af01aa '400': description: Bad Request. Validation failed or missing parameters. content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' example: error: code: 400 Bad Request message: Validation failed because of invalid request data details: - code: MissingValue target: external_template_id message: external_template_id value is required but value is passed empty. request_id: cTRlnJaG '5XX': description: Internal Server Error. content: application/json: schema: $ref: '#/components/schemas/SimpleErrorResponse' example: title: Internal Server Error message: An unexpected error was encountered while processing this request. Please contact MoEngage Team /custom-templates/osm/search: post: tags: - OSM Templates summary: Search OSM Templates description: This API searches the OSM templates created in your MoEngage account. x-mint: content: | **Mandatory Pagination** 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. * If the request body is passed empty, then all templates will be returned. * The `preview_image` field in the response will be generated by MoEngage for the HTML template payload. #### Rate Limit The rate limit is 100 RPM. requestBody: required: true description: Search filters for finding OSM templates. content: application/json: schema: $ref: '#/components/schemas/SearchOsmTemplateRequest' example: page: 1 entries: 10 template_source: - API sort_params: - last_modified_date: DESCENDING responses: '200': description: Search successful. Returns a list of templates. content: application/json: schema: $ref: '#/components/schemas/SearchOsmTemplateResponse' example: data: - meta_info: template_id: '1234567890123' template_name: NAME_OF_THE_TEMPLATE template_version: '1' created_by: test@moengage.com channel: ON-SITE template_source: API template_type: CUSTOM external_template_id: 4a1afbc5-4c31-4f19-8c23-793e27af01aa version: 1 basic_details: payload: ... preview_image: https://pbs.twimg.com/profile_images/10ydbKG1.jpg created_by: test@moengage.com created_at: '2023-08-01T07:58:53.880000' updated_by: test@moengage.com updated_at: '2023-08-01T07:58:53.880000' '400': description: Bad Request. Missing or invalid search parameters. content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' example: error: code: 400 Bad Request message: Validation failed because of invalid request data details: - code: MissingValue target: external_template_ids message: external_template_id or version is missing in external_template_ids. request_id: npmQrbNE '429': description: Rate limit breached. content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' example: response_id: OUUkHvcn type: custom_template error: code: Too Many Requests message: "API rate limit breached. Current limit: n/m mins" '5XX': description: Internal Server Error. content: application/json: schema: $ref: '#/components/schemas/SimpleErrorResponse' example: title: Internal Server Error message: An unexpected error was encountered while processing this request. Please contact MoEngage Team components: 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). schemas: StandardErrorResponse: type: object description: Standard error structure used for 400 and 429 responses. properties: error: type: object properties: code: type: string description: A brief explanation of the error. example: 4XX Bad Request message: type: string description: Describes why the request failed (e.g., Duplicate - template_id). example: Duplicate - template_id and template_version details: type: array description: A list of error detail objects containing code, target, and specific messages. items: type: object properties: code: type: string description: Descriptive Error Code. example: InvalidValue target: type: string description: Denotes the field causing the issue. example: Duplicate - template_id and template_version message: type: string description: Descriptive Error Message. example: "template_id:BasicTemplate1 template_version:1 is already present." request_id: type: string description: Unique identifier for the request. example: cLCcgLQj SimpleErrorResponse: type: object description: Simplified error structure used for 401, 415, and 5xx responses. properties: title: type: string description: The title of the error. example: Authentication required description: type: string description: A description of the error (used in 401/415). example: MOE-APPKEY missing in Authentication Header message: type: string description: A message describing the error (used in 5xx). example: An unexpected error was encountered. CreateOsmTemplateRequest: type: object required: - basic_details - meta_info properties: basic_details: type: object description: Details about the template, including its payload and template type. required: - payload - template_type properties: payload: type: string description: | Payload type must be HTML. The data type is a string. * No limit restriction on field length. * For payload structure examples, see the main endpoint documentation. template_type: type: string description: The type of template being created. enum: - BANNER - POP_UP - NUDGE meta_info: type: object description: This field contains information about the template being created, such as its name, version, ID, and the creator's details. required: - created_by - template_id - template_name - template_version properties: created_by: type: string description: Identifier for the creator of the template (e.g., email). template_id: type: string description: A unique ID for the template provided by you. template_name: type: string description: The name of the template. template_version: type: string description: The version of the template. UpdateOsmTemplateRequest: type: object required: - external_template_id - basic_details - meta_info properties: external_template_id: type: string format: uuid description: The unique identifier generated by MoEngage during template creation. update_campaigns: type: boolean default: false description: | Flag to update all campaigns currently using this template to the newer version. * **`true`**: All campaigns running with this template will be updated. * **`false`**: A new version of the template is created; existing campaigns remain unchanged. basic_details: type: object description: Details about the template payload. required: - payload properties: payload: type: string description: | The updated HTML content. * Payload type must be HTML. * No limit restriction on field length. meta_info: type: object description: Updates template information such as name, version, and updater details. required: - template_name - template_id - updated_by properties: template_name: type: string description: The name of the template being updated. template_id: type: string description: A unique ID for the template provided by you. template_version: type: string description: Optional new version for the template. The version will be increased by 1 automatically after every update. updated_by: type: string format: email description: The email ID of the person updating the template. SearchOsmTemplateRequest: type: object description: >- **Notes:** - `page` and `entries` are mandatory effective November 15, 2025. All other fields are optional. - An empty request body will fetch all templates. required: - page - entries properties: page: type: integer description: The index of the page to be returned. Mandatory after Nov 15, 2025. entries: type: integer description: The number of entries/templates to return per page. Max 15. Mandatory after Nov 15, 2025. maximum: 15 template_name: type: string description: The name of the template to search for. Returns templates matching this name. template_id: type: string description: The unique ID of the template provided by you. template_source: type: array description: Filter templates by their source. items: type: string enum: - API - MOENGAGE template_type: type: array description: Filter templates by type (Custom or Pre-built). items: type: string enum: - CUSTOM - PRE_BUILT created_by: type: array description: Filter templates by the creator's email identifier. items: type: string format: email updated_by: type: array description: Filter templates by the updater's email identifier. items: type: string format: email sort_params: type: array description: Sort the templates by multiple fields in ASCENDING or DESCENDING order. Priority follows the array order. items: type: object properties: template_name: type: string enum: - ASCENDING - DESCENDING last_modified_date: type: string enum: - ASCENDING - DESCENDING last_modified_by: type: string enum: - ASCENDING - DESCENDING external_template_ids: type: array description: Search for multiple templates using pairs of `external_template_id` and `version`. items: type: object properties: external_template_id: type: string format: uuid version: type: integer OsmTemplate: type: object properties: external_template_id: type: string format: uuid description: The unique system-generated ID for the template. version: type: integer description: The numeric version of the template. basic_details: type: object properties: payload: type: string description: The HTML payload of the template. preview_image: type: string format: uri description: A preview image URL generated by MoEngage for the HTML payload. meta_info: type: object properties: template_id: type: string description: The user-provided template ID. template_name: type: string description: The name of the template. template_version: type: string description: The user-provided string version. created_by: type: string description: The creator of the template. channel: type: string example: ON-SITE description: The channel associated with the template. template_source: type: string enum: - API - MOENGAGE description: The source of the template creation. template_type: type: string enum: - CUSTOM - PRE_BUILT description: The type classification of the template. created_by: type: string description: The user who created the template. created_at: type: string format: date-time description: The timestamp when the template was created. updated_by: type: string description: The user who last updated the template. updated_at: type: string format: date-time description: The timestamp when the template was last updated. SearchOsmTemplateResponse: type: object properties: data: type: array description: A list containing the details of the templates found. items: $ref: '#/components/schemas/OsmTemplate'