API DocsKnowledge BaseSystem StatusContact SupportContact Sales
API Documentation

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 for you 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. The format is:

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

Where:

  • POST - the type of API request being made.
  • https://api.kevel.co - the 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.

The Fields of a creative template set which fields a UI user should enter for a creative. Each Field has its own object:

KeyType
Name
(string)		Required. The name of the field. Must be 255 characters or less. Example: "Caption"
Variable
(string)		Required. The macro name of the field to be used in the Contents and/or accessed via a Decision API response. The macro name must begin with "ct". Example: "ctCaption" and may only contain letters, numbers and the underscore character.
Type
(string)		Required. The data type of the field. See the table below. Example: "String"
Required
(boolean)		If true, the field will be validated as required when the creative is saved. A required field cannot also be Hidden. Defaults to false
Description
(string)		A description of the field for the UI. Example: "This is the caption for the ad."
Hidden
(string)		If true, sets whether the field is hidden in the UI. Defaults to false.
Default
(string (if Type is string) or array (if Type is array))		Required only if Hidden is true, otherwise not allowed. It sets a default value for the field. Example:

"a" (if string)

["a", "b", "c"] (if array)
AdQuery
(boolean)		If true, the field can be queried via the AdQuery feature.
MaxBytes
(integer)		The size limit, in bytes, of a file uploaded for this field. Cannot exceed 2 MB (2097152 bytes), and will default to 2 MB if omitted. MaxBytes is only evaluated when the field Type is File.
AllowedValues
(array)		When provided, inputs into String and Number fields must be one of specified values in the array. Example: ["a", " b", "c"]
Regex
(string)		When provided, inputs into String fields must conform to the specified regex pattern.
AllowPhraseMatch (boolean)Enables phrase or "fuzzy" matching on String type fields using AdQuery. See AdQuery documentation for more details.

🚧

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 of the field will be the Default.

📘

Note

There is a maximum of 100 fields per creative template.

🚧

Restrictions When Adding Custom Validation

AllowedValues and Regex rules can be defined on fields in new Creative Templates and on new fields for existing templates. After a field with validation rules has been saved to a Creative Template the only change that can be made is to add additional allowed values. These restrictions are in place to prevent pre-existing Creatives from entering an invalid state due to the field rules changing.

Field Types

The table below lists the different types of fields that may be used as part of the POST API call when creating a new creative template.

ValueDescriptionExample
StringA string. Max length of String values is 20,000 characters"This is some text"
FileA file uploaded directly via the Kevel UI or API. The file name itself uses the Variable name {{ctImage}}."http://static.adzerk.net/ad.gif"
ExternalFileAn external URL of an image"http://domain.com/ad.gif"
ArrayAn array of strings. For example, a list of tracking pixels to be served with the ad["http://domain.com/pixel1.gif","http://domain2.com/pixel2.gif"]
NumberA float0.5
1744819
ObjectAn object. Max size of Object values is 1 KB{ "SKU": "ZG011AQA", "Name": "Coca-Cola with Coffee Dark Blend - 12 fl oz", "AdvertiserId": 1, "image": "https://example.s3.amazonaws.com/Coca+Cola+with+Coffee.jpg", "price": "2.39", "description": "Great Coca-Cola taste infused with Brazilian coffee in Coca-Cola with Coffee Dark Blend." }

If your template creative requires uploading multiple images, you will need a file Field for uploading the image and a string Field for the image's path. The sum of all files uploaded to a single Creative cannot exceed 10 MB—for example, 5 file fields each with a 2 MB image. See the example Fields below:

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

Contents Object

A creative template can have 0 or more Contents that determine how the data set in the Fields should be outputted into the creative.

Each Contents field has a Type that corresponds to the data type ados.js , which should be used to render the creative, and the Body of the Content will be written to contents of the creative.

📘

Note

There is a maximum of 10KB (or 10000 characters) of Contents data per template.

KeyType
Type
(string)		Required. The data type ados.js should use to render the creative. Ex: "HTML"
Body
(string)		The data that should be written to the body of the creative. Max 10000 characters. Can use macros. Ex: "
Check out my cool caption: {{ctCaption}}
"

Content Types

ValueDescriptionExample(s)
HTMLIf served via ados.js, executes the HTML on a page. Can also use macros for displaying uploaded images, etc.

This does not wrap the data in any tags, so it can also be used for non-HTML data types such as XML or JSON.		`
This is the name: {{ctName}}


{{contentUrl}}/{{ctImage}}

{"foo":"bar"}

bar`
JavaScriptIf served via ados.js, executes JavaScript code in a <script> tag. You can define new functions, integrate with code currently running on the page, etc.No example available
JavaScriptExternalIf served via ados.js, executes an externally hosted JavaScript file, written into <script src="..."> tags. Use the full path to the file.http://domain.com/script.js
CSSIf served via ados.js, adds CSS into a page's stylesheet.`#azk12345 { width: auto; }

# azk{{placement.div.id}} { width: auto; }`
RawIf served via ados.js, wraps the data in a friendly Kevel iframe.

If served via the Decision API, can be used for any data type.		`{{contentUrl}}/{{ctImage}}

{"JSON":true}
`

🚧

Caution

Since Decision API responses do not render creatives on a page, the value of a Type will instead be rendered as the type in response, and the Body as body.

Language
Credentials
Header