TinyTag service
The TinyTag Service enables you to create TinyTag IDs as well as modify and view them.
The IDs are associated with information about the ad space such as size, reserve price, and what brands or creatives are allowed to run in that space. This information is stored server side with Xandr and is easy to modify.
TinyTag IDs can be used in TinyTags, which are placed directly on publisher pages and take the basic form https://ib.``adnxs``.com/tt?id=1
. Further information can be passed in a TinyTag using Dynamic TinyTag Parameters.
Note that the member associated with the TinyTag ID has rights of first refusal on the inventory, and receives credit (or cash) if another member purchases it.
HTTP Method | Endpoint | Description |
---|---|---|
DELETE | https://api.adnxs.com/tt/MEMBER_ID/TAG_ID | Delete an existing TinyTag. |
GET | https://api.adnxs.com/tt/MEMBER_ID | View all TinyTags for a member. |
GET | https://api.adnxs.com/tt/MEMBER_ID/TAG_ID | View a particular TinyTag. |
POST | https://api.adnxs.com/tt/MEMBER_ID (tag JSON) |
Create a new TinyTag. |
PUT | https://api.adnxs.com/tt/MEMBER_ID/TAG_ID (tag JSON) |
Modify an existing TinyTag. |
Field | Required | Type | Description |
---|---|---|---|
acb_code |
no | string(32) | Not commonly used. |
active |
no, default is active | int | Boolean value determines whether the segment can be used |
ad_profile_id |
no | int | This is the ID of the ad approval profile used for creative quality standards. |
audit_level |
no | enum | Values for self-auditing only. Note: Self-audits at the site level can be overridden at the placement (tinytag) level. Possible values: - "tinytag" - Use this value if the audited field is set to true in the placement. - "site" - Use this value if the audited field is set to false in the placement but true in the site. |
audited |
no | boolean | If true, the placement has been self-audited by the owner. |
code |
no | string(100) | User-defined field for calling tag via codes. More info can be found on the Tinytag Page. |
code2 |
no | string(100) | Second code, if desired. |
content_retrieval_timeout_ms |
no | int | - If 0 , the ad server uses the value from the Member Service. - Defaults to 0 if not provided to the API on PUT or POST calls. - If ad server reads a 0 in this field, it performs a member lookup and use the default timeout defined by the Member Service (assuming it's also non-zero). - When creating a TinyTag, none of the values are copied into this field from the member's default settings. You must explicitly specify them in your calls to POST . For more information, see the default_content_retrieval_timeout_ms field of the Member Service. |
default_calculation_type |
no | enum | This determines the bid price threshold below which a default creative is served. You can choose whether this threshold is the network's gross revenue or the publisher's net revenue. If there are no additional eligible campaigns, nor any default creatives available, a PSA is served. Possible values: "gross" or "net". |
default_creative_id |
no | int | The default creative to run if no bids meet the reserve price. |
default_creatives |
no | array | The default creatives that display instead of a PSA when there is no auction winner. For each default creative, the reserve price is set with the "price" field in the array. See Default Creatives below for more details. Note: For pops placements: The placement does not pop if the reserve price is not met, except in the case of a prepop. |
default_referrer_url |
no | string | If a visibility profile is set to hide inventory urls in your bid requests, you can set this field to pass a vanity url instead. This is particularly useful in cases where publishers do not want to share actual domains but nonetheless want buyers to be able to identify them by domain. Note, however, that the vanity domain cannot be targeted directly by Xandr campaigns, although it can be targeted by external bidders. |
enable_for_mediation |
no | boolean | - This is the source of truth for whether a TinyTag should accept mediated content - Unless set on PUT or POST , this field inherits its default value from the member. If the default value is changed on the Member Service, that action does not retroactively impact TinyTags created previously; they continue to be set to the old default value. In other words, the value of this field cannot be updated retroactively by setting the member default. For more information, see the default_enable_for_mediation field of the Member Service. |
estimated_clear_prices |
no | The bid amount that has historically won the majority (95%) of the 3rd party auctions in which it participates. See Estimated Clear Price below for more details. | |
exclusive |
no, default is false | boolean | Read-only. This field has been Deprecated. This field formerly served as the default value for the exclusive behavior on a TinyTag. This setting is now controlled via the rtb field in the marketplace_map object of the site service. |
floor_application_target |
no | enum | The type of bids to which the reserve price is applied. Possible values: -"external_only" - The reserve price is applied only to external bids (buying member and selling member are different). Use this option if you would rather serve an available managed learn impression than serve a default, even if this means exceeding the maximum % of daily volume for learn. - "external_non_preferred" - The reserve price is applied to external bids (buying member and selling member are different) or when the impression is an available managed learn impression that exceeds the maximum % of daily volume for learn. Use this option if you would rather serve a default than serve an available managed learn impression that would exceed the maximum % of daily volume for learn. - "all" - The reserve price is applied to all bids except managed learn impressions within the maximum % of daily volume for learn. |
height |
no | int | The height of the tag in pixels. |
hide_referer |
boolean | Do not display the referer page. | |
id |
no, only on modify | int | Xandr ID assigned by the API to reference this tag. |
intended_audiences |
no | enum | Values for self-auditing only. Possible values: "general", "children", "young_adult", or "mature". |
inventory_attributes |
no | array | Values for self-auditing only. This is an array of objects with IDs. Please see the Inventory Attribute Service for a list of IDs. |
is_resizable |
no | boolean | If the placement uses a friendly iFrame and you want the placement to resize to fit smaller or larger creatives, set this field to true. |
last_activity |
no | timestamp | The timestamp of last modification to this tiny tag. |
media_subtypes |
no | enum | Deprecated. Please use supported_media_types and supported_media_subtypes instead. |
member_id |
yes | int | The member ID that owns this tag. Required for call, but not JSON. |
name |
no | string | Name associated with the TinyTag |
pixel_type |
no | enum | Identifies the type of pixel. Possible values are "script" or "image". |
pixel_url |
no | string | The location that the pixel notifies when a user clicks on that placement. |
pixel_url_secure |
no | boolean | Indicates whether the pixel URL points to an encyrpted web page. |
pop_values |
no | array | If the supported_media_type is "Pop", or the supported_media_subtypes is "Popup" or "Popunder", this array defines the behavior of the pop. See Pop Values below for more details. |
position |
no | enum | "above", "below", or "unknown" - the position of the TinyTag relative to the page fold |
publisher_id |
no | int | The ID of the publisher associated with the site that the tag is on. |
reserve_price |
no, default is $0 | double | The reserve price of the ad in $CPM - This is the lowest price that inventory owner is willing to sell for, otherwise the default creative is served. Note : this field is listed as "price" in the /meta listing. |
segments |
no | Array of objects | A user viewing this TinyTag is placed into all of the specified segments Example: "segments": [ {"segment_id":1} ] |
site_id |
yes | int | The ID of the site that the tag is associated with. The hierarchy is Sites > Tags. For more information about the Site Service, make a GET call to https://api.adnxs.com/site/meta. |
supported_media_subtypes |
no | array | The media subtypes that are allowed to serve on the placement. See Supported Media Subtypes below for more details. |
supported_media_types |
no | array | The media types that are allowed to serve on the placement. See Supported Media Types below for more details. |
tag_data |
no | string | Other information, often demographic or descriptive data. Sent only to the owner's bidder. See also qs_data in TinyTags. Note: this field is listed as "other_data" in the /meta listing. |
use_detected_domain |
no, default is true. | boolean | Read-only. Whether to use the detected domain versus the reported domain. Defaults to true for all clients. |
visibility_profile_id |
no | int | The ID of the visibility profile assigned directly to the placement. |
width |
no | int | The width of the tag in pixels. |
Creatives are categorized by media type and media subtype. Media type defines the general display style of the creative, for example, "Banner", and media subtype defines the specific display style of creatives, for example, "Standard Banner" or "In-Banner Video". You can use this array to limit the media type, the general display style of creatives, that can serve on a placement. To limit the media subtype, the specific display style of creatives, use the supported_media_subtypes array (see Supported Media Subtypes below).
Field | Type | Description |
---|---|---|
id |
int | The ID of the allowed media subtype. |
name |
string | Read-only. The name of the allowed media subtype. |
Creatives are categorized by media type and media subtype. Media type defines the general display style of the creative, for example, "Banner", and media subtype defines the specific display style of creatives, for example, "Standard Banner" or "In-Banner Video". You can use this array to limit the media subtype, the specific display style of creatives, that can serve on a placement. To limit the media type, the general display style of creatives, use the supported_media_types array (see Supported Media Subtypes above).
Field | Type | Description |
---|---|---|
id |
int | The ID of the allowed media subtype. |
name |
string | Read-only. The name of the allowed media subtype. |
Notes on Supported Media Types and Media Subtypes
If you do not specify either supported media types or supported media subtypes, the "Banner" media type is allowed by default.
You can combine the "Banner" and "Text" media types, and any combination of their media subtypes, on a single placement, but you cannot combine any of the other media types and media subtypes. This limitation ensures that only appropriate creatives are served on a placement. For example, a placement that allows creatives of the media type "Video" is intended to be fed to a video player; it would not make sense to allow creatives of any other media type, such as "Interstitial", to serve on the placement.
You can set a placement to allow the "Expandable" media type or any of its subtypes for direct inventory. If you want to support expandable creatives for placements that are available for reselling to other platform members, please provide the URL to support for verification.
You use this array to assign default creatives to the placement. Please note the following requirements:
- A default creative must not be expired. See the is_expired field in the Creative Service for more information.
- A default creative must be assigned to a creative template that matches the supported_media_types and supported_media_subtypes of the placement. For example, if the placement allows creatives of the "Banner" media type, you would not be able to associate default creatives that use a creative template for the "Interstitial" media type. See the template field in the Creative Service for more information.
- If the placement is sized (the "width" and "height" fields are defined for the placement), this array should contain only one creative with the matching dimensions.
Field | Type | Description |
---|---|---|
height |
int | The height of the default creative. |
id |
int | The ID of the default creative. |
name |
string | Read-only. The name of the default creative. |
price |
double | The reserve price for the default creative. A winning bid must be above this price. |
width |
int | The width of the default creative. |
If the supported_media_type is "Pop", or the supported_media_subtypes is "Popup" or "Popunder", these fields should be included in the "pop_values" array. Please see below for an example.
Field | Type | Description | Default |
---|---|---|---|
pop_freq_duration | int | See pop_freq_times. | No frequency cap |
pop_freq_times | int | Number of times that the tag can be popped to a unique user in pop_frequency_duration seconds. Has no effect when pop_is_prepop is set to true. | No frequency cap |
pop_is_prepop | boolean | If true, the tag is a prepop tag and serves into a window that the publisher page has already popped. | false |
pop_max_height | int | The max height of the creative. If pop_max_height is specified, any creative shown by the tag must have a height equal to or smaller than pop_max_height | no max height |
pop_max_width | int | If pop_max_width is specified, any creative shown by the tag must have a width equal to or smaller than pop_max_width | no max width |
Field | Type | Description |
---|---|---|
average_price | double | This is the average of all bids submitted for this placement. |
clear_price | int | The bid amount that has historically won the majority (95%) of the 3rd party auctions in which it participates for this placement. |
height | int | When exporting sizeless placement tags to be served, this determines the height of the placement. |
verified | boolean | Indicates whether the created prices are verified. |
width | int | When exporting sizeless placement tags to be served, this determines the width of the placement. |
$ cat tag
{
"tinytag":
{
"width": "728",
"height": "90",
"reserve_price": "5.00",
"default_creative_id": 212,
"active": true,
"tag_data": "male/22",
"ad_profile_id": 234
}
}
$ curl -b cookies -c cookies -X POST --data-binary @tag https://api.adnxs.com/tt/1/
{
"response": {
"status": "OK",
"id": "1234"
}
}
$ curl -b cookies -c cookies https://api.adnxs.com/tt/1/1234
$ curl -b cookies -c cookies [adnxs.com/tt/1/1234](https://api.adnxs.com/tt/1/1234)
{
"response": {
"tinytag": {
"id": 1234,
"width": "728",
"height": "90",
"member_id": 1,
"reserve_price": 5.00,
"default_creative_id": 212,
"tag_data": "male\/22",
"active": true,
"ad_profile_id": 234
},
"status": "OK"
}
}