Ad Group - Media Plan

AI Tools

The various methods for Product Content are listed below:

Create auto media plan

Creates an auto media plan for a retail campaign. Validates allowed dimensions against the retailer's whitelist. Requires Campaigns_List permission.
Path Parameters

Name	Data Type	Requirement	Parameter Type	Description
accountId	string	Mandatory	path	ID of the account.

Parameters

Field	Data Type	Requirement	Description
dimensions	array of string	Mandatory	List of ad dimensions to include (e.g. `["300x250", "728x90"]`).
retailCampaignId	integer	Mandatory	ID of the retail campaign to associate with this media plan.
mediaChannelIdx	integer	Mandatory	Index of the media channel to use.

Sample Request

POST http://demo.stub.api.jivox.com/v2/accounts/:accountId/media-plans/auto

Request Body

{ "dimensions": ["300x250", "728x90"], "retailCampaignId": 5373, "mediaChannelIdx": 101 }

Response

Returns a MediaPlanEditResponse JSON object.

Field	Data Type	Description
mediaPlanId	integer	ID of the newly created media plan.
msg	string	Success message.

Request Body

{ "mediaPlanId": 65807, "msg": "Media plan created successfully" }

Name	Data Type	Requirement	Parameter Type	Description
fields	string	Optional	query	Comma-separated list of fields to include in the response.
offset	integer	Optional	query	Pagination offset
limit	integer	Optional	query	Number of items per page.

Field	Data Type	Description
mediaPlanId	integer/null	ID of the media plan.
mediaPlanName	string/null	Name of the media plan.
adServers	array	List of ad server objects associated with this media plan.
adServers[].adServerName	string/null	Name of the ad server.
adServers[].adServerParams	object	Ad server parameters.
adServers[].placements	array	List of placement objects under this ad server.

{ "mediaPlanId": 65807, "mediaPlanName": "Summer Promo Media Plan", "adServers": [ { "adServerName": "Walmart DSP", "adServerParams": {}, "placements": [ { "placementId": "pl-001", "placementName": "300x250 Banner" } ] } ] }

Fetch ad group details

Returns all ad groups associated with a retail campaign, as a list of ID–name pairs. Requires MediaPlan_Tags_Create permission.

Path Parameters

Name	Data Type	Requirement	Parameter Type	Description
accountId	string	Mandatory	path	ID of the account.
retailCampaignIdx	integer	Mandatory	path	Index of the retail campaign to fetch ad groups for.

Sample Request

GET http://demo.stub.api.jivox.com/v2/accounts/:accountId/retail-campaigns/:retailCampaignIdx/ad-groups

Response

Returns an AdGroupDetails JSON object containing a list of AdGroupInfo items.

Field	Data Type	Description
adGroupDetails	array	List of ad group objects.
adGroupDetails[].adGroupId	string	ID of the ad group.
adGroupDetails[].adGroupName	string	Name of the ad group.

Request Body

{ "adGroupDetails": [ { "adGroupId": "ag-001", "adGroupName": "Ad Group A" }, { "adGroupId": "ag-002", "adGroupName": "Ad Group B" } ] }

Get Product Content (content map)

Returns the product content (content map) for a retail campaign and media plan. The response varies based on whether content is mapped by placement (placementContentMap) or by ad group (adGroupPlacementCreativeMap). Requires MediaPlan_List permission.

Parameters

Name	Data Type	Requirement	Parameter Type	Description
accountId	string	Mandatory	path	ID of the account.
retailCampaignId	integer	Mandatory	path	Index of the retail campaign.
mediaPlanId	integer	Mandatory	path	ID of the media plan.

Query Parameters

Name	Data Type	Requirement	Parameter Type	Description
offset	integer	Optional	query	Pagination offset
limit	integer	Optional	query	Number of items per page.

Sample Request

GET http://demo.stub.api.jivox.com/v2/accounts/:accountId/retail-campaigns/:retailCampaignId/media-plans/:mediaPlanId/content-map

Response

Returns an RMAProductContent JSON object. Either placementContentMap or adGroupPlacementCreativeMap is populated depending on the campaign type.

Field	Data Type	Description
contentType	string/null	Content type (e.g. `Product`, `Creatives`).
numOfCards	integer/null	Number of cards in the creative.
placementContentMap	array/null	List of placement-level content mappings (used for non-ad-group campaigns).
placementContentMap[].placementId	string/null	ID of the placement.
placementContentMap[].externalPlacementId	string/null	External placement ID.
placementContentMap[].placementName	string/null	Name of the placement.
placementContentMap[].dimension	string/null	Ad dimension (e.g. `300x250`).
placementContentMap[].content	array	List of content preview items
placementContentMap[].content[].contentValue	string/null	Raw content value (e.g. SKU or creative name).
placementContentMap[].content[].displayValue	string/null	Display label for the content
placementContentMap[].content[].productImageUrl	string/null	Product image URL (present when `contentPreviews` is available).
placementContentMap[].content[].previewUrls	array/null	Per-ad-unit preview URLs.
placementContentMap[].content[].previewUrls[].adUnitId	integer	ID of the ad unit.
placementContentMap[].content[].previewUrls[].url	string/null	Preview URL for the ad unit.
adGroupPlacementCreativeMap	array/null	List of ad-group-level content mappings (used for ad-group-based campaigns).
adGroupPlacementCreativeMap[].adGroupId	string/null	ID of the ad group.
adGroupPlacementCreativeMap[].adGroupName	array of string	Name(s) of the ad group.
adGroupPlacementCreativeMap[].status	array	Status value(s) for the ad group.
adGroupPlacementCreativeMap[].placementCreativeMap	array	List of placement-level creative mappings within the ad group
adGroupPlacementCreativeMap[].placementCreativeMap[].placementId	string/null	ID of the placement
adGroupPlacementCreativeMap[].placementCreativeMap[].externalPlacementId	string/null	External placement ID.
adGroupPlacementCreativeMap[].placementCreativeMap[].placementName	string/null	Name of the placement.
adGroupPlacementCreativeMap[].placementCreativeMap[].dimension	string/null	Ad dimension.
adGroupPlacementCreativeMap[].placementCreativeMap[].content	array	List of content preview items (same structure as `placementContentMap[].content`).
next	string/null	URL for the next page of results.
previous	string/null	URL for the previous page of results.

Sample Response

{ "contentType": "Creatives", "numOfCards": 2, "placementContentMap": null, "adGroupPlacementCreativeMap": [ { "adGroupId": "ag-001", "adGroupName": ["Ad Group A"], "status": ["Active"], "placementCreativeMap": [ { "placementId": "pl-001", "externalPlacementId": null, "placementName": "300x250 Banner", "dimension": "300x250", "content": [ { "contentValue": "Creative-001", "displayValue": "Creative A", "productImageUrl": null, "previewUrls": null } ] } ] } ], "next": null, "previous": null }

Update Product Content (content map)

Saves/updates the product content mapping for a retail campaign and media plan. Accepts ad-group-level content mapping. Requires MediaPlan_Edit permission.

Path Parameters

Name	Data Type	Requirement	Parameter Type	Description
accountId	string	Mandatory	path	ID of the account.
retailCampaignId	integer	Mandatory	path	Index of the retail campaign.
mediaPlanId	integer	Mandatory	path	ID of the media plan.

Sample Request

POST http://demo.stub.api.jivox.com/v2/accounts/:accountId/retail-campaigns/:retailCampaignId/media-plans/:mediaPlanId/content-map

Response

Field Data	Type	Requirement	Description
contentType	enum (string)	Mandatory	Content type. Values: `Product`, `Sub-category`, `Category`, `Creatives`, `All`, `Brand`.
dataServiceId	integer	Optional	ID of the data service (asset source).
adGroupPlacementCreativeMap	array	Mandatory	Ad-group-level content mapping.
adGroupPlacementCreativeMap[].adGroupId	string	Mandatory	ID of the ad group
adGroupPlacementCreativeMap[].adGroupName	string	Optional	Name of the ad group.
adGroupPlacementCreativeMap[].status	string	Optional	Status of the ad group.
adGroupPlacementCreativeMap[].placementCreativeMap	array	Mandatory	List of placement-level mappings within the ad group
adGroupPlacementCreativeMap[].placementCreativeMap[].placementId	string	Mandatory	ID of the placement
adGroupPlacementCreativeMap[].placementCreativeMap[].externalPlacementId	string	Optional	External placement ID.
adGroupPlacementCreativeMap[].placementCreativeMap[].placementName	string	Optional	Name of the placement.
adGroupPlacementCreativeMap[].placementCreativeMap[].dimension	string	Optional	Ad dimension (e.g. `300x250`).
adGroupPlacementCreativeMap[].placementCreativeMap[].siteId	string	Optional	Site ID associated with the placement
adGroupPlacementCreativeMap[].placementCreativeMap[].content	array of string	Mandatory	List of content values (SKUs or creative names). Must be empty when `contentType` is `All`.

Info

Note: contentType: All is only valid for the Meta ad server and non-SBT campaigns. Content list must be empty when using All

Sample Response

{ "contentType": "Creatives", "dataServiceId": 12345, "adGroupPlacementCreativeMap": [ { "adGroupId": "ag-001", "adGroupName": "Ad Group A", "status": "Active", "placementCreativeMap": [ { "placementId": "pl-001", "placementName": "300x250 Banner", "dimension": "300x250", "content": ["Creative-001", "Creative-002"] } ] } ] }

Response

Field	Data Type	Description
message	string	Save confirmation message.

Response

{ "message": "Product content saved successfully" }

List Product/Category/Subcategory from Asset Source

This will list all the Product/Category/SubCategory from the Asset Source.

Parameters

Name	Data Type	Requirement	Parameter Type	Description
accountId	string	Mandatory	path	ID of the advertiser account created on the platform.

Sample Request

GET http://demo.stub.api.jivox.com/v2/accounts/:accountId/retail-feed-settings/list?fields=product&query=searchQuery&limit=10&offset=0

Info

The Parameter:

accountId - is the Current account Id

field: product/category/sub-category field

query: the search query input by the user

limit: the limit of elements in the list

offset: the no. of elements to skip

Sample Response

{ values: ["Dove Soap", "Dove Conditioner", "Dove Shampoo"] }

Last updated on

Was this page helpful?

Ad Group - Media Plan

Create auto media plan

Get media plan by ID

Fetch ad group details

Get Product Content (content map)

Update Product Content (content map)

List Product/Category/Subcategory from Asset Source