This endpoint requests an ad or multiple ads for display on pages throughout your site or app. The winning ad(s) result from an auction that the Koddi Ads platform runs in realtime, based on the business logic, bids and bid modifiers, and eligibility rules of your ad program.
Winning ads will return a list of the search-unique information and attributes for display of an ad, tracking data, and potentially an error message all contained within the response.
The parameters client_name, site and culture must match a unique valid combination (that will be provided by your Koddi team). No additional authentication is required for this endpoint.
A Note on UUIDs (aka GUID)
A UUID (or GUID) is an acronym for 'universally unique identifier' (or 'globally unique identifier'). It is a 128-bit integer number used to identify resources. More information can be found here.
You'll see we use GUIDs throughout the Koddi platform. We generally recommend that these values follow the format of a standard GUID, but realize there are times when that is not possible. When not possible, we ask that the ID you use contains only numbers and letters (no special characters). If that is not possible, your Koddi team can provide additional guidance.
Inputs
Sample Inputs
This is a sample - the actual parameters in the categories and targeting sections in your instance of Koddi Ads are configured for your use cases. Please work with your Koddi team on specifics.
{
"client_name": "Your Name",
"domain": "www.yoursite.com",
"site_id": "127",
"experience_name": "Onsite Display",
"page_name": "Search",
"max_requested": 25,
"slots_available": 5,
"bidders": [
{
"id": "27538",
"publisher_score": 1.23
},
{
"id": "345543",
"publisher_score": 1.00
},
{
"id": "657456",
"publisher_score": 0.89
},
{
"id": "857444",
"publisher_score": 0.50
}
],
"user": {
"guid": "[generated by publisher]",
"id": "[generated by publisher]",
"ip_address": "127.0.0.1",
"is_authenticated": false,
"culture": "en-US",
"currency": "USD",
"user_agent": "Chrome/20.0.1132.47"
},
"model": {
"algo_id": 0,
"allow_experimentation": true,
"name": "test_model",
"ab_segment_key": "pqs",
"test_version": [
"1202.2",
"9202.1",
"129.1"
]
},
"categories": {
"team": "Lions",
"gender": "W",
"category": "Apparel > Clothing > Shirts > Jerseys"
},
"targeting": {
"device_type": "Desktop",
"units": 2,
"new_cust": 0,
"value": 1,
"start": "1900-01-01",
"finish": "1900-01-02",
"hotel_country": "US",
"cuisine": [
"AmericanBreakfast"
]
},
"yield_management": {
"price_floor": 0,
"include_bids_below_price_floor": true,
"attributes": {
"market": [
"NY"
],
"adults": 5
}
}
}
| Field | Type | Description | Required | |
| client_name | string | Your company name. Your Koddi team will provide this value. | Required | |
| domain | string | This is the domain of the site calling for winning ads. The format is generally www.yoursite.com. This is used for downstream reporting only. | Optional | |
| site_id | string | This is the ID of the site calling for winning ads. The format is flexible (any string) and is intended to map to your POS structure in a fexible and easy way. You must provide Koddi with a list of all values that will be passed so that our system can be configured to accept them. |
Required | |
| experience_name | string | This is the name of the experience that corresponds to the auction. Please work with your Koddi team to know what possible values exist for this parameter. | Optional | |
| page_name | string | The name of the page on your site (search page vs details page, etc.)
Koddi requires a list of all values that will be passed, so that our system can be configured to accept them. |
Required | |
| max_requested | int | The max number of ads that will be returned by Koddi. | Optional | |
| slots_available | int | The number of slots that could be filled by ads on the page. Must be accurate to get proper coverage and inventory utilization metrics. | Required | |
| bidders | array of objects | The ids and corresponding publisher_scores for the auction. Duplicate values should be avoided. | ||
| id | string | The bidders for the auction. Duplicate values should be avoided. | Required if using bidders method | |
| publisher_score | float | The publisher score for the bidders. | Required if using bidders method | |
| user | object | Information about the user. | ||
| guid | string | Unique user ID generated by the publisher (used for tracking to conversion events). | Required | |
| id | string | Optional secondary user ID from the publisher site. | Optional | |
| ip_address | string | The end user's IP (where allowed by local law). This is only used for fraud detection and is deleted within 48 hours. Please consult with your Koddi team if local law prevents sharing this information. | Optional, but highly suggested for bot detection | |
| is_authenticated | bool | Is the user signed in to the publisher site? | Optional | |
| culture | string | This is the is the language of the user (site) calling for winning ads. Koddi suggests language-COUNTRY.
Koddi needs a listing of all values that might be passed before our system can be configured to accept them. |
Required | |
| currency | string | This is the is the currency of the user (site) calling for winning ads. We use the ISO 3 character code. | Required | |
| user_agent | string | The end user's user agent. This is used for fraud detection only. | Required | |
| model | object | Used for testing different ad treatments for users. Please contact your Koddi team to use this. | ||
| algo_id | int | Used for testing different ad treatments for users. Please contact your Koddi team to use this. | Optional | |
| allow_experimentation | bool | Used for testing different ad treatments for users. Please contact your Koddi team to use this. | Optional | |
| name | string | Used for testing different ad treatments for users. Please contact your Koddi team to use this. | Optional | |
| ab_segment_key | string | Used in certain instances to manually group an auction into a testing bucket. Please contact your Koddi team to use this. | Optional | |
| test_version | array of strings | Used for testing different ad treatments for users. Please contact your Koddi team to use this. | Optional | |
| categories | object | The categories that have been applied in user search (based on the inventory feed). The categories don’t need to be configured - the name of the category must match the column header in the inventory feed exactly. If your page contains multiple values for a single category, use a string array. For example: “Brand”: [“Nike”, “Jordan”] | ||
| targeting | object | The targeting that has been applied in user search. These will be configured by Koddi for you based on your use cases during the implementation of Koddi Ads. | ||
| device_type | string | The end user's device type.
One of the following: App-Phone App-Tablet Desktop Mobile-Phone Mobile-Tablet Please note that in some standard reports, the values are summed as follows: App-Phone --> App App-Tablet --> App Desktop --> Desktop Mobile-Phone --> Mobile Web Mobile-Tablet --> Mobile Web |
Optional | |
| hotel_country | string | The country the hotel is physically located. Please use standard 2 letter ISO codes on implementation. | Optional | |
| yield management | object | The yield management configuration that has been applied for the publisher. This can be configured by the publisher for specific search instances. | Optional | |
| include_bids_below_price_floor | bool | Would you like to include bids below the configured price floor in the auction? | Optional | |
| attributes | object | These will vary based on use case or specific publisher that these are enacted on - the above are just examples. | Optional |
Response
The winning ads endpoint responds with a click tracking URL, the ID of the winning bidder(s), an impression tracking URL which should be called when the ad impression occurs, the tracking string for both the click tracking and impression tracking URLs and other data (as configured). It is very important that the click and impression calls are built dynamically using the tracking data provided in this response.
Sample Response
This is a sample - the actual parameters in the call in your instance of Koddi Ads may vary. Please work with your Koddi team on specifics.
{
"errors": [],
"sponsored_listings": [
{
"click_tracking_url": "koddi.io",
"bidder": "100000006",
"advertiser_name": "Campbell's Soup",
"impression_tracking_url": "koddi.io",
"tracking_data": "encoded_string",
"cpm": 29,
"bid": 31,
"tracking_guid": "GUID",
"price_floor": 0.50,
"price_floor_type": 1,
"advertiser_metadata": {
"advertiser_type": "Marketplace"
},
"assets": {
"creative_url": "koddi.io",
"creative_destination": "koddi.io",
"creative_name": "Creative Name",
"creative_cta": "Buy Now"
}
}
]
}
The winning ads call will return an error message if a required data element is missing.
Otherwise, the call will return a 200 that either contains ads, or will be blank (meaning there is no active campaign for the criteria in the call).
If any additional error codes are returned, please work with your Koddi team to resolve them.