PRODUCT
Follow

Overview

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.

Resource URL

Depending on the API user that was created for you, use one of the following URLs:

  • https://api.sizmek.com/rest/placements

  • https://adapi.sizmek.com/sas/placements

Note

Note: Confirm with your Sizmek customer success manager regarding the correct URL to use.

HTTP Method and URI List

HTTP Method

URI

Description

GET

/placements/

Retrieves multiple placements.

GET

/placements/{id}

Retrieves a specific placement.

GET

/placements/packages

Retrieves multiple packages.

GET

/placements/packages/{id}

Retrieves a specific package.

GET

/placements/externalMediaPlan/{id}

Retrieves an external media plan for the following placement types:

  • In-Stream Video Verification Tracking

  • Verification Tracking

POST

/placements

Creates a placement.

POST

/placements/packages

Creates a package.

POST

/placements/delete

Deletes a placement.

DELETE

/placements/packages/{id}

Deletes a specific package.

PUT

/placements/{id}

Updates a specific placement.

PUT

/placements/packages/{id}

Updates a specific package.

PUT

/placements/externalMediaPlan/{id}

Updates an external media plan for the following placement types:

  • In-Stream Video Verification Tracking

  • Verification Tracking

Method Examples and Request Parameters

Important

Important:

  • For PUT calls, do the following:

    • We recommend that for any PUT method that updates an object, 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.

    • 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", ... }] }   

Get Multiple Placements

Retrieves multiple placements. Can be filtered according to query parameters.

Request 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

accountName

Name of account.

String

Optional

advertiserId

ID of advertiser.

Integer

Optional

advertiserName

Name of advertiser.

String

Optional

brandId

ID of parent brand.

String

Optional

brandName

Name of parent brand.

String

Optional

campaignID

ID of campaign.

Integer

Optional

campaignName

Name of campaign.

String

Optional

height

Height of placement.

Integer

Optional

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"]}}

Note

Note: The date is according to the Unix epoch timestamp.

siteName

Name of placement site.

String

Optional

Status

Placement status.

String

Optional

Type

Type of placement.

String

Optional

Width

Width of placement.

Integer

Optional

Request Format

Depending on the API user that was created for you, use one of the following URLs:

  • GET https://api.sizmek.com/rest/placements?from=0&max=250

  • GET https://adapi.sizmek.com/sas/placements?from=0&max=250

Response Format

Get a Specific Placement

Retrieves a specific placement.

Request Parameters

Name

Description

Type

Required

Notes

id

ID of placement to fetch

Long

Required

Request Format

Depending on the API user that was created for you, use one of the following URLs:

  • GET https://api.sizmek.com/rest/placements/1074212202

  • GET https://adapi.sizmek.com/sas/placements/1074212202

Response Format

Get Multiple Placement Packages

Retrieves all placement packages. Can be filtered.

Request Format

Depending on the API user that was created for you, use one of the following URLs:

  • GET https://api.sizmek.com/rest/placements/packages?from=0&max=250

  • GET https://adapi.sizmek.com/sas/placements/packages?from=0&max=250

Response Format

A successful request returns the HTTP 200 OK status code and a JSON response body that shows the specified number of placement packages.

Get a Specific Placement Package

Retrieves a specific media plan.

Request Parameters

Name

Description

Type

Required

Notes

id

ID of placement to fetch

Long

Required

Request Format

Depending on the API user that was created for you, use one of the following URLs:

  • GET https://api.sizmek.com/rest/placements/packages/1074212202

  • GET https://adapi.sizmek.com/sas/placements/packages/1074212202

Response Format

A successful request returns the HTTP 200 OK status code and a JSON response body that shows the requested placement package.

Get an External Media Plan

Retrieves an external media plan for the following placement types:

  • In-Stream Video Verification Tracking

  • Verification Trafficking

Request Parameters

Name

Description

Type

Required

Notes

id

ID of placement to fetch

Long

Required

Request Format

Depending on the API user that was created for you, use one of the following URLs:

  • GET https://api.sizmek.com/rest/placements/1074212202

  • GET https://adapi.sizmek.com/sas/placements/1074212202

Response Format

A successful request returns the HTTP 200 OK status code and a JSON response body that shows the requested external media plan.

Create a Placement

Creates a placement.

Request Parameters

Name

Description

Type

Required

Notes

Body

Request containing placement to create

JSON

Required

Request Format

Depending on the API user that was created for you, use one of the following URLs:

  • POST https://api.sizmek.com/rest/placements

  • POST https://adapi.sizmek.com/sas/placements

Response Format

A successful request returns the HTTP 200 OK status code and a JSON response body that shows the new placement.

Create a Package

Creates a new package.

Request Parameters

Name

Description

Type

Required

Notes

Body

Request containing the package to create

JSON

Required

Request Format

Depending on the API user that was created for you, use one of the following URLs:

  • POST https://api.sizmek.com/rest/placements/packages

  • POST https://adapi.sizmek.com/sas/placements/packages

Response Format

A successful request returns the HTTP 200 OK status code and a JSON response body that shows the new package.

Delete a Placement

Deletes one or more placements simultaneously.

Request Parameters

NAME

DESCRIPTION

TYPE

REQUIRED

NOTES

id

One or more ids of placements to delete.

Long

Required

Request Format

Depending on the API user that was created for you, use one of the following URLs:

  • POST https://api.sizmek.com/rest/placements/delete

  • POST https://adapi.sizmek.com/sas/placements/delete

Response Format

A successful request returns the HTTP 200 OK status code; the requested placements are deleted.

Delete a Specific Package

Deletes a specific package.

Request Parameters

NAME

DESCRIPTION

TYPE

REQUIRED

NOTES

id

ID of the package to delete.

Long

Required

Request Format

Depending on the API user that was created for you, use one of the following URLs:

  • DELETE https://api.sizmek.com/rest/placements/packages/1073748333

  • DELETE https://adapi.sizmek.com/sas/placements/packages/1073748333

Response Format

A successful request returns the HTTP 200 OK status code; the requested placements are deleted.

Update a Placement

Updates an existing placement.

Request Parameters

Name

Description

Type

Required

Notes

id

ID of the placement to update.

Long

Required

Body

Request body containing the placement to update.

JSON

Required

Request Format

Depending on the API user that was created for you, use one of the following URLs:

  • PUT https://api.sizmek.com/rest/placements/1074212200

  • PUT https://adapi.sizmek.com/sas/placements/1074212200

Response Format

A successful request returns the HTTP 200 OK status code; the placement is updated accordingly.

Update a Package

Update an existing placements package.

Request Parameters

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

Request Format

Depending on the API user that was created for you, use one of the following URLs:

  • PUT https://api.sizmek.com/rest/placements/packages/1234

  • PUT https://adapi.sizmek.com/sas/placements/packages/1234

Response Format

A successful request returns the HTTP 200 OK status code; the placement package is updated accordingly.

Update an External Media Plan

Updates an existing external media plan for the following placement types:

  • In-Stream Video Verification Tracking

  • Verification Trafficking

Request Parameters

Name

Description

Type

Required

Notes

id

ID of the external media plan to be updated.

Long

Required

Body

Request body containing the external media plan to update.

JSON

Required

Request Format

Depending on the API user that was created for you, use one of the following URLs:

  • PUT https://api.sizmek.com/rest/placements/1083976450

  • PUT https://adapi.sizmek.com/sas/placements/1083976450

Response Format

A successful request returns the HTTP 200 OK status code; the external media plan is updated accordingly.

Generate Tag

Publishes and generates a single placement tag.

Important

Important: Placement must be enabled and attached to enabled ads.

Request Parameters

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

Request Format

Depending on the API user that was created for you, use one of the following URLs:

  • POST https://api.sizmek.com/rest/placements/generateTag

  • POST https://adapi.sizmek.com/sas/placements/generateTag

Response Format

If request is successful, response will be 200 OK with the created tag structure.

Response Parameters

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.

bannerSize Object

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

Status Codes and Errors

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.

General Errors

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.

Validation Errors

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.

31114

MediaCost must be empty in a Verification tracking 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.

31118

The combination of Taxonomy, %s, and tracking tag location, %s, is invalid for a Verification placement.

31119

The following URLs are invalid: %s

31120

In-Stream Video Verification Tracking is not configured for this campaign; this tracking requires Advanced data collection. You can configure Verification data collection in campaign settings.

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.

Search and Replace Errors

Code

Description

31154

Master ad: Field, %s, to replace was not found in the placement %s.

Generate Tag/Generate Tag File/Share Tag Errors

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.

35050

Tag generation failed for placement %s - Missing tracking tag location for verification placement.

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.

Generating Excel Errors

Code

Description

35007

Could not create excel for site.

35008

Could not create .txt file for one-click share.

35011

Generating .zip file failed.

Detachment Errors

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.

External Media Plan Errors

Code

Description

35012

External media plan validation error: Campaign is null

35013

External media plan validation error: Campaign data is null.

35016

External media plan validation error: %s ID, %s, already exists.

35017

External media plan validation error: Duplicate row, %s, %s, %s, %s.

35018

Placement ID mismatch. Trying to save media plan for placement ID %s, but the request contains placement ID %s.

35019

External media plan can be saved only for placement type Verification tracking.

35100

Disable Cookies cannot be false for placement while site/campaign Disable Cookies is true.

Share Tag Validation Errors

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.

35121

Tracking/verification placement, %s, cannot have a deactivated status.

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.

Published Placements General Error for Validations

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 Sizmek customer success manager to set Peer39 PCPM.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk