> ## 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.
# Create OSM Template
> 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.
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.
## OpenAPI
````yaml /api/osm-templates/osm-templates.yaml post /custom-templates/osm
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:
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.
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
components:
schemas:
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.
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.
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).
````