Image ad items (commonly known as "display ads") are an effective medium for delivering advertising messages across multiple platforms. They are easy to setup and configure because they require only a creative (i.e. an image file) and, when applicable, a destination URL to which users will be redirected when the ad is clicked.
In general, ad items are assigned to an advertiser campaign, and in turn the campaign to a zone. Ad items can also be assigned directly to a zone, but we recommend doing so only if the ad items are directly related to that zone's publisher or are intended to be default/house ads.
x-group: Campañas - name: Ad Items / Custom HTML description: >-Creating a custom HTML ad item is the best option if you need to serve a third-party advertisement from an ad network or another advertiser, or if you want to create an ad that cannot be achieved using traditional display advertising.
Custom HTML ad items allow you to implement virtually any type of ad using Haku’s ad serving macros and a text box.
In general, ad items are assigned to an advertiser campaign, and in turn the campaign to a zone. Ad items can also be assigned directly to a zone, but we recommend doing so only if the ad items are directly related to that zone's publisher or are intended to be default/house ads.
x-group: Campañas - name: Ad Items / Native description: >- Native ad items use native templates to create seamless editorial content.Ad item companion products link an ad item to a product in a product DB catalog. Each companion product belongs to a single ad item and references a specific product via a catalog ID and product identifier (SKU).
Companion products are nested under ad items and can be
managed under both
/ad-items/image/{ad_item_id}/companions/products and
/ad-items/native/{ad_item_id}/companions/products.
Requires the Display Ad Item Companions and Product DB Replicated features.
x-group: Retail media - name: AdServe description: > For server-side ad requests via JSON API, use the adserve endpoint to request ad items in JSON format from the ad server.Ad items represent the particular catalog item (product) being promoted. One or more catalog ad items may be assigned to a campaign.
x-group: Retail media - name: Ad Items / Catalog Item / Bulk description: >-Bulk operations for catalog ad items. These endpoints allow you to create or delete multiple catalog ad items at once and assign them to campaigns.
x-group: Retail media - name: Zones / Catalog description: >-A catalog zone is the representation of a source of promoted product ads. Advertiser campaigns would be assigned to catalog zones (called a placement), making them eligible to be matched against when making an ad request.
x-group: Retail media - name: Creatives (All) description: >- Creatives are the displayed part of an ad item. It can be an image, HTML5/rich media, custom HTML, or video. x-group: Campañas - name: Creatives / Image description: >- The image file that makes up an advertisement is known as the image creative. You can create a new image creative, retrieve one or more image creatives, update an existing image creative, or delete the image creative. x-group: Campañas - name: Data Keys description: >- Aside from keywords, location, and platform-based targeting, Haku also lets you target specific audiences using key value-based attributes. These are called data keys. For example, you can use data keys to target a specific age, gender, or date. Like the other forms of targeting, you must create and define data keys before you can use them. Data keys simply hold the value of attributes. After creating and defining data keys, you must create [Data Key Targets](#tag/Data-Key-Targets) to set up the actual targeting filters. For more information, read How to create data keys and data key targets via API. x-group: Targeting - name: Data Key Targets description: >- Data Key targets are used hand-in-hand with [Data Keys](#tag/Data-Keys) to create custom targeting filters. For more information, read How to create data keys and data key targets via API. x-group: Targeting - name: Geo Targets description: >-Geographic targets ("geo targets") enable you to deliver advertisements to users based on their geographic location. This is an effective way of reducing wasted impressions and increasing your return on investment.
Geographic targeting can be as generic as continents or as specific as cities. A geo target may contain as many areas as desired which can vary in specificity. (For example, an area of "South America" and an area of a specific city could exist in the same geo target.) Geo targets can either be inclusive or exclusive.
x-group: Targeting - name: Media Groups description: >- Media groups allow you to group creatives together for easier organization and management in your account. x-group: Campañas - name: Native Templates description: >- Native templates define the styles and formatting of native ads. Once a template is created it can then be applied, reused, and edited as needed to make native ad items.Native ads are ads that look like editorial content. For example, a native ad on a blog looks like the other articles on the site, a native ad on Instagram looks like an Instagram post, and a native ad on a search engine looks like other search results. Native ads are also known as sponsored content or promoted posts. x-group: Inventario - name: Placements description: >- Assign an advertisement or campaign to a zone based on a set of scheduling criteria using the placements endpoint. Each placement represents a combination of criteria required to serve an advertisement. Prior to creating a placement, you will need to have created several other resources: * An [ad item](#tag/Ad-Items-(All)), * a [campaign](#tag/Campaigns-(All)), * a [zone](#tag/Zones-(All)), * and a [schedule](#tag/Schedules) You also have the option to create targeting filters, keywords, and activity limits to further control the deliverability of your placements. x-group: Campañas - name: Platform Targets description: >-Target your advertisements to specific mobile/tablet/notebook/desktop devices, or to specific browsers and operating systems to help ensure users get the best ads for their platform. You can also target specific mobile phones or tablets, such as iPhones or Samsung devices using device targeting filters.
x-group: Targeting - name: Product DB / Catalog description:Product catalogs that can be used for product-based advertising.
x-group: Retail media - name: Product DB / Catalog Items description: >-Product catalog items that can be used for product-based advertising.
x-group: Retail media - name: Product DB / Catalog Items / Bulk Upload description: >-Bulk upload a catalog CSV with column names that match the fields submitted to a catalog.
x-group: Retail media - name: Product DB / Publisher Sources description: >-Publisher Sources that can be used for product-based advertising targeting.
x-group: Retail media - name: Product DB / Publisher Source Targets description: >-Publisher Source Targets that can be used for product-based advertising targeting.
x-group: Retail media - name: Publishers description: >- A publisher is typically a person or a company who owns a website, app, newsletter, or even another ad server. Each publisher will have one or more zones, which represent the locations on their websites, apps or newsletters where advertisements can be displayed. x-group: Inventario - name: Reports description: >-Reporting is the new interface to Statistics. It serves to quantify the serving of your advertisements across price and performance related metrics. They are updated in real time. We go to great lengths to give you detailed and accurate data about the performance of your advertisements to help you make informed decisions. The following endpoints enable you to build your own reporting dashboard.
x-group: Reportes - name: Schedules description: >- Schedules describe the conditions necessary for serving advertisements. Common conditions include start and end dates, and quotas. You can also use delivery methods to determine the expiration and pacing set up for advertisements. Default delivery delivers the impressions as quickly as possible, while smooth delivery will evenly serve impressions over the lifetime dates and quotas. For example, with smooth delivery, if your campaign has a quota of 30,000 impression set over a period of 60 days, the system would serve the assignment 500 times per day. Smooth delivery assignments have the highest potential priority for serving within Haku. If a quota has not been filled then that assignment will generally always serve as long as a targeting system does not interfere. __NOTE__: Schedules have no effect on their own and must be referenced through their ID. For campaigns with campaign-level scheduling, the schedule must be referenced in the [placement](#tag/Placements). For campaigns with ad item-level scheduling, the schedule must be referenced in the [campaign assignment](#tag/Campaign-Assignments) for each ad item in the campaign. Multiple placements and assignments can reference the same schedule, so they can share the same quota, start/end dates, and other common settings. x-group: Campañas - name: Zones (All) description: > Zones represent the space on a Publisher's website where ads are displayed ("served"). A zone's size can either be fixed or dynamic. The types of zones are: * __Standard__ - The most common, used to serve various ads including image, HTML5/Rich Media, Native Ads or third party scripts. * __VAST__ - Used to serve VAST video ads. * __Email__ - Used to serve image ads in emails and newsletters. x-group: Inventario - name: Zones / Standard description: >- The most common zone type. Used to serve image ads (JPG,PNG, or GIF), HTML5/Rich Media, or third party scripts. x-group: Inventario paths: /campaigns/{id}/eligible-zones: get: tags: - Campaign Assignments summary: Get eligible zones for a campaign description: >- Returns zones that can be assigned to the given campaign. Each zone includes an `assigned` flag indicating whether the campaign is already assigned to that zone. Zones may be standard, email, or catalog. parameters: - $ref: '#/components/parameters/path_id' - $ref: '#/components/parameters/list_limit' - $ref: '#/components/parameters/list_offset' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/eligible_zone_list' '404': $ref: '#/components/responses/resource_does_not_exist' components: parameters: path_id: name: id in: path description: Identifier of the resource. required: true schema: type: integer example: 1234 list_limit: name: limit in: query description: >- The number of objects returned in the response, sometimes called "take". The max value is __100__. schema: type: integer list_offset: name: offset in: query description: The position to start the retrieval of objects, sometimes called "skip". schema: type: integer schemas: eligible_zone_list: type: object allOf: - $ref: '#/components/schemas/list' - properties: url: description: >- Schemas for the campaign eligible zones list endpoint. The endpoint returns zones that can be assigned to a campaign, with an `assigned` flag per zone. example: /v2/campaigns/1234/eligible-zones data: description: >- List of eligible zones. Each item is a zone (standard, email, or catalog) with an `assigned` flag. type: array items: $ref: '#/components/schemas/eligible_zone_item' type: object list: properties: object: description: For list resources, the value of 'object' will always be 'list'. type: string example: list has_more: description: True if there are more data beyond the offset and limit. type: boolean example: false limit: description: The number of resources to return. Sometimes called 'take'. type: integer example: 10 offset: description: >- The number of resources in sequence to ignore, sometimes called 'skip'. type: integer example: 0 type: object eligible_zone_item: type: object allOf: - oneOf: - $ref: '#/components/schemas/standard_zone_get' - $ref: '#/components/schemas/email_zone_get' - $ref: '#/components/schemas/catalog_zone_get' - properties: assigned: description: Whether the campaign is currently assigned to this zone. type: boolean example: false type: object error_resource_does_not_exist: properties: http_status: type: integer example: 404 type: type: string example: resource_not_found_error message: type: string example: Resource not found. type: object standard_zone_get: allOf: - $ref: '#/components/schemas/resource_get' - $ref: '#/components/schemas/standard_zone' - properties: object: description: >- A string denoting the current resource being requested or affected. type: string readOnly: true example: standard_zone self: description: >- The relative URL of the current resource being requested or affected. type: string readOnly: true example: /v2/zones/standard/1234 use_share_of_voice: description: >- Whether the zone should use "share of voice" as its serving strategy. If this is set to false, the zone will use "weight" as its serving strategy. type: boolean example: true type: object email_zone_get: allOf: - $ref: '#/components/schemas/resource_get' - $ref: '#/components/schemas/email_zone' - properties: object: description: >- A string denoting the current resource being requested or affected. type: string readOnly: true example: email_zone self: description: >- The relative URL of the current resource being requested or affected. type: string readOnly: true example: /v2/zones/email/1234 type: object catalog_zone_get: properties: object: description: A string denoting the current resource being requested or affected. type: string example: catalog_zone self: description: >- The relative URL of the current resource being requested or affected. type: string example: /v2/zones/catalog/104339 id: description: The current resource identifier (ID). type: integer example: 104339 name: description: The name of the catalog zone type: string example: Product DB catalog_id: description: The identifier (ID) of the catalog type: integer example: 74374 publisher: description: The identifier (ID) of the publisher to which the zone belongs type: integer example: 53563 metadata: description: An object containing any number of metadata fields and values. type: object example: [] bid_floor: description: The default bid floor for this zone type: number format: float example: 0 bid_floor_cpm: description: Sets the bid floor for CPM in the zone type: number format: float example: 1.1 bid_floor_cpc: description: Sets the bid floor for CPC in the zone type: number format: float example: 1.3 advertiser_cost_type: description: >- Configures the zone to charge the advertiser by either impression (CPM) or by clicks (CPC) type: string example: CPC auction_type: description: Sets the type of auctions in this zone type: string example: SECOND_PRICE click_cooldown_period: description: The cooldown period for users clicking on the same advertisement type: integer example: 60 conversion_lookback_period: description: The conversion lookback period type: integer example: 7776000 type: object allOf: - $ref: '#/components/schemas/catalog_zone' resource_get: properties: object: description: A string denoting the current resource being requested or affected. type: string readOnly: true self: description: >- The relative URL of the current resource being requested or affected. type: string readOnly: true id: description: The current resource identifier (ID). type: integer readOnly: true example: 1234 type: object standard_zone: required: - name properties: name: description: >- The name of the zone. We recommend using a naming scheme that is descriptive, relevant, and consistent. type: string example: Zone Name dimensions: description: >- The type of dimensions to which the zone should adhere. "__fixed__" dimensions require a `width` and `height` to determine how the ad will be displayed, whereas "__dynamic__" dimensions leave the width and height to be set by the site serving the ad. type: string example: fixed width: description: >- The width of the standard zone (see common ad item dimensions). The height and width of the zone must match the size of the ad items that will be displayed within it. These values must be given if dimensions are "__fixed__". It must be __0__ or not given if dimensions are "__dynamic__". type: integer example: 300 height: description: >- The height of the standard zone (see common ad item dimensions). The height and width of the zone must match the size of the ad items that will be displayed within it. These values must be given if dimensions are "__fixed__". It must be __0__ or not given if dimensions are "__dynamic__". type: integer example: 250 publisher: description: The identifier (ID) of the publisher to which the zone belongs. type: integer example: 5223151 popup_frequency: description: >- The number of impressions after which a popup is displayed. It lets you control how often the popups should be served. For example, setting the value to __1__ means a popup will be displayed each time the page is loaded, while setting it to __5__ means a popup will be displayed after every five impressions. Defaults to __0__, which means never show a popup. type: integer deprecated: true refresh_frequency: description: >- The interval (in seconds) after which a new ad is shown in the zone without requiring a page reload. This allows serving multiple impressions in one viewing session, making the most of your ad space on content heavy pages where the user will be spending a lot of time reading, such as an article or a forum thread. Defaults to __0__, which means the zone will not be served new ads without a page reload. __NOTE__: - If Unique Delivery is on, the interval must be equal to the number of ad items in the zone or assigned campaign - Third party scripts relying on `document.write` may not serve properly when using JavaScript zone tags. type: integer refresh_limit: description: >- The total number of times the zone will be refreshed with a new ad. Defaults to __0__, which means zone will never be refreshed with a new ad. type: integer responsive: description: >- Whether the size of the ad is fixed (__"fixed"__), resizeable (__"auto"__), or subject to the CSS of the page (__"inherit"__). The __"fixed"__ option makes the ad item match the zone size when it is served. The __"auto"__ option resizes the zone to fit the size of the served ad item. The __"inherit"__ option lets CSS on the page decide the size of the zone. __TIPS__: - Use __"auto"__ if there is a chance that no ad may be served, which may be the case if you are using targeting and quotas. This will allow Haku to collapse the empty zones. - Do not use __"auto"__ when using asynchronous tags with a raw HTML ad item. Otherwise the ad will not display properly because iframes conflict with responsive pages. - Do not use __"ASync JavaScript"__ or __"IFrame"__ tags with __"auto"__ and __"inherit"__. type: string example: auto unique_delivery: description: >- Whether unique ads are served on each zone. It requires the use of JavaScript tags. Unique Delivery ensures that each zone will show an ad item from different campaigns, making it ideal for pages where the same zone tag is used multiple times. When set to 'true', the number of campaigns assigned to the zone must be greater than or equal to the number of instances of the zone on the page. type: boolean example: false iab_categories: description: >- A list of [IAB Categories](#iab-categories) that describe the content and purpose of the app or site to which the zone belongs. __NOTE__: This feature requires the Programmatic add-on. If you don't have the add-on, you must set this field's value to __null__ or an empty array. type: array items: type: string example: - iab2 - iab7 allow_demand_sources: description: >- Whether to allow this zone to make requests to Demand Endpoints for bids. __NOTE__: This feature requires the Programmatic add-on. If you don't have the add-on, you must set this field's value to __false__. type: boolean example: true bid_floor: description: >- The default bid floor for this zone when sending bids to programmatic demand partners. __NOTE__: This feature requires the Programmatic add-on. If you don't have the add-on, you must set this field's value to __0__. type: number format: float example: 0 min_payout: description: >- The minimum amount that will be paid out to the publisher for an impression in CPM (cost per thousand). __NOTE:__ This field is for Programmatic (through Demand Endpoints) impressions only. type: number format: float example: 0.75 serve_priority_order: description: >- The order of priority when choosing a serving method. When set to __"weight"__, ads are chosen in the order of Smooth-Delivery > Weight > Auction. When set to __"auction"__, ads are chosen in the order of Smooth-Delivery > Auction > Weight. Defaults to __"weight"__. type: string example: weight pmp_deals: description: >- An array of PMP Deal IDs that are allowed in this zone. __NOTE__: This feature requires the Programmatic add-on. If you don't have the add-on, you must set this field's value to __null__ or an empty array. type: array items: type: integer example: - 10075 - 10115 private_auction: description: >- Whether the auction will ignore non-deal bids. __NOTE__: This feature requires the Programmatic add-on. If you don't have the add-on, you must set this field's value to __false__. type: boolean example: true optimization_strategy: description: The optimization strategy for the zone. type: string example: global_ecpm burn_in_impressions: description: >- The number of impressions required for a placement before we are confident in its eCPM. type: integer example: 100000 burn_in_hours: description: >- The number of hours a placement must be live before we are confident in its eCPM. type: integer example: 24 ecpm_testing_allowance: description: >- The percentage of non-burn-in impressions that will be given to placements with a less than optimal eCPM. This allows for eCPM recalculations on placements that were originally thought to be low in value. type: number format: float example: 0.3 metadata: description: >- An object containing any number of metadata keys and values. Keys and values must be strings. type: object example: btf: 'true' mobile_only: 'false' 'rtb_placement_id ': description: >- Required for OpenRTB requests. Sets the `tagid` field in the request. The `tagid` is the identifier of a specific ad placement or the ad tag that was used to initiate the auction. __NOTE__: The ability to participate in OpenRTB auctions via Haku requires subscribers to have the Programmatic Advertising add-on. If you don't have this add-on, you must set this field's value to __null__. type: string example: '123' 'api_frameworks ': description: >- Required for OpenRTB requests. Sets the `api` field in the `banner` object. The banner specifies the list of supported API frameworks for this impression. __NOTE__: The ability to participate in OpenRTB auctions via Haku requires subscribers to have the Programmatic Advertising add-on. If you don't have this add-on, you must set this field's value to __null__ or an empty array. type: array items: type: string example: - ormma auction_tie_break: description: Determines the method for breaking ties in auction mediation. type: string enum: - RANDOM - SCORE example: RANDOM allowed_root_native_templates: description: >- An array of allowed root native template IDs for this zone. This is used to restrict the native ad templates that can be served in this zone. If not set, all native ad templates are allowed. type: array items: type: integer example: - 1234 - 5678 ad_size_filter: description: >- Defines the ad size filter for the zone. Only works with dynamic zones. Requires the Zone Ad Size Filtering add-on. properties: type: description: >- The type of ad size filtering for this zone. When set to INCLUSIVE, only ad items matching the ad size filter sizes will be served in the zone. When set to EXCLUSIVE, only ad items that do not match the ad size filter sizes will be served in the zone. type: string enum: - INCLUSIVE - EXCLUSIVE example: INCLUSIVE sizes: description: The type of ad size filtering for this zone. type: array items: properties: width: description: Width of the ad size filter. type: integer example: 300 height: description: Height of the ad size filter. type: integer example: 250 type: object example: width: 300 height: 250 type: object type: object email_zone: required: - name - width - height properties: name: description: >- The name of the zone. We recommend using a naming convention that is descriptive, relevant, and consistent. type: string example: Zone Name width: description: The width of the email zone. type: integer example: 250 height: description: The height of the email zone. type: integer example: 300 publisher: description: The identifier (ID) of the publisher to which the zone belongs. type: integer example: 62353314 metadata: description: >- An object containing any number of metadata keys and values. Keys and values must be strings. type: object example: btf: 'true' mobile_only: 'false' uid_rotate: description: >- When set to 'true', this email zone will be allowed to serve different ads to the same email per user. When false, it will only get one ad per email per user. Defaults to 'false'. type: boolean example: true rotate_timer: description: >- An object indicating the period after which a user can see a new ad for this email zone. The 'amount' field is an integer 0 or greater. The 'interval' field must be one of 'minutes', or 'days'. If 'minutes', 'amount' is limited 10080. if 'days', 'amount' is limited to 7 type: object example: amount: 30 interval: minutes auction_tie_break: description: Determines the method for breaking ties in auction mediation. type: string enum: - RANDOM - SCORE example: RANDOM type: object catalog_zone: properties: name: description: The name of the catalog zone type: string maxLength: 255 example: Promotions catalog_id: description: The identifier (ID) of the catalog type: integer example: 74374 publisher: description: The identifier (ID) of the publisher to which the zone belongs type: integer example: 53563 bid_floor: description: The default bid floor for this zone type: number format: float example: 0 bid_floor_cpm: description: >- Sets the bid floor for CPM in the zone, bids below this will be eliminated. This value can be overridden at the time of the ad request. This should be set if the advertiser_cost_type is CPM. It is assumed to be in the publisher's currency. type: number format: float example: 1.1 bid_floor_cpc: description: >- Sets the bid floor for CPC in the zone, bids below this will be eliminated. This value can be overridden at the time of the ad request. This should be set if the advertiser_cost_type is CPC. It is assumed to be in the publisher's currency. type: number format: float example: 1.3 advertiser_cost_type: description: >- Configures the zone to charge the advertiser by either impression (CPM) or by clicks (CPC). The valid values are CPM or CPC, it will default to CPC. type: string enum: - CPM - CPC example: CPC auction_type: description: >- Sets the type of auctions in this zone, values are either FIRST_PRICE or SECOND_PRICE. It will default to SECOND_PRICE. type: string enum: - FIRST_PRICE - SECOND_PRICE example: SECOND_PRICE click_cooldown_period: description: >- Adjusts the cooldown period for users clicking on the same advertisement more than once within a designated period. Expects a value between 1 and 86400 inclusive (seconds). Default 3600 seconds. type: integer maximum: 86400 minimum: 1 example: 60 conversion_lookback_period: description: >- Adjusts the conversion lookback period which controls the period of time which it would be possible to record a conversion for a given click. Expects a value between 1 and 7776000 inclusive (seconds). Default 7776000 seconds (90 days). type: integer maximum: 7776000 minimum: 1 example: 7776000 type: object responses: resource_does_not_exist: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/error_resource_does_not_exist' securitySchemes: API Key: type: apiKey in: header name: Authorization description: >- API key en el header `Authorization: Basic TU_API_KEY`. La key va tal cual, sin codificar en base64. Las credenciales se entregan al comenzar la integración. ````