Share via

Create and Manage Campaign Groups

Warning

Deprecation Notice The Marketing Version 202411 (Marketing November 2024) has been sunset. We recommend that you migrate to the latest versioned APIs to avoid disruptions. See the Migration page for more details. If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.

Try in Postman

Campaign groups provide advertisers a way to manage status, budget, and performance across multiple related campaigns.

Whenever an Ad Account is created, a new campaign group is automatically created for it.

A campaign group can contain a variety of campaign types. There is no limit to the number of campaign groups per advertiser account. Note that LinkedIn imposes a limit of 5,000 campaigns per advertiser account and 2,000 campaigns per non-default campaign group.

Permissions

two conditions for successful Ad Account Users API calls:

  • Scope permission accessibility for:

  • rw_ads (read/write).

  • r_ads (read-only)

  • The Ad Account user assigning permission holding one of the following Ad Account roles:

  • ACCOUNT_BILLING_ADMIN

  • ACCOUNT_MANAGER

  • CAMPAIGN_MANAGER

  • CREATIVE_MANAGER

  • VIEWER (read-only, even with rw_ads scope)

For more information on Ad Account roles and permissions, refer to the following:

Pagination for non-search APIs

The adCampaignGroups API implements pagination using the start and count parameters for several methods. The max count value is 1000. A 400 Bad Request response with the message, "Specified count is larger than 1000" is returned if:

  • The count is greater than 1000.
  • The number of elements in the response is greater than 100, and the API request doesn't contain pagination request parameters.

For more information, see Pagination.

Schema

Note

Starting 202211, response decoration is no longer supported and has been replaced by Additional Info Fields. These new field(s) provide additional information for a field that's present in a schema. Learn more about the Additional Info Fields here. The fields budgetOptimization.bidStrategy and budgetOptimization.budgetOptimizationStrategyare only supported starting from API versions 202501.

Field Name Type Description Additional Info Field
account SponsoredAccountUrn URN identifying the advertising account associated with the campaign. This value is immutable once set. For example, urn:li:SponsoredAccount:{id}. False
accountInfo Account Information about the advertising account associated with the campaign. This is a read only field. Please refer to Additional Info Fields to learn how to access this field. True
backfilled boolean, default="false" Flag that denotes whether the campaign group was created organically or to backfill existing campaigns. This is a read-only field set by the system. False
id long Numerical identifier for the campaign group. This is a read-only field set by the system. False
name string The name of the campaign group used to make it easier to reference a campaign group and recall its purpose. The value of this field can't exceed 100 characters. False
runSchedule.start long Represents the inclusive (greater than or equal to) date when to start running the associated campaigns under this campaign group. This field is required. False
runSchedule.end optional long Represents the exclusive (strictly less than) date when to stop running the associated campaigns under this campaign group. If this field is unset, it indicates an open range with no end date. This field is required if totalBudget is set. False
servingStatuses string[] Array of enums that determine whether or not campaigns within the campaign group may be served. Unlike status, which is user-managed, the values are controlled by the service. This is a read-only field. Possible values are:
  • RUNNABLE Campaign group is currently active; billing information, budgetary constraints, or start and end dates are valid.
  • STOPPED Campaign group is currently not eligible for serving for reasons other than billing information, budgetary constraints, or termination dates. For instance, a campaign group will be STOPPED if it has been canceled by the user, or it's marked as spam.
  • BILLING_HOLD Parent account is on billing hold.
  • ACCOUNT_TOTAL_BUDGET_HOLD Parent account total budget has been reached.
  • ACCOUNT_END_DATE_HOLD Parent account end date has been reached.
  • CAMPAIGN_GROUP_TOTAL_BUDGET_HOLD Campaign group total budget has been reached.
  • CAMPAIGN_GROUP_START_DATE_HOLD Campaign group start date is in the future.
  • CAMPAIGN_GROUP_END_DATE_HOLD Campaign group end date has been reached.
    		•  False
    status string Status of campaign group. Possible values are:
  • ACTIVE - Denotes that the campaign group is capable of serving ads, subject to run date and budget limitations (as well as any other limitations at the account or campaign level).
  • ARCHIVED - Denotes that the campaign group is presently inactive, and should mostly be hidden in the UI until un-archived.
  • CANCELLED - Denotes that the campaign group has been permanently canceled and can't be reactivated. Not a settable status.
  • DRAFT - Denotes that the campaign group is in a preliminary state and should temporarily not be served.
  • PAUSED - Denotes that the campaign group meets all requirements to be served, but temporarily shouldn't be.
  • PENDING_DELETION - Denotes that the campaign group has been requested to be deleted that's currently pending.
  • REMOVED - Denoted that the campaign group was deleted, but must remain fetchable due to the existence of performance data.
    		•  False
    totalBudget.amount BigDecimal If budgetOptimization.budgetOptimizationStrategy is DYNAMIC, the total budget of the campaign group will be shared among all campaigns within the same campaign group. Otherwise, it represents the maximum amount to be spent across all associated campaigns and creatives for the duration of the campaign group. False
    totalBudget.currencyCode Currency Indicates the currencyCode of the campaign group's total budget. Note: The currency must match the ISO currency code of the account. False
    test boolean, default="false" Flag showing whether this campaign group is a test campaign group, i.e., belongs to a test account. This is a read-only and immutable field that's set implicitly during creation based on whether the account is a Test Account or not. False
    allowedCampaignTypes string[] Array of enums that indicates allowed campaign types within the specific campaign group. Possible values are:
  • TEXT_AD - Text-based ads that show up in the right column or top of the page on LinkedIn.
  • SPONSORED_UPDATES - Native ads that promote a company's content updates in the LinkedIn feed.
  • SPONSORED_INMAILS - Personalized messages with a call-to-action button delivered to a LinkedIn's member inbox.
  • DYNAMIC - Ads that are dynamically personalized. This is a read-only field.
    		•  False
    objectiveType string Campaign Group Objective type values. This field is optional and immutable. Campaigns in this group will automatically have the same objective type. Click here for Objective descriptions
  • BRAND_AWARENESS
  • ENGAGEMENT
  • JOB_APPLICANTS
  • LEAD_GENERATION
  • WEBSITE_CONVERSIONS
  • WEBSITE_VISITS
  • VIDEO_VIEWS
    		•
    budgetOptimization.bidStrategy string Denotes the strategy used for bidding in auction. Campaigns under the campaign group must have the same bid strategy. Possible values:
  • MAXIMUM_DELIVERY
  • MANUAL
  • COST_CAP
    		•
    budgetOptimization.budgetOptimizationStrategy string Strategy used for campaign group budgeting to decide how to allocate budget across campaigns under the campaign group. Possible values:
  • DYNAMIC
    		•
    dailyBudget BigDecimal Daily budget for the campaign group and will be shared among all campaigns within the campaign group. This field is optional and mutable. It can only be used if budgetOptimization.budgetOptimizationStrategy is DYNAMIC Note: This field applies to API Versions starting from 202504 and later. False

    Note

    allowedCampaignTypes is in the response only when the account type is ENTERPRISE and is not in the response when account type is BUSINESS (as all campaign types can be created within Business accounts.)

  • Before creating new campaigns in Enterprise accounts, it's recommended to check allowedCampaignTypes first.

    • Create a Campaign Group

    Campaign groups can be created in ACTIVE or DRAFT state. Can be changed from ACTIVE to ARCHIVED or PAUSED.

    Try in Postman

    POST https://api.linkedin.com/rest/adAccounts/512352200/adCampaignGroups

    {
    "account": "urn:li:sponsoredAccount:512352200",
    "name": "CampaignGroup1",
    "runSchedule": {
        "end": 9876543210123,
        "start": 1234567890987
    },
    "status": "ACTIVE",
    "totalBudget": {
        "amount": "60000.00",
        "currencyCode": "USD"
    }
}

    Budgeting and Run Schedule

    Budgets and start/end dates can exist at the advertiser account, campaign group, or campaign levels. If there's a conflict between levels, the more restrictive values are used for serving.

    Get a Campaign Group

    Try in Postman

    GET https://api.linkedin.com/rest/adAccounts/{adAccountId}/adCampaignGroups/{adCampaignGroupsId}

    Sample Response

    {
    "account": "urn:li:sponsoredAccount:512358882",
    "backfilled": false,
    "changeAuditStamps": {
        "created": {
            "actor": "urn:li:person:324_kGGaLE",
            "time": 1490074934000
        },
        "lastModified": {
            "actor": "urn:li:unknown:0",
            "time": 1490074934000
        }
    },
    "id": 512358882,
    "name": "New Campaign Group",
    "runSchedule": {
        "end": 9876543210123,
        "start": 1234567890987
    },
    "test": false,
    "servingStatuses": [
        "BILLING_HOLD"
    ],
    "allowedCampaignTypes": [
        "SPONSORED_UPDATES",
        "TEXT_AD"
    ],
    "status": "ACTIVE"
}

    Search for Campaign Groups

    Try in Postman

    Note

    From 202,401 version and above, we have moved from index based pagination to cursor based pagination for our search APIs.

    Cursor based Pagination for search APIs

    The adCampaignGroups API implements cursor based pagination using the pageSize and pageToken parameters for search method. The max allowed pageSize is 1,000.

    • pageSize governs the number of requested entities
    • pageToken is used to get the next set of results.
    • nextPageToken is returned in metadata field of the search response.
    • This should be passed in pageToken query parameter in the request to get the next page of results.

    Use the q=search parameter with to search for campaign groups by ID, name, and status fields. Search criteria is mandatory and can be chained together for increased granularity.

    GET https://api.linkedin.com/rest/adAccounts/{adAccountId}/adCampaignGroups?q=search&search=(searchCriteria:(values:List(searchValue)))

    Parameters

    Field Name Required Description
    search.id.values no Searches for campaign groups by ID. For example, urn:li:sponsoredCampaignGroup:{campaignGroupId}
    search.status.values no Searches for campaign groups with the provided status. The possible values are:
  • ACTIVE
  • ARCHIVED
  • CANCELED
  • DRAFT
  • PAUSED
  • PENDING_DELETION
  • REMOVED
    		•
    search.name.values no Searches for campaign groups by name.
    search.test no Searches for campaign groups based on test or non-test.
  • true: for test campaign groups
  • false: for non-test campaign groupsIf not specified, searches for both test and non-test campaign groups.
    		•
    sortOrder no Specifies the sort order of the results. Results will be sorted by campaign group id. Supported values include:
  • ASCENDING
  • DESCENDING The default is "ASCENDING".
    		•
    pageSize no Specifies the number of entities to be returned. The default is 100. Max is 1,000.
    pageToken no Unique key representing the last entity of the response. This is to be used to fetch the next set of entities. If less than pageSize entities are returned in the current response, pageToken will be null

    Sample Request

    The following example searches for all campaign groups in ACTIVE and DRAFT status. The results are ordered by id in descending order.

    GET https://api.linkedin.com/rest/adAccounts/506223315/adCampaignGroups?q=search&search=(status:(values:List(ACTIVE,DRAFT)))&sortOrder=DESCENDING

    Sample Response

    {
    "elements": [
        {
            "runSchedule": {
                "end": 9876543210123,
                "start": 1234567890987
            },
            "changeAuditStamps": {
                "created": {
                    "time": 1542042798000
                },
                "lastModified": {
                    "time": 1542129293297
                }
            },
            "name": "Refresh group",
            "test": false,
            "servingStatuses": [
                "CAMPAIGN_GROUP_END_DATE_HOLD",
                "BILLING_HOLD"
            ],
            "allowedCampaignTypes": [
                "SPONSORED_UPDATES",
                "TEXT_AD"
            ],
            "backfilled": false,
            "id": 603407684,
            "account": "urn:li:sponsoredAccount:506223315",
            "status": "ACTIVE"
        },
        {
            "runSchedule": {
                "start": 1493228897000
            },
            "changeAuditStamps": {
                "created": {
                    "time": 1493228897000
                },
                "lastModified": {
                    "time": 1493228897000
                }
            },
            "name": "New Campaign Group",
            "test": false,
            "servingStatuses": [
                "BILLING_HOLD"
            ],
            "allowedCampaignTypes": [
                "SPONSORED_UPDATES",
                "TEXT_AD"
            ],
            "backfilled": false,
            "id": 504293601,
            "account": "urn:li:sponsoredAccount:506223315",
            "status": "ACTIVE"
        }
    ],
    "metadata": {
        "nextPageToken": "DgGerr1iVQreCJVjDOW_rcp63nueBDipsS4DJpvJo"
    }
}

    Note

    The above call may return both test and non-test campaign groups. If you would like to search only non-test campaign groups, you can filter out the test campaign groups by specifying search.test=false.
    If you would like to search only test campaign groups, specify search.test=true.

    API Call to get the next set of results would use the nextPageToken passed in the response above.

    GET https://api.linkedin.com/rest/adAccounts/506223315/adCampaignGroups?q=search&search=(status:(values:List(ACTIVE,DRAFT)))&sortOrder=DESCENDING&pageToken=DgGerr1iVQreCJVjDOW_rcp63nueBDipsS4DJpvJo

    Update a Campaign Group

    Try in Postman

    Campaign groups can be updated with a partial update.

    Note

    If the account type is ENTERPRISE, you can't update the default campaign group's fields through the API. To identify default campaign groups, check if backfilled is set to true. For non-default campaign groups, only name and status are mutable.

    Sample Request

    To update the budget:

    POST https://api.linkedin.com/rest/adAccounts/{adAccountId}/adCampaignGroups/{adCampaignGroupId}

    {
    "patch": {
        "$set": {
            "totalBudget": {
                "amount": "3000",
                "currencyCode": "USD"
            }
        }
    }
}

    To update the status:

    POST https://api.linkedin.com/rest/adAccounts/{adAccountId}/adCampaignGroups/{adCampaignGroupId}

    {
    "patch": {
        "$set": {
            "status": "DRAFT"
        }
    }
}

    Delete a Campaign Group

    Try in Postman

    A Campaign Group can be deleted. Use DELETE method to delete a DRAFT campaign group. To start the process of deleting non DRAFT campaign group, update the status to PENDING_DELETION.

    Sample Request

    To delete DRAFT campaign group:

    DELETE https://api.linkedin.com/rest/adAccounts/{adAccountId}/adCampaignGroups/{adCampaignGroupId}

    To delete non DRAFT campaign group:

    POST https://api.linkedin.com/rest/adAccounts/{adAccountId}/adCampaignGroups/{adCampaignGroupId}
{
    "patch": {
        "$set": {
            "status": "PENDING_DELETION"
        }
    }
}

    A successful response returns a 204 code.

    Batch Operations

    Batch operations may only be performed on entities that belong to the same Ad Account.

    Batch Create Campaign Groups

    When you perform a batch create, the header X-RestLi-Method must be included in the request and set to BATCH_CREATE.

    Note

    This API is currently not supported for ENTERPRISE accounts.

    Sample Request

    POST https://api.linkedin.com/rest/adAccounts/512352200/adCampaignGroups

    {
    "elements": [
        {
            "account": "urn:li:sponsoredAccount:512352200",
            "name": "CampaignGroup2",
            "runSchedule": {
                "end": 9876543210123,
                "start": 1234567890987
            },
            "status": "ACTIVE",
            "totalBudget": {
                "amount": "60000.00",
                "currencyCode": "USD"
            }
        },
        {
            "account": "urn:li:sponsoredAccount:512352200",
            "name": "CampaignGroup3",
            "runSchedule": {
                "end": 9876543210123,
                "start": 1234567890987
            },
            "status": "ACTIVE",
            "totalBudget": {
                "amount": "30000.00",
                "currencyCode": "USD"
            }
        }
    ]
}

    Batch Get Campaign Groups

    Multiple campaign groups can be requested in a single call by chaining together ids parameters that each have a corresponding campaign group ID.

    GET https://api.linkedin.com/rest/adAccounts/{adAccountId}/adCampaignGroups?ids=List(campaignGroupId1,campaignGroupId2)

    Sample Request

    GET https://api.linkedin.com/rest/adAccounts/512352200/adCampaignGroups?ids=List(604716224,604716214)

    Sample Response

    {
    "errors": {},
    "results": {
        "604716214": {
            "account": "urn:li:sponsoredAccount:512352200",
            "backfilled": false,
            "changeAuditStamps": {
                "created": {
                    "actor": "urn:li:person:324_kGGaLE",
                    "time": 1494970241000
                },
                "lastModified": {
                    "actor": "urn:li:unknown:0",
                    "time": 1494970241000
                }
            },
            "id": 604716214,
            "name": "CampaignGroup2",
            "runSchedule": {
                "end": 9876543210123,
                "start": 1234567890987
            },
            "test": false,
            "servingStatuses": [
                "BILLING_HOLD"
            ],
            "allowedCampaignTypes": [
                "SPONSORED_UPDATES",
                "TEXT_AD"
            ],
            "status": "ACTIVE",
            "totalBudget": {
                "amount": "60000",
                "currencyCode": "USD"
            }
        },
        "604716224": {
            "account": "urn:li:sponsoredAccount:512352200",
            "backfilled": false,
            "changeAuditStamps": {
                "created": {
                    "actor": "urn:li:person:324_kGGaLE",
                    "time": 1494970241000
                },
                "lastModified": {
                    "actor": "urn:li:unknown:0",
                    "time": 1494970241000
                }
            },
            "id": 604716224,
            "name": "CampaignGroup3",
            "test": false,
            "runSchedule": {
                "end": 9876543210123,
                "start": 1234567890987
            },
            "servingStatuses": [
                "BILLING_HOLD"
            ],
            "allowedCampaignTypes": [
                "SPONSORED_UPDATES",
                "TEXT_AD"
            ],
            "status": "ACTIVE",
            "totalBudget": {
                "amount": "30000",
                "currencyCode": "USD"
            }
        }
    },
    "statuses": {}
}

    Batch Update Campaign Groups

    Multiple campaign groups can be updated in a single call. Similar to a Batch GET, this can be done by chaining together ids parameters that each have a corresponding campaign group ID.

    When you perform a batch update, the header X-RestLi-Method must be included in the request and set to BATCH_PARTIAL_UPDATE.

    Note

    If the account type is ENTERPRISE, you can't update the default campaign group's fields through the API. To identify default campaign groups, check if backfilled is set to true. For non-default campaign groups, only name and status are mutable.

    Sample Request

    POST https://api.linkedin.com/rest/adAccounts/512352200/adCampaignGroups?ids=List(604716224,604716214)

    {
    "entities": {
        "604716214": {
            "patch": {
                "$set": {
                    "totalBudget": {
                        "amount": "3000",
                        "currencyCode": "USD"
                    }
                }
            }
        },
        "604716224": {
            "patch": {
                "$set": {
                    "status": "ACTIVE"
                }
            }
        }
    }
}

    Batch Delete Campaign Groups

    Multiple campaign groups can be deleted. Use DELETE method to delete DRAFT campaign groups. To start the process of deleting non DRAFT campaign groups, update the status to PENDING_DELETION.

    Sample Request

    To delete DRAFT campaign groups:

    DELETE https://api.linkedin.com/rest/adAccounts/{adAccountId}/adCampaignGroups?ids=List(CAMPAIGN_GROUP_ID1, CAMPAIGN_GROUP_ID2)

    To delete non DRAFT campaign groups:

    POST https://api.linkedin.com/rest/adAccounts/512352200/adCampaignGroups?ids=List(604716224,604716214)
{
    "entities": {
        "604716214": {
            "patch": {
                "$set": {
                    "status": "PENDING_DELETION"
                }
            }
        },
        "604716224": {
            "patch": {
                "$set": {
                    "status": "PENDING_DELETION"
                }
            }
        }
    }
}

    A successful response returns a 204 code.

    • Last updated on