Ads - Kleio API Reference

Ads are the core entity around which more or less all of Kleio operates. On this page, we will look into the intricacies of ads and how to think of them. We will also look into the notion of `tags`` and how tags can be used for targeting.

The ad model

The ad model contains a variety of data. Some of these properties are ones you can set the value of yourself, others are read-only, populated, and maintained by the system itself. Most properties are also optional.

Properties

Name
product_id
Type
string
Description
The id of the product being advertised. This should be an ID that makes sense to you - typically it is the ID you use to reference the product in your system.
Name
max_bid
Type
integer
Description
The maximum amount of money an advertiser is willing to pay for a conversion of their ad. The value must be a whole integer and there is no specific currency implied. If you want to support fractional units of money, you should multiply the bid by a constant. For example, if you want to support €-cent you should use 100 for a max_bid of €1.
Name
ad_id
Type
string
Description
This is the ID of the ad within the Kleio ad server. It is set and managed by Kleio.
Name
name
Type
string
Description
A name associated with an ad, to more easily distinguish multiple ads for the same product. Has no bearing on the auctions.
Name
description
Type
string
Description
A description associated with an ad. Can serve as an aid for human users of the system. Has no bearing on the auctions.
Name
tags
Type
[string]
Description
An array of strings. These tags can later be used to include certain ads in an auction.
Name
metadata
Type
string
Description
Arbitrary metadata that you might want to associate with an ad. This data is ignored by Kleio when it comes to ad targeting and other similar behavior but will be returned alongside winning ads. This makes it useful for passing data through Kleio which might be necessary for you to later succesfully render the ad.
Name
budget
Type
integer
Description
The maximum total amount an advertiser is willing to pay across any number of conversions. Note that because there might be a time delay between an ad having won an auction and the ad converting, the budget might be overshot.
If you leave this property unset, the ad will continue to run indefinitely. That is to say, it will continue to be eligible to participate in ad auctions. Whether it wins or not is dependent on the max_bid property, the targeting, and how well the ad performs.
Name
spent
Type
integer
Description
A running accumulator of the money spent on this ad.
When an ad wins the second-price auction, it wins with a bid. Should the ad subsequently convert (i.e. you track a conversion), then the bid it won the auction with is added to this spent value.
When the spent equals or exceeds the budget column, the ad stops being eligible for being auctioned.
Name
converts_on
Type
string
Description
Can take one of three values: impression, click, manual.
This property allows you to specify what is considered a conversion for a specific ad. If an ad is sold on an impression basis (pay per view), then you can set it to impression and the auction system will consider each impression a success. If you are operating with a setup where a user needs to click on an ad for it to be considered a success (pay per click), then you can set it to click. If your definition of conversion differs from either impressions or clicks, then set it to manual, but please do realize that in this case you need to manually track the conversion using the conversion tracking endpoint!
This property defaults to click.
Name
impressions
Type
integer
Description
The number of impressions that have been tracked against this particular ad. This property is managed by Kleio.
Name
conversions
Type
integer
Description
The number of conversions that have been tracked against this particular ad. This property is managed by Kleio.
Name
created_at
Type
timestamp
Description
Timestamp of when the ad was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the ad was last updated.

GET/api/v1/ads

List all ads

This endpoint allows you to list all ads associated with your account. You might also be interested in products resource. It gives you a similar result but groups the ads by the product they are for.

Request

GET

/v1/contacts

curl -G https://example.com/api/v1/ads \

Response

{
  "data": [{
    "id": "be50c003-58f2-42db-9718-2d380174ffd1",
    "product_id": "1539",
    "max_bid": 1500,
    "budget": 1600000,
    "spent": 2014,
    "name": "Roadbike XT in Racing Green",
    "description": "Spring campaign",
    "metadata": "{\"tag\": \"Seasonal offer\"}",
    "tags": ["search", "new-ribbon"],
    "converts_on": "click",
    "impressions": 1290,
    "conversions": 19,
    "created_at": "<DATETIME>",
    "updated_at": "<DATETIME>"
  },
  ...]
}

POST/api/v1/ads

Create an ad

This endpoint allows you to add a new ad to Kleio.

As Kleio is an ad server with a focus on making it possible to showcase products in product listings, each ad has to be associated with a product and there might be more than one ad associated with a given product.

As an example, let's assume you own an e-commerce website selling shoes from different brands. On your website, you likely have a front page, and a category listing showing a variety of shoes, in addition to a search. One of your suppliers might want particular shoes featured across your store. In this case, you would create an ad for the particular shoe. If the supplier is willing to pay more to be prominently featured in search than on other surfaces, you might create an additional ad with a higher bid, specifically targeting the search surface. In this case, you end up creating two ads for what is a single product in your store. For a more detailed example of how this type of targeting might work, please check out the targeting-guide.

Please note that there is no need to explicitly create, or manage, products in Kleio,

Required attributes

Name
product_id
Type
string
Description
The id of the product you would like to advertise. This should be an ID that makes sense to you - typically it is the ID you use to reference the product in your system.
Name
max_bid
Type
integer
Description
The maximum amount of money an advertiser is willing to pay for a conversion of their ad. The value must be a whole integer and there is no specific currency implied. If you want to support fractional units of money, you should multiply the bid by a constant. For example, if you want to support €-cent you should use 100 for a max_bid of €1.

Optional attributes

Name
name
Type
string
Description
A name associated with an ad, to more easily distinguish multiple ads for the same product. Has no bearing on the auctions.
Name
description
Type
string
Description
A description associated with an ad. Can serve as an aid for human users of the system. Has no bearing on the auctions.
Name
metadata
Type
string
Description
Arbitrary metadata that you might want to associate with an ad. This data is ignored by Kleio when it comes to ad targeting and other similar behavior but will be returned alongside winning ads. This makes it useful for passing data through Kleio which might be necessary for you to later succesfully render the ad.
Name
tags
Type
[string]
Description
An array of strings. These tags can later be used to include certain ads in an auction.
Name
budget
Type
integer
Description
The maximum total amount an advertiser is willing to pay across any number of conversions. Note that because there might be a time delay between an ad having won an auction and the ad converting, the budget might be overshot.
If you leave this property unset, the ad will continue to run indefinitely. That is to say, it will continue to be eligible to participate in ad auctions. Whether it wins or not is dependent on the max_bid property, the targeting, and how well the ad performs.
Name
converts_on
Type
string
Description
Can take one of three values: impression, click, manual.
This property allows you to specify what is considered a conversion for a specific ad. If an ad is sold on an impression basis (pay per view), then you can set it to impression and the auction system will consider each impression a success. If you are operating with a setup where a user needs to click on an ad for it to be considered a success (pay per click), then you can set it to click. If your definition of conversion differs from either impressions or clicks, then set it to manual, but please do realize that in this case you need to manually track the conversion using the conversion tracking endpoint!
This property defaults to click.

Request

POST

/api/v1/ads

curl -H "Content-Type: application/json" \
  --data '{
    "product_id": "1539",
    "name": "Roadbike XT in Racing Green",
    "description": "Spring campaign",
    "metadata": "{\"tag\": \"Seasonal offer\"}",
    "max_bid": 1500,
    "budget": 1600000,
    "converts_on": "impression",
    "tags": ["search", "new-ribbon"]
  }' \
  https://example.com/api/v1/ads

Response

{
  "data": {
    "id": "59b05f3c-1397-4135-9e32-cdce5ff17736",
    "product_id": "1539",
    "name": "Roadbike XT in Racing Green",
    "description": "Spring campaign",
    "metadata": "{\"tag\": \"Seasonal offer\"}",
    "max_bid": 1500,
    "budget": 1600000,
    "spent": 0,
    "converts_on": "impression",
    "tags": [
      "search",
      "new-ribbon"
    ],
    "impressions": 0,
    "conversions": 0,
    "created_at": "<DATETIME>",
    "updated_at": "<DATETIME>"
  }
}

GET/api/v1/ads/:id

Retrieve an ad

This endpoint returns a specific ad by its id. The id is the ID of the ad within Kleio, and is not to be confused with the product_id. If you are looking for a way to get the ads associated with a specific product_id, you should take a look at the products resource instead.

Request

GET

/api/v1/ads/:id

curl -G https://example.com/api/v1/ads/7fc7668c-a20d-4184-8ded-47ed19c50b44 \

Response

{
  "data": {
    "id": "7fc7668c-a20d-4184-8ded-47ed19c50b44",
    "product_id": "1539",
    "name": "Roadbike XT in Racing Green",
    "description": "Spring campaign",
    "metadata": "{\"tag\": \"Seasonal offer\"}",
    "max_bid": 1500,
    "budget": 1600000,
    "spent": 0,
    "tags": [
      "search",
      "new-ribbon"
    ],
    "converts_on": "click",
    "impressions": 0,
    "conversions": 0,
    "created_at": "<DATETIME>",
    "updated_at": "<DATETIME>"
  }
}

PUT/api/v1/ads/:id

Update an ad

This endpoint allows you to update an existing ad in Kleio.

You only need to include the properties you would like to change in your request. The ones you do not include will not be affected.

Optional attributes

Name
product_id
Type
string
Description
The id of the product you would like to advertise. This should be an ID that makes sense to you - typically it is the ID you use to reference the product in your system.
Name
max_bid
Type
integer
Description
The maximum amount of money an advertiser is willing to pay for a conversion of their ad. The value must be a whole integer and there is no specific currency implied. If you want to support fractional units of money, you should multiply the bid by a constant. For example, if you want to support €-cent you should use 100 for a max_bid of €1.
Name
name
Type
string
Description
A name associated with an ad, to more easily distinguish multiple ads for the same product. Has no bearing on the auctions.
Name
description
Type
string
Description
A description associated with an ad. Can serve as an aid for human users of the system. Has no bearing on the auctions.
Name
metadata
Type
string
Description
Arbitrary metadata that you might want to associate with an ad. This data is ignored by Kleio when it comes to ad targeting and other similar behavior but will be returned alongside winning ads. This makes it useful for passing data through Kleio which might be necessary for you to later succesfully render the ad.
Name
tags
Type
[string]
Description
An array of strings. These tags can later be used to include certain ads in an auction.
Name
budget
Type
integer
Description
The maximum total amount an advertiser is willing to pay across any number of conversions. Note that because there might be a time delay between an ad having won an auction and the ad converting, the budget might be overshot.
If you leave this property unset, the ad will continue to run indefinitely. That is to say, it will continue to be eligible to participate in ad auctions. Whether it wins or not is dependent on the max_bid property, the targeting, and how well the ad performs.
Name
converts_on
Type
string
Description
Can take one of three values: impression, click, manual.
This property allows you to specify what is considered a conversion for a specific ad. If an ad is sold on an impression basis (pay per view), then you can set it to impression and the auction system will consider each impression a success. If you are operating with a setup where a user needs to click on an ad for it to be considered a success (pay per click), then you can set it to click. If your definition of conversion differs from either impressions or clicks, then set it to manual, but please do realize that in this case you need to manually track the conversion using the conversion tracking endpoint!
This property defaults to click.

Request

PUT

/api/v1/ads/:id

curl -X PUT \
  -H "Content-Type: application/json" \
  --data '{
    "max_bid": 90,
    "tags": ["search", "cart-before-checkout", "recommendations"]
  }' \
  https://example.com/api/v1/ads/7fc7668c-a20d-4184-8ded-47ed19c50b44

Response

{
  "data": {
    "id": "7fc7668c-a20d-4184-8ded-47ed19c50b44",
    "product_id": "1539",
    "name": "Roadbike XT in Racing Green",
    "description": "Spring campaign",
    "metadata": "{\"tag\": \"Seasonal offer\"}",
    "max_bid": 90,
    "budget": 1600000,
    "spent": 0,
    "tags": [
      "search",
      "cart-before-checkout",
      "recommendations"
    ],
    "converts_on": "click",
    "impressions": 0,
    "conversions": 0,
    "created_at": "<DATETIME>",
    "updated_at": "<DATETIME>"
  }
}

DELETE/api/v1/ads/:id

Delete an ad

This endpoint allows you to delete an ad from Kleio.

This is not to be confused with deleting a product. A product (and all associated ads) can be deleted using the products API endpoint.

Request

DELETE

/api/v1/ads/:id

curl -X DELETE \
  https://example.com/api/v1/ads/7fc7668c-a20d-4184-8ded-47ed19c50b44