Creative Builder - Criteo Docs

Getting StartedThe creative builder will enable to construction of new creatives through the API. In this document, you will find details regarding the different sections of a creative template variable. A creative comprises five template variable values, which is a required array used in the POST or PUT calls when building a new creative. Any existing template variable can be found under sections of the GET Retailer Template endpoint.

Endpoints

Verb	Endpoint	Description
GET	`/{retailer-id}/templates`	Get a list of available creative templates for a specified retailer
POST	`/{account-id}/creatives`	Create a new account creative
GET	`/{account-id}/creatives/{creative-id}`	Get account creative by creative id
PUT	`/{account-id}/creatives/{creative-id}`	Update an existing creative

Creative Attributes

string

Value: int64Is Nullable? NoId for the entity

type

string

Value: -Is Nullable? NoCanonical type name of the entity. These types correspond to the different values that can be set to a particular TemplateVariableValue

creativeFormat

enum , string

required

Is Nullable? NoCreative template available to use for template creationUnknown,FlagShip,Showcase,SponsoredProducts,Butterfly,BundleBoost,IAB,CUSTOM,DisplayPanel ,DigitalShelfTalker

name

string

required

Value: -Is Nullable? falseThe name of the template

retailerId

integer

Value: int32Is Nullable? NoThe retailer associated to the template

skuCollectionMin

integer

required

Value: int32Is Nullable? NoMin number of collections to configure in the ad

skuCollectionMax

integer

Value: int32Is Nullable? YesMax number of collections that can be configured in the ad

skuPerCollectionMin

integer

required

Value: int32Is Nullable? NoMin number of SKUs to be configured in the ad for each collection

skuPerCollectionMax

integer

Value: int32Is Nullable? YesMax number of SKUs to be configured in the ad for each collection

displayableSkusMax

integer

Value: int32Is Nullable? YesMax number of SKUs that can serve at once for this ad

allCollectionsMandatory

boolean

required

Value: true,falseIs Nullable? NoIf set to true, the ad will only serve if a SKU from each collection is available

createdAt

string

required

Value: date-timeIs Nullable? NoThe time at which the template was created

updatedAt

string

required

Value: date-timeIs Nullable? NoThe time at which the template was updated

creativeFormatType

integer

Value: -Is Nullable? NoType of creative format

environments

integer

Value: Web = 1 , Mobile = 2 , App = 3Is Nullable? NoType of web environment creative format is eligible to serve on

associatedLineItemsId

string

Value: int64Is Nullable? NoLine item ids that is associated with the creative

Environments Variable

Provides the list of environments details suitable for the ad, like page type and display environment

environments:pageType

enum | strings

required

Is Nullable? NoPage type where the creative is suitable to deliverUnknown,Search,Home,Browse,Checkout,Category,ProductDetail,Confirmation,Merchandising,Deals,Favorites,SearchBar,CategoryMenu

environments:environments

array of enum | strings

required

Is Nullable? NoList of environments per pageType where the creative is suitable to deliverWeb,Mobile,App,Lockout,Mixed,iOS,Android

Template Variable

Provides the template settings details, such as the type of variables available in each template.

templateVariable.id

string

required

Is Nullable? NoThe id of the template variable

templateVariable.required

boolean

required

Value: true, falseIs Nullable? NoPresents if the template variable is a required field

templateVariable.type

enum | strings

required

Is Nullable? NoThe type variable of the template settings. The variable type will determine which ChoiceVariableSpecification that can be usedText,Choice,Color,Files,Hyperlink

Template Variable | ChoiceVariableSpecification

This field wraps an array of strings that should contain the choices provided by the corresponding ChoiceVariableSpecification. Choice variables are optional, and they are equivalent to a set of drop-down choices one would select in the RMP UI.

choiceVariableSpecification.options.ChoiceOption.dependentVariables

string

required

Is Nullable? NoTemplate variables unblocked when the option is chosen

choiceVariableSpecification.options.ChoiceOption.id

string

required

Value: -Is Nullable? NoThe id of the option

choiceVariableSpecification.maxSelected

integer

Value: int32Is Nullable? YesThe maximum number of selectable options

choiceVariableSpecification.minSelected

integer

Value: int32Is Nullable? YesThe minimum number of selectable options

Template Variable | textVariableSpecification

Variables in the texVariableSpecification specifies the max number of characters

textVariableSpecification.maxChars

integer

Value: -Is Nullable? yesThe maximum amount of characters accepted for the text

Template Variable | filesVariablesSpecification

Present if the variable is set to one or more asset ids. The fields here specify the acceptable file extensions of the assets and the min and max numbers that can be provided.

filesVariablesSpecification.extensions

enum - string

required

Is Nullable? NoThe accepted file extensionsunknown,jpeg,png,gif,pdf

filesVariablesSpecification.maxBytes

integer

Value: int32Is Nullable? YesThe maximum amount of bytes per file

filesVariablesSpecification.minFiles

integer

required

Value: int32Is Nullable? YesThe minimum amount of files requires

filesVariablesSpecification.maxFile

integer

Value: int32Is Nullable? YesThe maximum amount of files required

Template Variable Value

Provided when creating (POST) or updating (PUT) a creative.

templateVariableValue.id

string

required

Value: -Is Nullable? NoThe id of the template variable the value is applied to. The id is equivalent to the template field name one would see in RMP. This variable in the POST/PUT calls informs which template fields to be modified.

templateVariableValue.textVariableValue.text

string

required

Value: -Is Nullable? NoThe displayed text

templateVariableValue.choiceVariableValue.chosenOptions

string

Value: -Is Nullable? NoThe chosen options

templateVariableValue.colorVariableValue.color

string

required

Value: -Is Nullable? FalseThe displayed color (HEX format)

templateVariableValue.filesVariableValue.assetIds

string

required

Value: min. length: 1Is Nullable? NoThe assets representing the images to be displayed

templateVariableValue.hyperlinkVariableValue.url

string

required

Value: -Is Nullable? NoThe url to redirect to

Get Retailer Templates

Get a list of available creative templates for a specific retailer Sample Request

curl -L -X GET 'https://api.criteo.com/{version}/retail-media/retailers/299/templates' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>'

Sample Response

JSON

{
    "data": [
        {
            "attributes": {
                "creativeFormat": "CUSTOM",
                "name": "Overrides Test Template",
                "retailerId": 299,
                "skuCollectionMin": 1,
                "skuCollectionMax": 20,
                "skuPerCollectionMin": 1,
                "skuPerCollectionMax": null,
                "displayableSkusMax": 5,
                "allCollectionsMandatory": false,
                "createdAt": "0001-01-01T00:00:00+00:00",
                "updatedAt": "0001-01-01T00:00:00+00:00",
                "sections": [
                    {
                        "title": "Background Images",
                        "description": null,
                        "templateVariables": [
                            {
                                "id": "desktop_background_image",
                                "required": false,
                                "type": "Files",
                                "filesVariablesSpecification": {
                                    "extensions": [
                                        "Jpeg",
                                        "Gif",
                                        "Png"
                                    ],
                                    "minFiles": 0
                                }
                            },
                            {
                                "id": "border_color",
                                "required": false,
                                "type": "Color"
                            },
                            {
                                "id": "button_color",
                                "required": false,
                                "type": "Color"
                            },
                            {
                                "id": "selected_button_color",
                                "required": false,
                                "type": "Color"
                            },
                            {
                                "id": "button_text_color",
                                "required": false,
                                "type": "Color"
                            },
                            {
                                "id": "selected_button_text_color",
                                "required": false,
                                "type": "Color"
                            }
                        ]
                    },
                    {
                        "title": "Redirection URL",
                        "description": null,
                        "templateVariables": [
                            {
                                "id": "optional_footer_type",
                                "required": false,
                                "type": "Choice",
                                "choiceVariableSpecification": {
                                    "options": [
                                        {
                                            "dependentVariables": [],
                                            "id": "Open a file"
                                        },
                                        {
                                            "dependentVariables": [],
                                            "id": "Legal Text"
                                        },
                                        {
                                            "dependentVariables": [],
                                            "id": "Open a link"
                                        }
                                    ]
                                }
                            },
                            {
                                "id": "optional_footer_redirect_target",
                                "required": false,
                                "type": "Choice",
                                "choiceVariableSpecification": {
                                    "options": [
                                        {
                                            "dependentVariables": [],
                                            "id": "On current page"
                                        },
                                        {
                                            "dependentVariables": [],
                                            "id": "On new page"
                                        }
                                    ]
                                }
                            },
                            {
                                "id": "optional_footer_text_color",
                                "required": false,
                                "type": "Color"
                            },
                            {
                                "id": "optional_footer_background_color",
                                "required": false,
                                "type": "Color"
                            },
                            {
                                "id": "optional_footer_type_2",
                                "required": false,
                                "type": "Choice",
                                "choiceVariableSpecification": {
                                    "options": [
                                        {
                                            "dependentVariables": [],
                                            "id": "Open a file"
                                        },
                                        {
                                            "dependentVariables": [],
                                            "id": "Legal Text"
                                        },
                                        {
                                            "dependentVariables": [],
                                            "id": "Open a link"
                                        }
                                    ]
                                }
                            },
                            {
                                "id": "optional_footer_redirect_target_2",
                                "required": false,
                                "type": "Choice",
                                "choiceVariableSpecification": {
                                    "options": [
                                        {
                                            "dependentVariables": [],
                                            "id": "On current page"
                                        },
                                        {
                                            "dependentVariables": [],
                                            "id": "On new page"
                                        }
                                    ]
                                }
                            },
                            {
                                "id": "optional_footer_text_color_2",
                                "required": false,
                                "type": "Color"
                            },
                            {
                                "id": "optional_footer_background_color_2",
                                "required": false,
                                "type": "Color"
                            },
                            {
                                "id": "redirect_target",
                                "required": false,
                                "type": "Choice",
                                "choiceVariableSpecification": {
                                    "options": [
                                        {
                                            "dependentVariables": [],
                                            "id": "On current page"
                                        },
                                        {
                                            "dependentVariables": [],
                                            "id": "On new page"
                                        }
                                    ]
                                }
                            },
                            {
                                "id": "footer_text_color",
                                "required": false,
                                "type": "Color"
                            },
                            {
                                "id": "footer_background_color",
                                "required": false,
                                "type": "Color"
                            }
                        ]
                    }
                ],
                "id": "52"
            },
            "id": "52",
            "type": "Template"
        }
    ],
    "warnings": [],
    "errors": []
}

Create Creative

The create creative endpoint will generate a new creative for an account id. The endpoint request body consists of an array called templateVariableValues which will be used to specify the template variables that will be modified during the creative generation.
The template variables that can be modified are dependent on each creative template. This information is provided in the GET | Retailer Templates response, under the templateVariables array.
Multiple template variables can be specified in each call. See the sample response for an example of how to set up the endpoint.

Creative Asset Upload APIThe Create Creative endpoint will require an assetId. Before generating a new creative ID, upload new creative assets files using the Creative Asset Upload endpoint to obtain the assetId.

Sample Request

curl -L -X POST 'https://api.criteo.com/{version}/retail-media/accounts/5/creatives' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "name": " Demo API CreativeV5",
    "brandId": 118301,
    "retailerId": 299,
    "templateId": 51,
    "templateVariableValues": [
        {
            "id": "cta_text",
            "textVariableValue": {
                "text": "Call To Action Text"
            }
        },
        {
            "id": "optional_footer_type",
            "choiceVariableValue": {
                "chosenOptions": [
                    "Open a file"
                ]
            }
        },
        {
            "id": "optional_footer_redirect_target",
            "choiceVariableValue": {
                "chosenOptions": [
                    "On current page"
                ]
            }
        },
        {
            "id": "button_text_color",
            "colorVariableValue": {
                "color": "#4C88a5"
            }
        },
        {
            "id": "footer_background_color",
            "colorVariableValue": {
                "color": "#2133CD"
            }
        },
        {
            "id": "desktop_background_image",
            "filesVariableValue": {
                "assetIds": [
                    "000b34dae90dfe5831e95600dc02ed5f3b4d9f52c4955a804eb26bbe9c29f470"
                ]
            }
        },
        {
            "id": "optional_redirect_url",
            "hyperlinkVariableValue": {
                "url": "https://www.criteo.com"
            }
        }
    ]
}'

Sample Response

{
    "data": {
        "attributes": {
            "name": " Demo API CreativeV5",
            "status": "Ready",
            "brandId": 118301,
            "retailerId": 299,
            "associatedLineItemIds": [],
            "updatedAt": "2022-10-05T16:25:15.1327786+00:00",
            "creativeFormatType": 0,
            "environments": [
                {
                    "pageType": "Category",
                    "environments": [
                        "Web"
                    ]
                }
            ],
            "templateVariableValues": [
                {
                    "id": "desktop_background_image",
                    "filesVariableValue": {
                        "assetIds": [
                            "000b34dae90dfe5831e95600dc02ed5f3b4d9f52c4955a804eb26bbe9c29f470"
                        ]
                    }
                },
                {
                    "id": "optional_redirect_url",
                    "hyperlinkVariableValue": {
                        "url": "https://www.criteo.com"
                    }
                }
            ],
            "id": "365534915380219904"
        },
        "id": "365534915380219904",
        "type": "Creative"
    },
    "warnings": [],
    "errors": []
}

Get Creatives

Get account creative by creative id Sample Request

curl -L -X GET 'https://api.criteo.com/{version}/retail-media/accounts/5/creatives/365342206324719616' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>'

Sample Response

{
    "data": {
        "attributes": {
            "name": " Demo API Creative",
            "status": "Ready",
            "brandId": 118301,
            "retailerId": 299,
            "associatedLineItemIds": [],
            "updatedAt": "2022-10-05T03:39:29.7085127+00:00",
            "creativeFormatType": 0,
            "environments": [
                {
                    "pageType": "Category",
                    "environments": [
                        "Web"
                    ]
                }
            ],
            "templateVariableValues": [
                {
                    "id": "desktop_background_image",
                    "filesVariableValue": {
                        "assetIds": [
                            "000b34dae90dfe5831e95600dc02ed5f3b4d9f52c4955a804eb26bbe9c29f470"
                        ]
                    }
                },
                {
                    "id": "button_text_color",
                    "colorVariableValue": {
                        "color": "#4C88a5"
                    }
                },
                {
                    "id": "optional_footer_type",
                    "choiceVariableValue": {
                        "chosenOptions": [
                            "Open a file"
                        ]
                    }
                },
                {
                    "id": "optional_footer_redirect_target",
                    "choiceVariableValue": {
                        "chosenOptions": [
                            "On current page"
                        ]
                    }
                },
                {
                    "id": "footer_background_color",
                    "colorVariableValue": {
                        "color": "#2133CD"
                    }
                }
            ],
            "id": "365342206324719616"
        },
        "id": "365342206324719616",
        "type": "Creative"
    },
    "warnings": [],
    "errors": []
}

Update Creatives

The endpoint will allow for updating existing creatives. The API endpoint request body uses the same templateVariableValues model as the one used in the POST | Create Creative call, but this time allows for updating any of the existing template variable fields.

Changes to the Creative ID when Updating CreativesWhen generating a new creative, the initial id is known as a “parentId,” of the creative. Every new update made to that creative creates a new “childId” which is a copy of the previous creative containing new updates. This means that the creativeId will change whenever a new update is made to the creative.To ensure that your line item is using the correct creativeId, your application will need to call the latest creativeId from the Get Creatives endpoint before associating a new creative to the line item.

Sample Request
In this example, updates are made to change the brandId, optional_footer_type, button_text_color, footer_background_color

curl -L -X PUT 'https://api.criteo.com/{version}/retail-media/accounts/5/creatives/365534915380219904' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "name": " Demo API CreativeV5_Updated",
    "brandId": 2000030397,
    "retailerId": 299,
    "templateId": 51,
    "templateVariableValues": [
        {
            "id": "cta_text",
            "textVariableValue": {
                "text": "Call To Action Text"
            }
        },
        {
            "id": "optional_footer_type",
            "choiceVariableValue": {
                "chosenOptions": [
                    "Legal Text"
                ]
            }
        },
        {
            "id": "optional_footer_redirect_target",
            "choiceVariableValue": {
                "chosenOptions": [
                    "On current page"
                ]
            }
        },
        {
            "id": "button_text_color",
            "colorVariableValue": {
                "color": "#fe5000"
            }
        },
        {
            "id": "footer_background_color",
            "colorVariableValue": {
                "color": "#fe5000"
            }
        },
        {
            "id": "desktop_background_image",
            "filesVariableValue": {
                "assetIds": [
                    "000b34dae90dfe5831e95600dc02ed5f3b4d9f52c4955a804eb26bbe9c29f470"
                ]
            }
        },
        {
            "id": "optional_redirect_url",
            "hyperlinkVariableValue": {
                "url": "https://www.criteo.com"
            }
        }
    ]
}'

Sample Response

{
    "data": {
        "attributes": {
            "name": " Demo API CreativeV5_Updated",
            "status": "Ready",
            "brandId": 2000030397,
            "retailerId": 299,
            "associatedLineItemIds": [],
            "updatedAt": "2022-10-05T16:32:54.290397+00:00",
            "creativeFormatType": 0,
            "environments": [
                {
                    "pageType": "Category",
                    "environments": [
                        "Web"
                    ]
                }
            ],
            "templateVariableValues": [
                {
                    "id": "desktop_background_image",
                    "filesVariableValue": {
                        "assetIds": [
                            "000b34dae90dfe5831e95600dc02ed5f3b4d9f52c4955a804eb26bbe9c29f470"
                        ]
                    }
                },
                {
                    "id": "optional_redirect_url",
                    "hyperlinkVariableValue": {
                        "url": "https://www.criteo.com"
                    }
                }
            ],
            "id": "365534915380219904"
        },
        "id": "365534915380219904",
        "type": "Creative"
    },
    "warnings": [],
    "errors": []
}

​Endpoints

​Creative Attributes

​Environments Variable

​Template Variable

​Template Variable | ChoiceVariableSpecification

​Template Variable | textVariableSpecification

​Template Variable | filesVariablesSpecification

​Template Variable Value

​Get Retailer Templates

​Create Creative

​Get Creatives

​Update Creatives

Endpoints

Creative Attributes

Environments Variable

Template Variable

Template Variable | ChoiceVariableSpecification

Template Variable | textVariableSpecification

Template Variable | filesVariablesSpecification

Template Variable Value

Get Retailer Templates

Create Creative

Get Creatives

Update Creatives