Retrieve list of all campaigns
This endpoint retrieves a list of campaigns based on specified filters and parameters such as campaign name, campaign type, placement ID, team ID, approval state, and more. A date range (from and to)
description: "This endpoint retrieves a list of campaigns based on specified filters and parameters such as campaign name, campaign type, placement ID, team ID, approval state, and more. A date range (from and to) can be provided to narrow results based on the update time of the campaign. Pagination and sorting are supported to manage large datasets efficiently."
Retrieve list of all campaigns
This endpoint retrieves a list of campaigns based on specified filters and parameters such as campaign name, campaign type, placement ID, team ID, approval state, and more. A date range (from and to) can be provided to narrow results based on the updateTime of the campaign. Pagination and sorting are supported to manage large datasets efficiently.
Authorizations
AuthorizationstringRequired
For accessing the API a valid JWT jwt must be passed in all queries in the 'Authorization' header. The following syntax must be used in the 'Authorization' header. (Bearer xxx.yyy.zzz)
Body
Responses
200
List of campaigns with pagination token for retrieving additional results.
application/json
nextPageTokenstringOptional
The page token used to request the next page in pagination. Include it as pageToken in the request.
totalCountstring · int64Optional
Displays the total number of campaigns that meet the specified criteria.
400
There was a problem with input.
application/json
401
Login failed or token not valid.
application/json
403
Access denied due to insufficient permissions.
application/json
default
An unexpected error response.
application/json
post/v3/campaigns
POST /v3/campaigns HTTP/1.1
Host: campaign.<env>.citrusad.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 744
{
"filters": {
"approvalState": "APPROVAL_STATE_PENDING,APPROVAL_STATE_APPROVED",
"campaignState": "CAMPAIGN_STATE_ACTIVE,CAMPAIGN_STATE_PAUSED",
"campaignType": "Banner",
"catalogIds": "catalog_001",
"fromDate": "2024-09-01T12:00:00Z",
"ids": "campaign_123456789, campaign_6454456789",
"managedOnly": false,
"name": "text",
"pageSize": 20,
"pageToken": "CgQImOTlaSgIIFA==",
"placementId": "1ceee624-7c87-4e98-9995-042da2a32525, 5geee624-7c87-4e98-9995-042da2a32522",
"requestTeamId": "Team-101",
"servingState": "SERVING_STATE_SCHEDULED",
"sortOptions": {
"key": "SORT_OPTION_KEY_UPDATE_TIME",
"lastValue": "text",
"order": "SORT_OPTION_ORDER_ASC"
},
"teamId": "66eee624-7c87-4e98-9995-042da2a32525",
"toDate": "2024-09-30T23:59:59Z",
"walletId": "wallet_123456789, wallet_6454456789"
}
}{
"campaigns": [
{
"advertisedProducts": {
"productGroupList": [
"text"
],
"productsByAttributes": {
"priceRange": {
"max": "100",
"min": "10"
},
"tags": [
"tag1",
"tag2",
"tag3"
]
},
"productsByKey": [
{
"catalogId": "catalog_001",
"productCode": "PROD123456",
"sellerId": "seller_78910"
}
]
},
"approval": {
"rejectionReason": "text",
"state": "APPROVAL_STATE_PENDING"
},
"bannerConfig": {
"contentStandardId": "content_standard_001",
"slotsConfiguration": [
{
"altText": null,
"artworkImageId": "ysdcsdcsdcsdc=",
"link": "http://abc.com/",
"slotId": "Category",
"text": null,
"trackingTagProvider": [
{
"content": "<IMG SRC=\"https://example.com\">",
"provider": "TRACKING_TAG_PROVIDER_DCM_IMPRESSION"
}
]
}
]
},
"bannerXConfig": {
"additionalFields": [
{
"id": "12345abcde",
"value": "abcd-8798uhu"
}
],
"backgroundColourHex": "#FFFFFF",
"backgroundImageId": "bg_image_001",
"backgroundImagePosition": "BANNER_X_BACKGROUND_IMAGE_POSITION_REPEATING",
"bannerText": "Summer Sale: Up to 50% off!",
"bannerTextColourHex": "#FF5733",
"companionProducts": [
{
"catalogId": "catalog_001",
"productCode": "PROD123456",
"sellerId": "seller_78910"
}
],
"contentStandardId": "content_standard_001",
"ctaFlag": true,
"ctaLink": "https://www.example.com",
"ctaText": "Click Here",
"ctaTextAccessibility": "Click to learn more",
"headingText": "Welcome to our store!",
"heroImageAltText": "This is the hero image.",
"heroImageId": "hero-image-id-456",
"heroMode": "BANNER_X_HERO_IMAGE_MODE_BLOCK",
"secondaryBackgroundImageId": "secondary-image-id-123",
"secondaryBackgroundImagePosition": "BANNER_X_BACKGROUND_IMAGE_POSITION_REPEATING",
"secondaryHeroImageAltText": "Secondary hero image description",
"secondaryHeroImageId": "456defghi",
"secondaryHeroMode": "BANNER_X_HERO_IMAGE_MODE_BLOCK",
"slotId": "slot_001",
"slotType": "BANNER_X_SLOT_TYPE_BANNER",
"trackingTagProvider": [
{
"content": "<script src='tracking.js'></script>",
"provider": "TRACKING_TAG_PROVIDER_DV"
}
],
"videoConfigs": [
{
"fileId": "video-id-1234",
"id": "id-1234-1234"
}
]
},
"brandPageConfig": {
"brandPageTemplateId": "tpl_brand_001",
"content": [
{
"brandPageModuleTemplateId": "text",
"contentType": "BRAND_PAGE_CONTENT_TYPE_HERO",
"filterMenu": {
"items": [
{
"label": "text",
"value": "text"
}
]
},
"hero": {
"ctaLink": "text",
"ctaText": "text",
"headline": "text",
"mediaAlt": "text",
"mediaType": "text",
"mediaUrl": "text",
"overlayBackground": "HERO_OVERLAY_BACKGROUND_GRADIENT",
"overlayEnabled": true,
"subheadline": "text"
},
"id": "text",
"image": {
"additionalTextLines": [
{
"name": "text",
"text": "text",
"url": "text"
}
],
"alt": "text",
"caption": "text",
"linkType": "IMAGE_LINK_TYPE_IMAGE",
"linkUrl": "text",
"product": {
"catalogId": "catalog_001",
"productCode": "PROD123456",
"sellerId": "seller_78910"
},
"url": "text"
},
"imageGallery": {
"cta": {
"text": "text",
"url": "text"
},
"images": [
{
"additionalTextLines": [
{
"name": "text",
"text": "text",
"url": "text"
}
],
"alt": "text",
"caption": "text",
"linkType": "IMAGE_LINK_TYPE_IMAGE",
"linkUrl": "text",
"product": {
"catalogId": "catalog_001",
"productCode": "PROD123456",
"sellerId": "seller_78910"
},
"url": "text"
}
],
"sectionDescription": "text",
"sectionTitle": "text"
},
"order": 1,
"productGrid": {
"cta": {
"text": "text",
"url": "text"
},
"products": [
{
"filterValues": [
"text"
],
"order": 1,
"product": {
"catalogId": "catalog_001",
"productCode": "PROD123456",
"sellerId": "seller_78910"
}
}
],
"sectionDescription": "text",
"sectionTitle": "text"
},
"splitLayout": {
"children": [
{
"nestedSplitLayout": {
"brandPageModuleTemplateId": "text",
"children": [
{
"brandPageModuleTemplateId": "text",
"contentType": "BRAND_PAGE_CONTENT_TYPE_HERO",
"id": "text",
"image": {
"additionalTextLines": [
{
"name": "text",
"text": "text",
"url": "text"
}
],
"alt": "text",
"caption": "text",
"linkType": "IMAGE_LINK_TYPE_IMAGE",
"linkUrl": "text",
"product": {
"catalogId": "catalog_001",
"productCode": "PROD123456",
"sellerId": "seller_78910"
},
"url": "text"
},
"order": 1,
"text": {
"cta": {
"text": "text",
"url": "text"
},
"text": "text",
"textLines": {
"lines": [
{
"name": "text",
"text": "text",
"url": "text"
}
]
}
}
}
],
"contentType": "BRAND_PAGE_CONTENT_TYPE_HERO",
"id": "text",
"order": 1
},
"nonLayout": {
"brandPageModuleTemplateId": "text",
"contentType": "BRAND_PAGE_CONTENT_TYPE_HERO",
"id": "text",
"image": {
"additionalTextLines": [
{
"name": "text",
"text": "text",
"url": "text"
}
],
"alt": "text",
"caption": "text",
"linkType": "IMAGE_LINK_TYPE_IMAGE",
"linkUrl": "text",
"product": {
"catalogId": "catalog_001",
"productCode": "PROD123456",
"sellerId": "seller_78910"
},
"url": "text"
},
"order": 1,
"text": {
"cta": {
"text": "text",
"url": "text"
},
"text": "text",
"textLines": {
"lines": [
{
"name": "text",
"text": "text",
"url": "text"
}
]
}
}
}
}
]
},
"text": {
"cta": {
"text": "text",
"url": "text"
},
"text": "text",
"textLines": {
"lines": [
{
"name": "text",
"text": "text",
"url": "text"
}
]
}
}
}
],
"contentStandardId": "content_standard_001",
"enabledAdTypes": [
"ENABLED_AD_TYPES_DISPLAY"
],
"featureVersion": "BRAND_PAGE_FEATURE_VERSION_1",
"name": "text",
"pageContentText": "text",
"pageHeadingText": "text",
"url": "https://retailer.com",
"urlPrefix": "/brands/",
"urlSuffix": "acme-summer-2026"
},
"campaignState": "CAMPAIGN_STATE_ACTIVE",
"catalogIds": [
"catalog_001",
"catalog_002"
],
"customFields": [
{
"content": "This is a custom field content.",
"customFieldId": "cfid_12345"
}
],
"customQuestions": [
{
"answers": [
"Answer 1",
"Answer 2",
"Answer 3"
],
"customQuestionId": "cqid_67890"
}
],
"endTime": "2024-09-30T23:59:59Z",
"fixedCosts": {
"creativeCost": "$200.00",
"dataCost": "$100.00",
"otherCost": "$50.00"
},
"id": "abc123xyz",
"managerTeamId": "manager_team_67890",
"name": "Summer Sale Campaign",
"namespaceId": "namespace_001",
"placementId": "placement_987654321",
"sellerId": "seller_12345",
"servingState": "SERVING_STATE_SCHEDULED",
"settings": {
"campaignType": "CAMPAIGN_TYPE_DISPLAY",
"fromTime": "2024-09-01T12:34:56Z",
"toTime": "2024-09-01T12:34:56Z"
},
"startTime": "2024-09-01T12:00:00Z",
"strategy": {
"auction": {
"automatedBid": {
"enableAutomatedBid": true,
"objectiveType": "OBJECTIVE_TYPE_BUDGET_ONLY",
"targetRoas": "2.5"
},
"maxBid": "$100.00",
"spendLimit": {
"daily": "$50.00",
"total": "$1000.00"
}
},
"fixedTenancy": {
"catalogCosts": [
{
"catalogCostPercentage": 0.25,
"catalogId": "catalog_123456"
}
],
"cost": "$99.99",
"positions": [
1,
2,
3
]
}
},
"targeting": {
"audience": {
"includeSegmentsSets": [
{
"segmentIds": [
"text"
]
}
]
},
"crossSell": {
"targetProductsByAttributes": {
"subclassTags": [
"Electronics",
"Home Appliances"
],
"vendorTags": [
"BrandX",
"BrandY"
]
},
"targetProductsByKey": [
{
"catalogId": "catalog_001",
"productCode": "PROD123456",
"sellerId": "seller_78910"
}
]
},
"excludeFilters": [
{
"catalogId": "catalog_12345",
"filter": "filter_value_abc"
}
],
"includeFilters": [
{
"catalogId": "catalog_12345",
"filter": "filter_value_abc"
}
],
"negativeSearchTerms": [
{
"matchType": "MATCH_TYPE_EXACT_MATCH",
"phrase": "text"
}
],
"searchTerms": [
{
"collectionName": "default_collection",
"excludedProducts": [
{
"catalogId": "catalog_001",
"productCode": "PROD123456",
"sellerId": "seller_78910"
}
],
"matchType": "MATCH_TYPE_PHRASE_MATCH",
"maxBid": "100.00",
"phrase": "example search term",
"suggested": true,
"treatAsCustom": true
}
],
"upsell": {
"targetProductsByAttributes": {
"priceRange": {
"max": "100",
"min": "10"
},
"subclassTags": [
"text"
],
"vendorTags": [
"text"
]
},
"targetProductsByKey": [
{
"catalogId": "catalog_001",
"productCode": "PROD123456",
"sellerId": "seller_78910"
}
]
}
},
"teamId": "team_12345",
"templateId": "template_123",
"updateTime": "2024-09-01T12:34:56Z",
"walletId": "wallet_123456789"
}
],
"nextPageToken": "text",
"totalCount": "text"
}