API DocsKnowledge BaseSystem StatusContact SupportContact Sales
API Documentation
Start typing to search…

Create Creative Template

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

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.

KeyTypeDescription
NamestringRequired. The name of the field. Must be ≤255 characters. Example: "Caption".
VariablestringRequired. 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.
TypestringRequired. The data type of the field. See Field Types below. Example: "String".
RequiredbooleanIf true, the field must be filled in. A required field cannot also be Hidden. Defaults to false.
DescriptionstringOptional. Description of the field in the UI. Example: "This is the caption for the ad.".
HiddenbooleanIf true, hides the field in the UI. Defaults to false.
Defaultstring or arrayRequired only if Hidden is true. Defines a default value. Example: "sponsored-brands" or ["biz-123","org-456"].
AdQuerybooleanIf true, the field can be queried via AdQuery.
MaxBytesintegerFile upload size limit (bytes). Max 2 MB (2,097,152). Only used when Type = File.
AllowedValuesarrayOptional. Restricts inputs for String or Number fields to specific values.
RegexstringOptional. Enforces a regex pattern for String fields.
AllowPhraseMatchbooleanEnables 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

ValueDescriptionExample
StringA string value. Max length: 20,000 characters."This is some text"
FileA file uploaded via Kevel UI or API. The file name uses the variable {{ctImage}}.https://static.adzerk.net/ad.gif
ExternalFileA URL for an externally hosted file or image.https://domain.com/ad.gif
ArrayA list of strings. For example, tracking pixels to serve with the ad.["https://tracker1", "https://tracker2"]
NumberA numeric (float) value.0.5, 1744819
ObjectA 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.

KeyTypeDescription
TypestringRequired. The data type ados.js uses to render the creative. Example: "HTML".
BodystringThe creative body markup. Max 10,000 characters. Macros allowed. Example: <div>Check out my cool caption: {{ctCaption}}</div>

Content Types

ValueDescriptionExample
HTMLExecutes 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>
JavaScriptExecutes JavaScript code in a <script> tag when served via ados.js.No example provided.
JavaScriptExternalExecutes an external JS file included with <script src="...">.https://domain.com/script.js
CSSInjects CSS into a page's stylesheet via ados.js.#azk12345 { width: auto; }
RawWraps 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.

Language
Credentials
Header