You can use the placement resource to retrieve all placements and packages, retrieve a specific placement or package, create a placement or package, and update an existing placement or package.
A package is a form of media buy in which multiple placements are bought from the site as a group sharing the same cost and impression goal.
|
HTTP Method |
URI |
Description |
|---|---|---|
|
/placements/ |
Retrieves multiple placements. |
|
|
/placements/{id} |
Retrieves a specific placement. |
|
|
/placements/packages |
Retrieves multiple packages. |
|
|
/placements/packages/{id} |
Retrieves a specific package. |
|
|
/placements |
Creates a placement. |
|
|
/placements |
Creates multiple placements. |
|
|
/placements/packages |
Creates a package. |
|
|
/placements/delete |
Deletes a placement. |
|
|
/placements/packages/{id} |
Deletes a specific package. |
|
|
/placements/{id} |
Updates a specific placement. |
|
|
/placements/packages/{id} |
Updates a specific package. |
|
|
/placements/generateTag |
Generate a placement tag. |
Important
Important:
-
For PUT calls, do the following:
-
For any PUT method that updates an object, make sure that you include the entire "result": object from the GET response in the request body. If there is missing information, even if it is read-only, the request might fail or override the existing fields with the new values.
-
You must also change the "result": to "entities": and make the entities contents into an array. For example, here is the output from the GET request:
{ "result": { "type": "Advertiser", ... } }You should make the following modifications, including your specific modifications, to the json object that you submit for the request.
{ "entities": [{ "type": "Advertiser", ... }] }
-
-
For POST calls, do the following:
-
Include the fields marked as Required, as indicated in the corresponding Object article.
-
Format the JSON object as follows:
{ "entities": [{ "type": "Advertiser", ... }] }
-
Retrieves multiple placements. Can be filtered according to query parameters.
|
Name |
Description |
Type |
Required |
Notes |
|---|---|---|---|---|
|
from |
Starting index by which to fetch new placements for paging purposes. |
Long |
Required |
|
|
max |
Maximum number of placements to fetch for each page. |
Long |
Required |
|
|
accountId |
ID of account. |
Integer |
Optional |
|
|
advertiserId |
ID of advertiser. |
Integer |
Optional |
|
|
campaignID |
ID of campaign. |
Integer |
Optional |
|
|
excludePlacementType |
Excludes specific placement types from the response. |
String |
Optional |
|
|
isAttached |
Indicates whether the placement is attached. |
Boolean |
Optional |
|
|
levelToEnrich |
Integer |
Suggested value is 3 |
||
|
packageId |
ID of placement package. |
Integer |
Optional |
|
|
packageName |
Name of placement package. |
String |
Optional |
|
|
siteId |
ID of site. |
Integer |
Optional |
|
|
q |
Filtering options for the request (see here). |
String |
Optional |
Example of query string: {"1":{"ID":["1073932327"]},"2":{"NAME":["smith"]}} NoteNote: The date is according to the Unix epoch timestamp. |
|
Status |
Placement status. |
String |
Optional |
|
|
Type |
Type of placement. |
String |
Optional |
Retrieves a specific placement.
Retrieves all placement packages. Can be filtered.
Retrieves a specific media plan.
Creates a placement.
|
Name |
Description |
Type |
Required |
Notes |
|---|---|---|---|---|
|
Body |
Request containing placement to create |
JSON |
Required |
Create multiple placements.
|
Name |
Description |
Type |
Required |
Notes |
|---|---|---|---|---|
|
Body |
Request containing placement to create |
JSON |
Required |
Creates a new package.
|
Name |
Description |
Type |
Required |
Notes |
|---|---|---|---|---|
|
Body |
Request containing the package to create |
JSON |
Required |
Deletes one or more placements simultaneously.
|
NAME |
DESCRIPTION |
TYPE |
REQUIRED |
NOTES |
|---|---|---|---|---|
|
id |
One or more ids of placements to delete. |
Long |
Required |
Deletes a specific package.
|
NAME |
DESCRIPTION |
TYPE |
REQUIRED |
NOTES |
|---|---|---|---|---|
|
id |
ID of the package to delete. |
Long |
Required |
Updates an existing placement.
|
Name |
Description |
Type |
Required |
Notes |
|---|---|---|---|---|
|
id |
ID of the placement to update. |
Long |
Required |
|
|
Body |
Request body containing the placement to update. |
JSON |
Required |
Update an existing placements package.
|
Name |
Description |
Type |
Required |
Notes |
|---|---|---|---|---|
|
id |
ID of the package to be updated. |
Long |
Required |
|
|
Body |
Request body containing the package to update. |
JSON |
Required |
Publishes and generates a single placement tag.
Important
Important: Placement must be enabled and attached to enabled ads.
|
Name |
Description |
Type |
Required |
Notes |
|---|---|---|---|---|
|
type |
Type of entity. |
String |
Required |
tagRequest |
|
campaignId |
ID of the campaign to which the placements belong. |
Integer |
Required |
|
|
placementIds |
IDs of the placements for which tag generation is required. |
Array of integers |
Required |
|
|
includeKeywordInTags |
If selected, adds keywords (according to the site setup) to the code that is generated. |
Boolean |
Required |
|
|
supportMobileTokens |
Select the check box to include site-level mobile tokens in placement tags. |
Boolean |
Required |
|
|
includePublish |
If selected, generates and publishes the tag. If not selected, generates the tag without publishing. |
Boolean |
Required |
|
|
builderTagTypes |
Used to create different types of tags for different pages. |
String |
Required |
|
Name |
Description |
Type |
Notes |
|---|---|---|---|
|
type |
Type of entity. |
String |
APITagResponse |
|
Id |
Internal. |
Internal |
|
|
relationsBag |
Internal. |
Internal |
|
|
tag |
Placement tag code. |
String |
A separate tag is generated for each placement. |
|
placementID |
ID of the placement for which the tag was generated. |
Integer |
|
|
placementName |
Name of the placement for which the tag was generated. |
String |
|
|
accountID |
ID of the account to which the placement belongs. |
Integer |
|
|
accountName |
Name of the account to which the placement belongs. |
String |
|
|
campaignId |
ID of the campaign to which the placement belongs. |
Integer |
|
|
campaignName |
Name of the campaign to which the placement belongs. |
String |
|
|
siteId |
ID of the site to which the placement belongs. |
Integer |
|
|
siteName |
Name of the site to which the placement belongs. |
String |
|
|
siteSectionId |
Internal. |
Internal |
|
|
siteSectionName |
Internal. |
Internal |
|
|
placementType |
Type of placement. |
String |
|
|
bannerSize |
Height and width of banner size. |
||
|
bookedImpressions |
Units that were ordered to serve. |
Integer |
|
|
startDate |
Start date of placement. |
Long |
|
|
endDate |
End date of placement. |
Long |
|
|
advertiserId |
ID of the advertiser to which the placement belongs. |
Integer |
|
|
advertiserName |
Name of the advertiser to which the placement belongs. |
String |
|
|
brandId |
ID of the brand to which the placement belongs. |
Integer |
|
|
brandName |
Name of the brand to which the placement belongs. |
String |
The following shows an example of an internal server error in a response body.
The following tables list the possible internal server errors for the placement resource.
|
Code |
Description |
|---|---|
|
30000 |
Placement not found. |
|
30001 |
Failed to get all placements. |
|
30002 |
Failed to get placement - %s. |
|
30003 |
Placement ID is not valid. |
|
30004 |
Failed to get all placement packages. |
|
30005 |
Failed to get placement package - %s. |
|
30006 |
Placement package cannot be deleted since it is dummy or it is connected to one or more placements. |
|
Code |
Description |
|---|---|
|
31000 |
Placement has no campaign. Package's site or publisher ID is not valid. |
|
31001 |
Placement has not site. |
|
31002 |
Placement has no site section. |
|
31003 |
Placement's campaign is not valid. |
|
31004 |
Placement's site is not valid. |
|
31005 |
Placement's site section is not valid. |
|
31006 |
siteId in site object, %s, and siteId in site section, %s, do not match. |
|
31007 |
Campaign ID in campaign, %s, and campaign ID in placement, %s, do not match. |
|
31008 |
Campaign ID of placement package, %s, and campaign ID of placement, %s, do not match. |
|
31009 |
SiteOrPublisher ID of placement package, %s, and SiteOrPublisher ID of placement, %s, do not match. |
|
31010 |
Placement package, %s, is not valid. |
|
31011 |
Placement package, %s, is not placement level and cannot be changed. |
|
31012 |
Placement ServingEnabled property cannot be changed. |
|
31013 |
Placement Status property cannot be changed. |
|
31014 |
Cannot change the placement's campaign. |
|
31015 |
Cannot create placement package with placementLevel, %s, for placement %s. |
|
31016 |
Cannot get all banner sizes. |
|
31017 |
Banner size is too small. |
|
31018 |
Banner size is too large. |
|
31019 |
Account ID must not be empty. |
|
31020 |
Placement, %s, cannot be deleted since it has %s delivery groups attached. |
|
31021 |
Placement, %s, has status %s, but has servingEnabled flag %s. |
|
31022 |
Cannot update placement package with placementLevel = true for placement %s. |
|
31051 |
Package’s campaign is not valid. |
|
31052 |
Package’s SiteOrPublisher is not valid. Package’s campaign is not valid. |
|
31054 |
SiteOrPublisher of placement package cannot be changed. |
|
31055 |
Campaign of placement package cannot be changed. |
|
31100 |
MediaCost is null. |
|
31101 |
Rate cannot have a value when there is no cost model. |
|
31102 |
Ordered units cannot have a value when there is no cost model. |
|
31103 |
CustomInteraction cannot have a value when the cost model is not CPA. |
|
31104 |
ConversionId cannot have a value when the cost model is not CPA. |
|
31105 |
InteractionId cannot have a value when the cost model is not CPA. |
|
31106 |
ActionType cannot have a value when the cost model is not CPA. |
|
31107 |
Partner, %s, cannot be found. |
|
31108 |
Taxonomy ID, %s, must have Peer39 account set to true. |
|
31110 |
Placement tracking tag location or Taxonomy cannot be changed. |
|
31111 |
Default tracking ad ID for placement, %s, is null. |
|
31112 |
Default tracking ad cannot be changed. |
|
31113 |
Default tracking ad must be empty when saving a placement. |
|
31115 |
Please enter a number of units less than 100,000,000. |
|
31116 |
Tracking type for placement, %s, could not be changed. |
|
31117 |
Tracking type in placement must be Impressions or Impressions and Clicks. |
|
31119 |
The following URLs are invalid: %s |
|
31123 |
Serving complete method: %s is not valid when Unit value is empty. |
|
31124 |
Serving complete method : %s is not valid for %s cost model. |
|
31150 |
MediaServingData is null. |
|
31151 |
End date must be after start date. |
|
31152 |
Units cannot be negative. |
|
31153 |
MediaServingData has no ServingCompletedMethod. |
|
31155 |
Placement package cannot be changed when placement status is published. |
|
35003 |
Placement attached property cannot be changed. |
|
35132 |
Only an In-Banner placement can use RandomNumber as CustomToken. |
|
Code |
Description |
|---|---|
|
31154 |
Master ad: Field, %s, to replace was not found in the placement %s. |
|
Code |
Description |
|---|---|
|
35000 |
The tag is not available because an insertion order is pending. |
|
35001 |
Tag generation failed for placement %s. |
|
35002 |
The tag is not available because there is no default delivery group attached. |
|
35101 |
The tag cannot be shared because there are no site contacts. |
|
35113 |
The tag generation failed for placement, %s, because a placement cannot be attached to more than one delivery group from the same target audience. |
|
35124 |
The tag is not available because the placement is not enabled yet. Please try again later. |
|
35125 |
The tag is not available because there are no ads attached to the placement. |
|
35126 |
The tag is not available because there are no enabled placements ads. |
|
35127 |
The tag is not available because there is more than one default delivery group attached. |
|
Code |
Description |
|---|---|
|
35007 |
Could not create excel for site. |
|
35008 |
Could not create .txt file for one-click share. |
|
35011 |
Generating .zip file failed. |
|
Code |
Description |
|---|---|
|
35004 |
Published placement %s cannot be detached. |
|
35005 |
Failed to update background delivery group for placement %s. |
|
35006 |
Failed to delete background delivery group for placement %s. |
|
Code |
Description |
|---|---|
|
35102 |
Missing attached ads. |
|
35103 |
Placement could not be deleted. |
|
35104 |
Missing untargeted delivery group. |
|
35105 |
Missing site contacts on multiple placements. |
|
35106 |
Missing attached ads on multiple placements. |
|
35107 |
Missing untargeted delivery group on multiple placements. |
|
35108 |
Placement type cannot be changed. |
|
35109 |
Placement dimensions size cannot be changed. |
|
35110 |
Number of impression units must be greater than the number of served impressions. |
|
35111 |
Start date cannot be before 2015. |
|
35112 |
End date must be after today and within the next five years. |
|
35113 |
Placement’s campaign is not unique. |
|
35114 |
Placement site cannot be changed when placement is attached. |
|
35116 |
Target audience, %s, is assigned to placement, %s, but it does not exist. |
|
35117 |
Placement, %s, is assigned to target audiences, but it is not of type In-Banner or In-Stream. |
|
35118 |
Target audience, %s, is not of type Publisher Targeting. |
|
35119 |
Update placement status from %s to %s is not allowed. |
|
35120 |
Tracking type in placement must be Clicks or Impressions and Clicks. |
|
35122 |
Placement package units must be between 0-99999999. |
|
35123 |
Placement package start date must be before end date. |
|
35133 |
CPA is the selected cost model. Please define a conversion activity. |
|
35134 |
The selected cost model cannot be used with conversion activities. To use a conversion activity, please select CPA as the cost model. |
|
35135 |
The selection conversion is not under the same advertiser as the placement package. |
|
Code |
Description |
|---|---|
|
35128 |
Published Placement, %s, does not have a default delivery group attached. |
|
35129 |
Published Placement, %s, has more than one default delivery group attached. |
|
35130 |
Published Placement, %s, does not have enabled placement ads. |
|
35131 |
Published Placement, %s, cannot be attached to more than one delivery group from the same target audience. |
|
35133 |
User does not have permission and/or required role type from Customer Success Manager to set Peer39 PCPM. |
Comments