> ## 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 OSM Templates
> This API searches the OSM templates created in your MoEngage account.
**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.
## OpenAPI
````yaml /api/osm-templates/osm-templates.yaml post /custom-templates/osm/search
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.
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: []
tags:
- name: OSM Templates
description: Operations to manage On-Site Messaging (OSM) templates.
paths:
/custom-templates/osm/search:
post:
tags:
- OSM Templates
summary: Search OSM Templates
description: This API searches the OSM templates created in your MoEngage account.
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:
schemas:
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
SearchOsmTemplateResponse:
type: object
properties:
data:
type: array
description: A list containing the details of the templates found.
items:
$ref: '#/components/schemas/OsmTemplate'
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.
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.
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).
````