Create | Update Standard Placement

Creates or updates Standard Placement based on whether the ID was provided.

URL: /rest-api/placements/update/standard.do

Method: POST

Response format: application/json

Error codes:

  • 401 Unauthorized – authentication error.

Response sample: 200 OK

AdUnit sizes:

AdUnit Size (Width x Height)
MEDIUM_RECTANGLE 300×250
RECTANGLE 180×50
LEADERBOARD 728×90
FULL_BANNER 468×60
SKYSCRAPER 120×600
WIDE_SKYSCRAPER 160×600
HALF_PAGE_AD 300×600
BUTTON_2 120×60
MICRO_BAR 88×31
XXL_BOX 468×648
CUSTOM Specified by user

Parameters:

  • hash – an MD5 digest of a concatenated username's MD5 password and a given timestamp.
  • timestamp – UNIX timestamp in milliseconds used for hash generation.
  • username – a given username.
  • id – identifier of the Placement that will be updated (optional, if no value is provided, new Placement will be created).
  • zoneId – Identifier of Zone where the Placement should be created (mandatory for new Placements).
  • type – type of Placement, supported value: SITE_PLACEMENT: 1; STANDARD_SITE_PLACEMENTS; STANDARD_SITE_BANNERS.
  • name – Placement Name (mandatory for new Placements).
  • description – short description of the Placement (optional).
  • adUnitId – available values: /rest-api/banner/adunit/values.do?placementType=SITE_PLACEMENT
  • size.Height – height of the Placement area; required when using CUSTOM adUnit.
  • size.Width – width of the Placement area; required when using CUSTOM adUnit.
  • labelsNames - names of Labels (optional).
  • allowVariableBannerSizes – Boolean (optional, default value is "false").
  • defaultCode – code to run when no ad is available as a String (optional).
  • rotateInterval – long between 0 and 1000, seconds between ad change, works only for iframe Invocation Code (optional).

Create | Update Non Standard Placement

Creates or updates Non-standard Placement info based on whether the ID was provided.

URL: /rest-api/placements/update/non-standard.do

Method: POST

Response format: application/json

Error codes:

  • 401 Unauthorized – authentication error.

Response sample:
200 OK

Parameters:

  • hash – an MD5 digest of a concatenated username's MD5 password and a given timestamp.
  • timestamp – UNIX timestamp in milliseconds used for hash generation.
  • username – a given username.
  • id – identifier of the Placement that will be updated (optional, if no value is provided, new Placement will be created).
  • zoneId – identifier of Zone where the Placement should be created (mandatory for new Placements).
  • name – Placement Name (mandatory for new Placements);
  • type – type of Placement, supported value: NON_STANDARD_SITE_PLACEMENT: 4; NONSTANDARD_SITE_PLACEMENTS; NONSTANDARD_SITE_BANNERS.
  • labelsNames - names of Labels (optional).
  • description – short description of the Placement (optional).

Create | Update Mobile Placement

Creates or updates Mobile Placement info based on whether the ID was provided.

URL: /rest-api/placements/update/mobile.do

Method: POST

Response format: application/json

Error codes:

  • 401 Unauthorized – authentication error.

Response sample:
200 OK

Parameters:

  • hash – an MD5 digest of a concatenated username's MD5 password and the a given timestamp.
  • timestamp – UNIX timestamp in milliseconds used for hash generation.
  • username – a given username.
  • id – identifier of the Placement that will be updated (optional, if no value is provided, new Placement will be created).
  • zoneId – Identifier of Zone where the Placement should be created (mandatory for new Placements).
  • name – Placement Name (mandatory for new Placements).
  • type – type of Placement, supported value: MOBILE_SITE_PLACEMENT: 2; MOBILE_SITE_PLACEMENTS; MOBILE_SITE_BANNERS.
  • labelsNames - names of Labels (optional).
  • description – short description of the Placement (optional).
  • defaultCode – code to run when no ad is available, as a String (optional).

Create | Update Video Placement

Creates or updates Video Placement info based on whether or not ID was provided.

URL: /rest-api/placements/update/video.do

Method: POST

Response format: application/json

Error codes:

  • 401 Unauthorized – authentication error.

Response sample:
200 OK

{"success":true, id: <placementId>} – success, returns id of affected placement record
{"success":false} – error

Parameters:

  • hash – a MD5 digest of concatenated username's MD5 password and the given timestamp.
  • timestamp – UNIX timestamp in milliseconds used in hash generation.
  • username – the given username.
  • id – identifier of the Placement that will be updated (optional, if no value is provided, new Placement will be created).
  • zoneId – Identifier of Zone where the Placement should be created (mandatory for new Placements).
  • type – type of Placement, supported value VIDEO_PLACEMENT: 3; VIDEO_PLACEMENTS; VIDEO_BANNERS.
  • name – Placement Name (mandatory for new Placements).
  • description – short description of the Placement (optional).
  • labelsNames - names of Labels (optional).
  • videoFormats – video ad format of the Placement, available values: PRE_ROLL, MID_ROLL, POST_ROLL, OVERLAY (optional, comma separated, default none).
  • skipButtonEnabled – show Skip Ad button (optional, default value is "false").
  • skipButtonMinimumAdDuration – minimum ad duration before show Skip Ad button – integer (optional, default value is "10").
  • skipButtonShowAfterSeconds – show Skip Ad button after given time in seconds - integer (optional, default value is "5").
  • skipButtonShowForSeconds – show Skip Ad button for a given time in seconds – integer (optional, default value is "5").

Create | Update Application Placement

Creates or updates Application Placement info based on whether ID was provided.

URL: /rest-api/placements/update/app.do

Method: POST

Response format: application/json

Error codes:

  • 401 Unauthorized – authentication error.

Response sample:
200 OK

{"success":true, id: <placementId>} – success, returns ID of affected Placement record
{"success":false} – error

Parameters:

  • hash – a MD5 digest of concatenated username's MD5 password and the given timestamp.
  • timestamp – UNIX timestamp in milliseconds used in hash generation.
  • username – the given username.
  • id – identifier of the Placement that will be updated (optional, if no value is provided, new Placement will be created).
  • zoneId – Identifier of Zone where the Placement should be created (mandatory for new Placements).
  • type – type of Placement, supported value APPLICATION_PLACEMENT: 5; APPLICATION_PLACEMENTS; APPLICATION_BANNERS.
  • adCategory – available values: BANNER, INTERSTITIAL (optional, default value is BANNER).
  • operatingSystem – IOS or ANDROID (optional, default value is IOS).
  • name – Placement Name (mandatory for new Placements).
  • labelsNames - names of Labels (optional).
  • description – short description of the Placement (optional).

Create | Update Click-through Placement

Creates or updates Click-through Placement based on whether ID was provided.

URL: /rest-api/placements/update/click_through.do

Method: POST

Response format: application/json

Error codes:

  • 401 Unauthorized – authentication error.

Response sample:
200 OK

{"success":true, id: <placementId>} – success, returns id of affected placement record
{"success":false} – error

Parameters:

  • hash – a MD5 digest of concatenated username's MD5 password and the given timestamp.
  • timestamp – UNIX timestamp in milliseconds used in hash generation.
  • username – the given username.
  • id – identifier of the Placement that will be updated (optional, if no value is provided, new Placement will be created).
  • zoneId – Identifier of Zone where the Placement should be created (mandatory for new Placements).
  • type – type of Placement, supported value: CLICK_THROUGH_PLACEMENT: 7; CLICK_THROUGH_PLACEMENTS; CLICK_THROUGH_BANNERS.
  • name – Placement Name (mandatory for new Placements).
  • labelsNames - names of Labels (optional).
  • description – short description of the Placement (optional).

Create | Update Native Placement

Creates or updates native placement info based on whether or not id was provided.

URL: /rest-api/placements/update/native.do

Method: POST

Response format: application/json

Error codes:

  • 401 Unauthorized – authentication error.

Response sample:
200 OK

{"success":true, id:} - success, returns id of affected placement record
{"success":false} - error

Parameters:

  • hash - a MD5 digest of concatenated username's md5 password and the given timestamp.
  • timestamp - UNIX timestamp used in hash generation.
  • username - the given username.
  • id - Identifier of placement to update (optional, if no value provided new placement will be created).
  • zoneId - Identifier of zone where put placement to (mandatory).
  • type - type of placement.
  • name - placement name (mandatory).
  • labelsNames - names of labels.
  • description - short characteristic of placement (optional).
  • nativePreferences.iconSize.width - width value for icon creative, optional, 128 by default.
  • nativePreferences.iconSize.height - height value for icon creative, optional, 128 by default.
  • nativePreferences.imageSize.width - width value for image creative, optional, 1200 by default.
  • nativePreferences.imageSixe.height - height value for image creative, optional, 627 by default.
  • nativePreferences.videoSize.width - width value for video creative, optional, 640 by default.
  • nativePreferences.videoSize.height - height value for video creative, optional, 480 by default.

Delete Placement

Deletes Placement with a given ID.

URL: /rest-api/placements/{placementId}/delete.do

Method: POST

Response format: application/json

Error codes:

  • 401 Unauthorized – authentication error.

Response sample:
200 OK

Parameters:

  • hash – an MD5 digest of a concatenated username's MD5 password and a given timestamp.
  • timestamp – UNIX timestamp in milliseconds used for hash generation.
  • username – a given username.

Get Placement Summary

Get the Placement ID, Category, Size and Key.

URL: /rest-api/placements/summary.do

Method: GET

Response format: application/json

Error codes:

  • 401 Unauthorized – authentication error.

Response sample:
200 OK

Parameters:

  • hash – an MD5 digest of a concatenated username's MD5 password and a given timestamp.
  • timestamp – UNIX timestamp in milliseconds used for hash generation.
  • username – a given username.
  • publishingCategories – IDs of publishing categories to filter the results (optional).
  • placementIds – IDs of placements to filter the results (optional).

Get Placement Invocation Code

Get the Invocation Code for the given Placement.

URL: /rest-api/placement/{key}/code.do

Method: GET

Response format: application/json

Error codes:

  • 401 Unauthorized – authentication error.

Response sample:
200 OK
{code: "http://ads.epom.com/ads?key=4dc64890a029cce994d01ca04ed6a5e4&ch=&width=160&height=600", success: true}

Parameters:

  • hash – an MD5 digest of a concatenated username's MD5 password and a given timestamp.
  • timestamp – UNIX timestamp in milliseconds used for hash generation.
  • username – a given username.
  • key – Placement Key.
  • t – Invocation Code type. Available values: IFRAME_SYNC, IFRAME_ASYNC, IFRAME_SIMPLE, JS_SYNC, JS_ASYNC, JW_PLAYER, FLOW_PLAYER, PHP, DIRECT_URL, EMAIL, JW_PLAYER_OVERLAY, API_JS_SYNC_CODE.

Get Matching Banners

Get all the Banners that match the Placement by its ID.

URL: /rest-api/placements/{placementId}/matchedAds.do

Method: GET

Response format: application/json

Error codes:

  • 401 Unauthorized – authentication error.

Response sample:
200 OK

Parameters:

  • hash – an MD5 digest of a concatenated username's MD5 password and a given timestamp.
  • timestamp – UNIX timestamp in milliseconds used for hash generation.
  • username – a given username.
  • placementId – the given Placement ID.

Get linked Banners

Get all the Banners linked to the Placement by its ID.

URL: /rest-api/banner/placement/{placementId}/banners.do

Method: GET

Response format: application/json

Error codes:

  • 401 Unauthorized – authentication error.
  • 403 Forbidden – not enough permissions.
  • 404 Not Found – no Placement with such ID.

Response sample:
200 OK

{id: 1, name: "bannerName1"}

Parameters:

  • hash – an MD5 digest of a concatenated username's MD5 password and a given timestamp.
  • timestamp – UNIX timestamp in milliseconds used for hash generation.
  • username – a given username.
  • placementId – the given Placement ID.

Add Labels without Overriding

Adds new Labels to the Placement without overriding the existing ones.

URL: /rest-api/placements/labels/add.do

Method: POST

Response format: application/json

Error codes:

  • 401 Unauthorized – authentication error.

Response sample:
200 OK
{"success":true, "placementId":<placementId>, "labels":[<label>,<label>,...]} - success, returns ID of the Placement record and its Labels.

Parameters:

  • hash – an MD5 digest of a concatenated username's MD5 password and a given timestamp.
  • timestamp – UNIX timestamp in milliseconds used for hash generation.
  • username – a given username.
  • placementId – ID of Placement to add Labels.
  • labels – names of new Labels to add to the Placement.

Copy Placement

Copies the Placement to the specified Zone.

URL: /rest-api/placements/copy-placement.do

Method: POST

Response format: application/json

Error codes:

  • 401 Unauthorized - authentication error
  • 400 Bad Request - palacement or zone not found or deleted

Response sample:

200 OK
{"success":"true", "newItemIds":["1", ...]}

Parameters:

  • placementId - placement prototype id, should exist and be not deleted
  • zoneId - zone id, should exist and be not deleted
  • keepBannersLinked - determine whether to keep banners linked to new placement, default=true
  • count - copies count, default=1
  • hash - a MD5 digest of concatenated username's md5 password and the given timestamp
  • timestamp - UNIX timestamp used in hash generation
  • username - the given username

Need more help?

Should you require any additional help with our solutions, do not hesitate to contact Epom technical support at support@epom.com. Our support managers are dedicated to resolving any issues and providing you with solutions and support if you face difficulties or have questions.