adCampaignGroups

  • Article

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

Supported Methods

CREATE | GET | SEARCH FINDER | PARTIAL UPDATE | BATCH CREATE | BATCH GET | BATCH PARTIAL UPDATE

adCampaignGroups Schema

Field Name Type Description
account SponsoredAccountUrn URN identifying the advertising account associated with the Campaign Group. This value is immutable once set
name string The name of the Campaign Group. Primarily used to make it easier to reference a Campaign Group and to recall its purpose
status string, default="ACTIVE" 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 CANCELED -  Denotes that the Campaign Group has been permanently canceled and cannot be reactivated DRAFT - Denotes 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 optional BigDecimal Maximum amount to spend over the life of the Campaign Group. The currency must match that of the Account
totalBudget.currencyCode optional currency ISO currency code. The currency code must match that of the parent account
runSchedule.start long Represents the inclusive (greater than or equal to) value in which to start the range. This field is mandatory
runSchedule.end optional long Scheduled date range to run associated objects. The start date must be non-null. Represents the exclusive (strictly less than) value in which to end the range. This field is optional. An unset field here indicates an open range; for example, if start is 1455309628000 (Fri, 12 Feb 2016 20:40:28 GMT), and end is not set, it would mean everything at, or after, 1455309628000. If totalBudget is set, this field is mandatory 
backfilled boolean, default="false" Flag that denotes whether the Campaign Group was created organically or was created to backfill existing campaigns. This is a system controlled field
servingStatuses strings[] 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.
id long Numerical identifier for the campaign group

CREATE

POST https://api.linkedin.com/v2/adCampaignGroupsV2

Body Fields

Field Name Sub-Field Name Description
account   URN identifying the advertising account associated with the Campaign Group. This value is immutable once set
name   The name of the Campaign Group. Primarily used to make it easier to reference a Campaign Group and to recall its purpose
runSchedule   Scheduled date range to run associated objects. The start date must be non-null
  start Represents the inclusive (greater than or equal to) value in which to start the range. This field is mandatory.
  end Scheduled date range to run associated objects. The start date must be non-null. Represents the exclusive (strictly less than) value in which to end the range. This field is optional. An unset field here indicates an open range; for example, if start is 1455309628000 (Fri, 12 Feb 2016 20:40:28 GMT), and end is not set, it would mean everything at, or after, 1455309628000. If totalBudget is set, this field is mandatory 
totalBudget   Maximum amount to spend over the life of the Campaign Group. The currency must match that of the Account
  amount The amount of money as a real number string
  currencyCode ISO currency code
status   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 CANCELED -  Denotes that the Campaign Group has been permanently canceled and cannot be reactivated DRAFT - Denotes 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

sample request body

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

GET

GET https://api.linkedin.com/v2/adCampaignGroupsV2/{campaignGroup ID}

Parameters

Field Name Description
campaignGroup ID Unique numerical identifier for the ad campaign

Sample Response

{
    "account": "urn:li:sponsoredAccount:512352200",
    "backfilled": false,
    "changeAuditStamps": {
        "created": {
            "actor": "urn:li:person:324_kGGaLE",
            "time": 1493054119000
        },
        "lastModified": {
            "actor": "urn:li:unknown:0",
            "time": 1493054119000
        }
    },
    "id": 602830604,
    "name": "CampaignGroup1",
    "runSchedule": {
        "end": 9876543210123,
        "start": 1234567890987
    },
    "servingStatuses": [
        "CAMPAIGN_GROUP_START_DATE_HOLD",
        "BILLING_HOLD"
    ],
    "status": "ACTIVE",
    "totalBudget": {
        "amount": "60000",
        "currencyCode": "USD"
    }
}

SEARCH FINDER

GET https://api.linkedin.com/v2/adCampaignGroupsV2?q=search

Parameters

Field Name Description
search.account.value Searches for Campaign Groups associated with the provided sponsored account URN
search.id.value Searches for Campaign Groups by ID
search.status.value Searches for Campaign Groups with the provided status. The possible values are:
  • ACTIVE
  • ARCHIVED
  • CANCELED
  • COMPLETED
  • DRAFT
  • PAUSED 
search.name.value Searches for Campaign Groups by name
sort.field Identifies an individual field to use as a sorting key
sort.order Specifies the sort order of the results. Supported values include:
  • ASCENDING
  • DESCENDING
The default is "ASCENDING"

Example

The query below fetches all active Campaign Groups and sorts the results by id in descending order.

GET https://api.linkedin.com/v2/adCampaignGroupsV2?q=search&search.status.values[0]=ACTIVE&sort.field=ID&sort.order=DESC

Sample Response

{
    "elements": [
        {
            "account": "urn:li:sponsoredAccount:512352200",
            "backfilled": false,
            "changeAuditStamps": {
                "created": {
                    "actor": "urn:li:person:324_kGGaLE",
                    "time": 1494962256000
                },
                "lastModified": {
                    "actor": "urn:li:unknown:0",
                    "time": 1494962256000
                }
            },
            "id": 604711434,
            "name": "CampaignGroup1",
            "runSchedule": {
                "end": 9876543210123,
                "start": 1234567890987
            },
            "servingStatuses": [
                "RUNNABLE"
            ],
            "status": "ACTIVE",
            "totalBudget": {
                "amount": "60000",
                "currencyCode": "USD"
            }
        }
    ],
    "paging": {
        "count": 1,
        "start": 0,
        "total": 10
    }
}

PARTIAL UPDATE

POST https://api.linkedin.com/v2/adCampaignGroupsV2/{campaignGroup ID}

Body Fields

Field Name Sub-Field Name Description
name   The name of the Campaign Group. Primarily used to make it easier to reference a Campaign Group and to recall its purpose
status   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 CANCELED -  Denotes that the Campaign Group has been permanently canceled and cannot be reactivated DRAFT - Denotes 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 betotalBudget.amount
runSchedule   Scheduled date range to run associated objects. The start date must be non-null
  start Represents the inclusive (greater than or equal to) value in which to start the range. This field is mandatory.
  end Scheduled date range to run associated objects. The start date must be non-null. Represents the exclusive (strictly less than) value in which to end the range. This field is optional. An unset field here indicates an open range; for example, if start is 1455309628000 (Fri, 12 Feb 2016 20:40:28 GMT), and end is not set, it would mean everything at, or after, 1455309628000. If totalBudget is set, this field is mandatory 
totalBudget   Maximum amount to spend over the life of the Campaign. The currency must match that of the Account
  amount The amount of money as a real number string
  currencyCode ISO currency code

Sample Request Body

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

BATCH CREATE

POST https://api.linkedin.com/v2/adCampaignGroupsV2

Required Batch Header

Name Value
X-RestLi-Method BATCH_CREATE

Sample Request Body

{
    "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

GET https://api.linkedin.com/v2/adCampaignGroupsV2?ids=602445944&ids=604711464

Sample Response Body

{
    "errors": {},
    "results": {
        "602445944": {
            "account": "urn:li:sponsoredAccount:512352200",
            "backfilled": false,
            "changeAuditStamps": {
                "created": {
                    "actor": "urn:li:person:324_kGGaLE",
                    "time": 1492623245000
                },
                "lastModified": {
                    "actor": "urn:li:unknown:0",
                    "time": 1492623245000
                }
            },
            "id": 602445944,
            "name": "CampaignGroup2",
            "runSchedule": {
                "end": 9876543210123,
                "start": 1234567890987
            },
            "servingStatuses": [
                "CAMPAIGN_GROUP_START_DATE_HOLD",
                "BILLING_HOLD",
                "CAMPAIGN_GROUP_TOTAL_BUDGET_HOLD"
            ],
            "status": "ACTIVE",
            "totalBudget": {
                "amount": "60000",
                "currencyCode": "USD"
            }
        },
        "604711464": {
            "account": "urn:li:sponsoredAccount:512352200",
            "backfilled": false,
            "changeAuditStamps": {
                "created": {
                    "actor": "urn:li:person:324_kGGaLE",
                    "time": 1494962643000
                },
                "lastModified": {
                    "actor": "urn:li:unknown:0",
                    "time": 1494962643000
                }
            },
            "id": 604711464,
            "name": "CampaignGroup3",
            "runSchedule": {
                "end": 9876543210123,
                "start": 1234567890987
            "servingStatuses": [
                "BILLING_HOLD"
            ],
            "status": "ACTIVE",
            "totalBudget": {
                "amount": "30000",
                "currencyCode": "USD"
            }
        }
    },
    "statuses": {}
}

BATCH PARTIAL UPDATE

POST https://api.linkedin.com/v2/adCampaignGroupsV2?ids=602445944&ids=604711464

Required Batch Header

Name Value
X-RestLi-Method BATCH_PARTIAL_UPDATE

Sample Request Body

{
    "entities": {
        "602445944": {
            "patch": {
                "$set": {
                    "status": "ACTIVE"
                }
            }
        },
        "604711464": {
            "patch": {
                "$set": {
                    "totalBudget": {
                        "amount": "6000",
                        "currencyCode": "USD"
                    }
                }
            }
        }
    }
}