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: /placements/{id}: get: tags: - Placements summary: Get a Single Placement parameters: - name: id in: path description: Identifier of the placement you'd like to get. required: true schema: type: integer example: '' - $ref: '#/components/parameters/fields' responses: default: description: successful operation content: application/json: schema: $ref: '#/components/schemas/placement_get' components: parameters: fields: name: fields in: query description: >- Restrict the fields you wish to retrieve by listing the desired fields formatted as a comma-separated list. Fields like "object", "self", and "id" are always returned. schema: type: string schemas: placement_get: properties: created_date: description: The date and time when the ad item placement was created. type: string format: date-time example: '2019-04-17 16:31:02' object: description: A string denoting the current resource being requested or affected. type: string example: placement self: description: >- The relative URL of the current resource being requested or affected. type: string example: /v2/placements/1234 id: description: The current resource identifier (ID). type: integer example: 1234 type: object allOf: - $ref: '#/components/schemas/placement' placement: properties: active: description: >- Whether to actively serve ads in the zones (__true__) or pause ad serving (__false__). Defaults to true. type: boolean example: true advertisement: description: >- An object containing the campaign identifier and type when creating a placement for a campaign. Otherwise, provide the appropriate ad item identifier or bidder identifier along with the corresponding type. __NOTE__: Subscribers on the Standard tier and below must have the Enhanced Ads add-on to create new rich media ads and native ads, as well as to change existing ads to either of those ad item types. Further, subscribers must have the Programmatic Advertising add-on to create programmatic ads. type: object allOf: - $ref: '#/components/schemas/placement_advertisement' channel: description: >- If assigned to a channel, this is the channel ID. This field cannot be given if `zone` is given. Either `zone` or `channel` are required in a POST. __NOTE__: Only subscribers on the Standard tier and above can create channels or assign campaigns to channels. If you don't have that feature, you must set this field's value to null. type: integer example: null cost: description: >- An object associating a pricing model with the performance of your ad item placement. This information will be used to calculate the revenue generated by your ad. You can either use a fixed cost or a rate-based pricing model for your ad placements. Fixed cost is tied to the amount of quota and is given as `{ 'fixed_cost': 0.00 }` You can also use a rate-based pricing model by specifying `cpm`, `cpc`, and `cpa` values as `{ 'cpm': 0.00, 'cpc': 0.00, 'cpa': 0.00 }`. This field is considered a classic PUT: any properties not included in the `cost` field will be set to __0.00__, even if the property already has a value. type: object example: cpm: 2.84 cpc: 2.56 cpa: 3.916 allOf: - $ref: '#/components/schemas/placement_cost' day_cap_limit: description: >- This field has been moved to the schedule object and is now deprecated. type: integer example: null deprecated: true day_cap_type: description: >- This field has been moved to the schedule object and is now deprecated. type: string example: views deprecated: true geo_target: description: >- The geotarget identifier (ID) if you want your ads to be delivered to a particular location only. This will direct your audience to ads in their region. Defaults to __null__, which means geographic targeting is not in effect. __NOTE__: For campaigns, this can be set only if the [campaign's](#tag/Campaigns-Standard) `targeting_source` was set to **"CAMPAIGN"**. Otherwise, targeting can be configured only in [Campaign Assignments](#tag/Campaign-Assignments). In addition, your subscription must have the Complete Targeting add-on to use this feature. If you don't have the add-on, you must set this field's value to __null__. type: integer example: 12345 keywords: description: >- Specify words separated by commas to determine if this ad should be served if a match is found on the page. You can use an asterisk ("\*") to represent a wildcard in a keyword. For example, __"paint\*"__ would match paint, painter, painting, paints, and all other variations. You can also stop the ad from being served in presence of a specific word by prepending a negative sign (-) to the word. For example, __"-paint"__ would stop the ad from being delivered if the word "paint" is found on the page. __NOTE__: For campaigns, this can be set only if the [campaign's](#tag/Campaigns-Standard) `targeting_source` was set to **"CAMPAIGN"**. Otherwise, targeting can be configured only in [Campaign Assignments](#tag/Campaign-Assignments). type: string example: example, keyword, list keywords_match_method: description: >- Defines the level of keyword targeting. Has three possible values: **"required"**, **"preferred"** or **"filtered"**. Set this to **"required"** to serve the ad only if a keyword match is found. Set this to **"preferred"** to increase the serving priority of an ad whenever a match is found. Set this to **"filtered"** to require a keyword match for the ad to be served without affecting the serving priority. __NOTE__: For campaigns, this can be set only if the [campaign's](#tag/Campaigns-Standard) `targeting_source` was set to **"CAMPAIGN"**. Otherwise, targeting can be configured only in [Campaign Assignments](#tag/Campaign-Assignments). type: string example: preferred payout: description: >- This information will be used to calculate the payout to the ad's publisher. Percentage-based payouts will be calculated based on the placement's `cost` values, whereas rate-based payouts are independent of the placement's `cost`. Any combination of the four properties (`fixed`, `cpm`, `cpc`, `cpa`) can be given; however, `fixed` payout will be ignored for rate-based payout if any of the other three `cpx` properties are set. This field is considered a classic PUT: any properties not included in the payout field will be set to __0.00__, even if the property already had a value. type: object example: type: rate cpm: 1.6 cpc: 1.75 cpa: 2.3 allOf: - $ref: '#/components/schemas/placement_payout' payout_percent: description: >- The percentage of the ad generated revenue paid out to the publisher. __DEPRECATED:__ This field has been expanded to the more detailed `payout`, though it may still be used as a simplified version. We encourage updating to use `payout` as `payout_percent` will likely be removed in later versions of the API. type: number format: float example: null deprecated: true per_user_view_limit: description: >- This field has been moved to the schedule object and is now deprecated. type: integer example: null deprecated: true per_user_view_period: description: >- This field has been moved to the schedule object and is now deprecated. type: integer example: null deprecated: true platform_target: description: >- The platform target identifier (ID) if you intend to restrict delivery of your ads to a certain device or a platform. Defaults to __null__, which means platform targeting is not in effect. __NOTE__: For campaigns, this can be set only if the [campaign's](#tag/Campaigns-Standard) `targeting_source` was set to **"CAMPAIGN"**. Otherwise, targeting can be configured only in [Campaign Assignments](#tag/Campaign-Assignments). In addition, your subscription must have the Targeting add-on to use this feature. type: integer example: 12345 priority: description: >- A value specifying whether to prefer serving of some ads over others in a campaign or channel. Allowable values in order of decreasing priority: __"sponsorship"__, __"standard"__, __"network"__, __"bulk"__, and __"house"__. type: string example: standard serve_method: description: >- Whether the placement is served using a weight-based (__"weight"__) or auction-based (__"auction"__) system. Defaults to __"weight"__. Auction-based placements are served based on their CPM and schedule. Weight is ignored for these placements and they are served using the default `delivery_method` regardless of their assigned schedule. Weight-based placements are served based on their weight and schedule. These placements can still have a CPM associated with them, but the CPM does not affect serving and is only used for reporting. __NOTE__: The serve method cannot be changed. Further, the auction-based system is available only to subscribers who have the Programmatic Advertising or Self-Serve Marketplace add-ons. If you don't have either of these add-ons, you must set this field's value to __"weight"__. type: string example: weight schedule: description: >- The schedule identifier (ID). __NOTE__: For campaigns, this can be set only if the [campaign's](#tag/Campaigns-Standard) `scheduling_source` was set to **"CAMPAIGN"**. Otherwise, scheduling can be configured only in [Campaign Assignments](#tag/Campaign-Assignments). type: integer example: 888 weight: description: >- A number used to determine the serving frequency of an advertisement. This number is used to compute the probability of an ad being served in a particular zone or channel. Can only be used in zone or channel that uses "weight" as its serving strategy. Defaults to 1, which means every ad has an equal chance of being served. For example, consider three ad items assigned to a zone or channel with weights of 1, 4 and 5. The ratio works out to a corresponding probability of 10%, 40% and 50% chance of each ad item being served. type: integer example: 1 share_of_voice: description: >- A number used to determine the serving frequency of an advertisement. Required when placement is assigned to a zone or channel that uses "share of voice" as its serving strategy. The sum of the share of voice for all placements in a zone or channel cannot exceed 100. type: integer example: 25 zone: description: >- If assigned to a zone, this is an object containing `type` and the zone ID. This field cannot be given if `channel` is given. Either `zone` or `channel` are required in a POST. The `type` value can be either **standard_zone** or **email_zone**. type: object example: id: 999 type: standard_zone allOf: - $ref: '#/components/schemas/placement_zone' data_key_target_id: description: >- The Data Key Target identifier (ID). __NOTE__: For campaigns, this can be set only if the [campaign's](#tag/Campaigns-Standard) `targeting_source` was set to **"CAMPAIGN"**. Otherwise, targeting can be configured only in [Campaign Assignments](#tag/Campaign-Assignments). In addition, only Enterprise subscribers have access to the [Data Keys](#tag/Data-Keys) feature. If you don't have that feature enabled, you must set this field's value to __null__ or __0__. type: integer example: 10000 list_target: description: >- The List Target identifier (ID) if you want your ads to be delivered based on the inclusion or exclusion of specific values in their respective lists. Defaults to null which means list targeting is not in effect. __NOTE:__ For campaigns, this can be set only if the campaign's targeting_source was set to "CAMPAIGN". Otherwise, targeting can be configured only in Campaign Assignments. In addition, you need to have List Targeting enabled in your account to use this feature. If you don't have that feature enabled, you must set this field's value to null. type: integer example: 12345 contextual_segments: description: An array of contextual segment identifiers (IDs). type: array items: type: integer example: - 1125 - 1128 audience_segments: description: >- Field for an upcoming feature. For now, set this field's value to __null__ or an empty array. type: array items: type: integer example: - 1125 - 1128 custom_segment_definition: description: >- The [Custom Segment Definition](#tag/Custom-Segments-Definitions) identifier (ID) if you want this placement targeted at the members that definition selects. Defaults to null, which means custom segment targeting is not in effect. The member is identified on the ad call by the `custom_segment_member` parameter. A placement carries a single definition, so a second rule set needs a second definition on a second placement. __NOTE:__ you need Custom Segments enabled in your account to use this feature. If you don't have that feature enabled, you must set this field's value to null. type: integer example: 10000 type: object placement_advertisement: required: - id - type properties: id: description: Identifier of the advertisement. (ID) type: integer example: 222 type: description: >- The type of advertisement, allowable values include: __"image_ad_item"__, __"custom_html_ad_item"__, __"rich_media_ad_item"__, __"s2s_ad_item"__, __"standard_campaign"__, and __"bidder"__. type: string example: standard_campaign type: object placement_cost: properties: fixed_cost: description: >- The total cost of the campaign. It is the fixed cost of the placement, not influenced by impressions, clicks, or actions. This property cannot be given if `cpm`, `cpc`, or `cpa` are given. Values are rounded to the nearest 100th (two decimal places). type: number format: float cpm: description: >- Cost per thousand impressions. This property cannot be given if `fixed_cost` is given. Values are rounded to the nearest 1000th (three decimal places). type: number format: float cpc: description: >- Cost per click. This property cannot be given if `fixed_cost` is given. Values are rounded to the nearest 1000th (three decimal places). type: number format: float cpa: description: >- Cost per action. This property cannot be given if `fixed_cost` is given. Values are rounded to the nearest 1000th (three decimal places). type: number format: float type: object placement_payout: required: - type properties: type: description: >- The type of payout the publisher will recieve. Accepted values are __"percent"__ or __"rate"__. This field is required when specifying a `payout`. type: string fixed: description: >- The fixed payout of the placement. Values are rounded to the nearest 100th (two decimal places). When using this field, it is not influenced by impressions (cpm), clicks (cpc), or actions (cpa). Inversely, then the cpm, cpc, and cpa fields are used, this field is disabled. type: number format: float cpm: description: >- Cost per mille, or simply the cost per 1,000 impressions. Values are rounded to the nearest 100th (two decimal places). type: number format: float cpc: description: >- Cost per click. Values are rounded to the nearest 100th (two decimal places). type: number format: float cpa: description: >- Cost per action (conversion). Values are rounded to the nearest 100th (two decimal places). type: number format: float type: object placement_zone: required: - id - type properties: id: description: Identifier of the zone. (ID) type: integer type: description: >- Type of zone. Accepted values: __"standard_zone"__, __"text_zone"__, and __"email_zone"__. type: string type: object 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. ````