Why Create a Creative Template?

When you want to create multiple creatives for your network, a creative template is a quick and easy way to create a standard format and style for all of your creatives while maintaining a consistent "look and feel."

This creates a new creative template for your network. The body of the request is a JSON object with the below fields. Do not specify an Id when creating a template. An Id will be assigned and returned with the response.

❗️
Warning
All string keys and values are case sensitive.
For example, Name is accepted but name is not, and the value String is accepted but string is not.

API Syntax

When using the Create Creative Template API endpoint, it is important to understand the syntax required to make the request. Because the Kevel API is a RESTful API, there is a specific request format that must be followed to ensure the endpoint can process the request.

POST https://api.kevel.co/v2/creative-templates

Where:

POST — the type of API request being made
https://api.kevel.co — the base URL for the request
v2 — the API version
creative-templates — the API endpoint being called

Object Fields

The table below lists the various fields you can include in your POST request when creating a new creative template.

Each field in a creative template defines what a UI user should enter for a creative.

Key	Type	Description
`Name`	string	Required. The name of the field. Must be ≤255 characters. Example: `"Caption"`.
`Variable`	string	Required. The macro name of the field to be used in the `Contents` and/or Decision API response. Must begin with `ct`. Example: `"ctCaption"`. Only letters, numbers, and underscores are allowed.
`Type`	string	Required. The data type of the field. See Field Types below. Example: `"String"`.
`Required`	boolean	If true, the field must be filled in. A required field cannot also be `Hidden`. Defaults to `false`.
`Description`	string	Optional. Description of the field in the UI. Example: `"This is the caption for the ad."`.
`Hidden`	boolean	If true, hides the field in the UI. Defaults to `false`.
`Default`	string or array	Required only if `Hidden` is true. Defines a default value. Example: `"sponsored-brands"` or `["biz-123","org-456"]`.
`AdQuery`	boolean	If true, the field can be queried via AdQuery.
`MaxBytes`	integer	File upload size limit (bytes). Max 2 MB (2,097,152). Only used when `Type` = `File`.
`AllowedValues`	array	Optional. Restricts inputs for `String` or `Number` fields to specific values.
`Regex`	string	Optional. Enforces a regex pattern for `String` fields.
`AllowPhraseMatch`	boolean	Enables phrase (“fuzzy”) matching for `String` fields in AdQuery. See AdQuery documentation.

🚧
Caution
You cannot provide a Default if a field is not Hidden.
If a creative API request sets a value for a Hidden field that uses a Default, the creative will be saved with that overridden value. Otherwise, the value will remain the Default.

📘
Note
There is a maximum of 100 fields per creative template.

🚧
Restrictions When Adding Custom Validation
AllowedValues and Regex rules can only be added, not modified or removed, once saved.
This prevents existing creatives from entering invalid states due to rule changes.

Field Types

Value	Description	Example
`String`	A string value. Max length: 20,000 characters.	`"This is some text"`
`File`	A file uploaded via Kevel UI or API. The file name uses the variable `{{ctImage}}`.	`https://static.adzerk.net/ad.gif`
`ExternalFile`	A URL for an externally hosted file or image.	`https://domain.com/ad.gif`
`Array`	A list of strings. For example, tracking pixels to serve with the ad.	`["https://tracker1", "https://tracker2"]`
`Number`	A numeric (float) value.	`0.5`, `1744819`
`Object`	A JSON object. Max size: 1 KB.	`json { "SKU": "ZG011AQA", "Name": "Coca-Cola with Coffee Dark Blend", "price": "2.39" }`

If your creative template requires multiple images, include both a file field (for upload) and a string field (for the path).
Total uploaded files per creative cannot exceed 10 MB (e.g., 5 × 2 MB files).

[
  {
    "Field": {
      "Name": "Image1 Full URL",
      "Required": false,
      "Variable": "ctImage1",
      "Type": "String",
      "Hidden": true,
      "Default": "{{contentUrl}}/{{ctImage1}}"
    }
  },
  {
    "Field": {
      "Name": "Image1",
      "Required": true,
      "Variable": "ctBaseImage1",
      "Type": "File"
    }
  }
]

Contents Object

A creative template can have 0 or more Contents that determine how the field data is rendered in the creative.

Each content entry includes a Type (rendering method) and a Body (creative markup).

📘
Note
Maximum 10 KB (10,000 characters) of content data per template.

Key	Type	Description
`Type`	string	Required. The data type ados.js uses to render the creative. Example: `"HTML"`.
`Body`	string	The creative body markup. Max 10,000 characters. Macros allowed. Example: `<div>Check out my cool caption: {{ctCaption}}</div>`

Content Types

Value	Description	Example
`HTML`	Executes as HTML via ados.js. Can include macros like `{{ctName}}`. Does not wrap data in tags, so it can also output XML or JSON.	`<div>This is the name: {{ctName}}</div>`
`JavaScript`	Executes JavaScript code in a `<script>` tag when served via ados.js.	No example provided.
`JavaScriptExternal`	Executes an external JS file included with `<script src="...">`.	`https://domain.com/script.js`
`CSS`	Injects CSS into a page's stylesheet via ados.js.	`#azk12345 { width: auto; }`
`Raw`	Wraps data in a Kevel iframe (ados.js) or returns raw body (Decision API).	`{{contentUrl}}/{{ctImage}}` or `{"JSON": true}`

🚧
Caution
Decision API responses return type and body fields instead of rendering creatives on a page.

200200