This endpoint requests an ad or multiple ads for ad placements 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 in rank order of the page-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 experience_name must match a unique valid combination (that will be provided by your Koddi team). No additional authentication is required for this endpoint by default, but an API key can be implemented if needed.

📘
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": "Experience 1",
    "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(Usage of this field is strongly suggested if utilizing the Koddi SSP)
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 and if utilizing the Koddi SSP
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.
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.

Try It!

200200

400400