Create and Manage Campaign Groups

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

There are two conditions for successful calls: (1) Scope permissions to rw_ads and/or r_ads, and (2) the user assigning permission holding one of the following roles in the Ad Account.

Scope permissions:

  • rw_ads (Read/Write)
  • r_ads (Read-Only)

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:

Pagination

The adCampaignGroupsV2 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 does not contain pagination request parameters

For more information, see Pagination.

Schema

Field Name Type Description
account SponsoredAccountUrn URN identifying the advertising account associated with the campaign. This value is immutable once set. For example, urn:li:SponsoredAccount:{id}.
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.
id long Numerical identifier for the campaign group. This is a read-only field set by the system.
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 cannot exceed 100 characters.
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.
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.
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 is 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.
  • 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 cannot 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 should not be.
  • totalBudget.amount BigDecimal Maximum amount to spend across all associated campaigns and creatives for duration of the campaign group.
    totalBudget.currencyCode Currency Maximum amount to spend over the life of the campaign. The currency must match the ISO currency code of the account.
    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 is set implicitly during creation based on whether the account is a Test Account or not.
    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.
  • 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 is recommended to check allowedCampaignTypes first.

  • Create a Campaign Group

    Campaign groups can be created in ACTIVE or DRAFT state. You can change ACTIVE to ARCHIVED or PAUSED.

    POST https://api.linkedin.com/v2/adCampaignGroupsV2
    
    {
        "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

    GET https://api.linkedin.com/v2/adCampaignGroupsV2/{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

    Use the q=search parameter with to search for campaign groups by ID, account, name, and status fields. Search criteria can be chained together for increased granularity. If a search query is omitted, all campaign groups the caller has access to are returned in a paginated response.

    GET https://api.linkedin.com/v2/adCampaignGroupsV2?q=search&search.{searchCriteria}.values[0]={searchValue}
    

    Parameters

    Field Name Required Description
    search.account.values no Searches for campaign groups associated with the provided sponsored account URN.
    search.id.values no Searches for campaign groups by ID.
    search.status.values no Searches for campaign groups with the provided status. The possible values are:
  • ACTIVE
  • ARCHIVED
  • CANCELED
  • DRAFT
  • PAUSED
  • 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.
  • sort.field no Identifies an individual field to use as a sorting key.
    sort.order no Specifies the sort order of the results. Supported values include:
    • ASCENDING
    • DESCENDING
    The default is "ASCENDING".

    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/v2/adCampaignGroupsV2?q=search&search.status.values[0]=ACTIVE&search.status.values[1]=DRAFT&sort.field=ID&sort.order=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:504293601",
                "status": "ACTIVE"
            }
        ],
        "paging": {
            "total": 226,
            "count": 10,
            "start": 0,
            "links": []
        }
    }
    

    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.

    Update a Campaign Group

    Campaign groups can be updated with a partial update.

    Note

    If the account type is ENTERPRISE, you cannot 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/v2/adCampaignGroupsV2/{adCampaignGroupId}
    
    {
        "patch": {
            "$set": {
                "totalBudget": {
                    "amount": "3000",
                    "currencyCode": "USD"
                }
            }
        }
    }
    

    To update the status:

    POST https://api.linkedin.com/v2/adCampaignGroupsV2/{adCampaignGroupId}
    
    {
        "patch": {
            "$set": {
                "status": "DRAFT"
            }
        }
    }
    

    Delete a Campaign Group

    A Campaign Group can be deleted.

    Caution

    Only campaign groups which are in DRAFT status are allowed to be deleted.
    Once deleted, a campaign group can't be retrieved or recovered.

    Sample Request

    DELETE https://api.linkedin.com/v2/adCampaignGroupsV2/CAMPAIGN_GROUP_ID
    

    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/v2/adCampaignGroupsV2
    
    {
        "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/v2/adCampaignGroupsV2?ids={campaignGroupId}&ids={campaignGroupId}
    

    Sample Request

    GET https://api.linkedin.com/v2/adCampaignGroupsV2?ids=604716224&ids=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 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 cannot 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/v2/adCampaignGroupsV2?ids=604716224&ids=604716214
    
    {
        "entities": {
            "604716214": {
                "patch": {
                    "$set": {
                        "totalBudget": {
                            "amount": "3000",
                            "currencyCode": "USD"
                        }
                    }
                }
            },
            "604716224": {
                "patch": {
                    "$set": {
                        "status": "ACTIVE"
                    }
                }
            }
        }
    }
    

    Batch Delete Campaign Groups

    Caution

    Only campaign groups which are in DRAFT status are allowed to be deleted.
    Once deleted, a campaign group can't be retrieved or recovered.

    Sample Request

    DELETE https://api.linkedin.com/v2/adCampaignGroupsV2?ids=List(CAMPAIGN_GROUP_ID1, CAMPAIGN_GROUP_ID2)
    

    A successful response returns a 204 code.