Why Update a Creative Template

There may come a time when you need to update an existing creative template that is part of your network. The Update Creative Template API endpoint enables you to not only update a new creative template for your network and all associated creatives, but you can also use this endpoint to archive a creative template by updating individual parameters on the creative template, or sending the entire template to be updated.

API Syntax

When using the Update 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/{CreativeTemplateID}/update

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.
CreativeTemplateID - the ID associated with the creative template you want to update.
update - the action being taken with this API call.

Request Format

The body of the request is a JSON Updates object that contains one or more objects with the following:

Key

Type

Example

Path (vector)

Required. A vector representing a path to an nested element: each element indicates a “level” of the underlying object.

A path of [] means "the whole object". Use this path to update the entire template in its entirety.

[ "Fields", 0, "Description" ] refers to the Description property of the first creative template field. (Note the zero-indexing)

Op
(string)

The operation to perform on the Path. Choose one from Update, Delete, InsertAfter. Defaults to update

Delete

Value
(As appropriate)

Required only for Update or InsertAfter. The new value to use with the Op. A value of [] used with "Update" deletes all the elements of the .Path

false

"New Description"

{ "Name" : "A new field", ... }

❗️
Warning
You cannot update the Type, Required, AdQuery, or Variable name of an existing field.

🚧
Caution
Updating a creative template will update all creatives that use that template. These changes will take effect immediately in ad serving.

Error Handling

Errors will be returned in an Errors object. This object will detail the Original state of the template, the intended Updates, the Proposed template after updates, and the Errors in question.

{
  "Errors": [
    {
      "Details": {
        "Original": {
          "Id": 198,
          "Name": "to be updated",
          "Description": "v1",
          "IsArchived": false,
          "Fields": [
            {
              "Name": "Awesome Thing",
              "Description": "Awesomeness to display",
              "Required": true,
              "Variable": "ctAwesome",
              "Type": "String"
            }
          ],
          "Contents": [
            {
              "Type": "HTML",
              "Body": "Guess what is awesome? {{ctAwesome}} is!"
            }
          ]
        },
        "Updates": [
          {
            "Path": [
              "Fields",
              0
            ],
            "Op": "InsertAfter",
            "Value": {}
          }
        ],
        "Proposed": {
          "Id": 198,
          "Name": "to be updated",
          "Description": "v1",
          "IsArchived": false,
          "Fields": [
            {},
            {
              "Name": "Awesome Thing",
              "Description": "Awesomeness to display",
              "Required": true,
              "Variable": "ctAwesome",
              "Type": "String"
            }
          ],
          "Contents": [
            {
              "Type": "HTML",
              "Body": "Guess what is awesome? {{ctAwesome}} is!"
            }
          ]
        },
        "Errors": [
          {
            "Path": [
              "Fields",
              0
            ],
            "Value": {},
            "Message": "Value at '[\"Fields\" 0]' does not contain required key(s) 'Type', 'Variable', and 'Name'."
          }
        ]
      },
      "Message": "The proposed changes would result in an invalid creative template"
    }
  ]
}