Campaign

Campaign Example

The following is an example of the JSON data structure of a Campaign. Additional details about the individual attributes of Campaigns can be found below.

JSON

{
  "type": "Campaign",
  "attributes": {
    "name": "My Campaign",
    "advertiserId": "12345",
    "goal": "Retention",
    "spendLimit": {
      "spendLimitType": "capped",
      "spendLimitRenewal": "daily",
      "spendLimitAmount": 123.45
    },
    "budgetAutomation": {
      "enabled": true,
      "budgetConfiguration": {
        "adSetObjectives": "conversions"
      }
    }
  }
}

Campaign Attributes

name
Currently read-only. The Campaign name, set by the advertiser. advertiserId
Read-only. The advertiser associated with the Campaign. goal
The marketing goal of the Campaign. Can be Acquisition, Retention or Unspecified (only for older campaigns). spendLimit.spendLimitType
Whether the Campaign spend is capped or not. Can be capped or uncapped. spendLimit.spendLimitRenewal
The cadence of spend limit renewal. Can be daily, monthly, lifetime, or undefined. The value undefined is only returned for an uncapped spend limit. spendLimit.spendLimitAmount
A decimal value representing the spend limit for the Campaign in the advertiser’s currency. It is required when spendLimitType is capped. If spendLimitType is uncapped, the value is null. In PATCH requests, set it to null when switching a Campaign to uncapped. budgetAutomation.enabled
Whether Campaign-level budget automation is active. To enable budget automation, set this field to true and provide a valid budgetConfiguration. If omitted, it defaults to false. budgetAutomation.budgetConfiguration.adSetObjectives
The optimization objective used by budget automation. Can be conversions, revenue, visits, or videoViews. This field is required when budgetAutomation.enabled is true.

Create a campaign

A new campaign can be created for a specific advertiser by making a POST call to the Campaign’s endpoint.
The request body should specify the type (Campaign) and the campaign attributes.

Spend LimitIf spendLimitType is capped, both spendLimitRenewal and spendLimitAmount are required. If spendLimitType is uncapped, omit spendLimitRenewal and spendLimitAmount from the request. The response returns spendLimitRenewal as undefined and spendLimitAmount as null.

GoalThe field goal is mandatory and can be either Acquisition or Retention.

Budget AutomationbudgetAutomation is optional. To create a Campaign with budget automation enabled, set enabled to true and provide budgetConfiguration.adSetObjectives. If budgetAutomation is omitted, the Campaign is created with budget automation disabled.

Request sample

JSON

{
  "data": {
    "type": "Campaign",
    "attributes": {
      "name": "My Campaign",
      "advertiserId": "12345",
      "goal": "Retention",
      "spendLimit": {
        "spendLimitType": "capped",
        "spendLimitRenewal": "daily",
        "spendLimitAmount": 123.45
      },
      "budgetAutomation": {
        "enabled": true,
        "budgetConfiguration": {
          "adSetObjectives": "conversions"
        }
      }
    }
  }
}

Response sample The API will return an array of ID, the type (Campaign) and the Campaign attributes of the new Campaign.

{
  "data": {
    "id": "99999",
    "type": "Campaign",
    "attributes": {
      "name": "My Campaign",
      "advertiserId": "12345",
      "spendLimit": {
        "spendLimitType": "capped",
        "spendLimitRenewal": "daily",
        "spendLimitAmount": 123.45
      },
      "budgetAutomation": {
        "enabled": true,
        "budgetConfiguration": {
          "adSetObjectives": "conversions"
        }
      },
      "goal": "Retention"
    }
  },
  "warnings": [],
  "errors": []
}

Searching Campaigns

Retrieving Campaigns by Filtering

Campaigns can be retrieved by specifying filters to apply to the set of all campaigns in your portfolio. Using filters, you can restrict the returned results to particular advertiserIds or specific campaignIds. Filters can be combined. For example, to retrieve the Campaigns in your portfolio related to a particular advertiser, filter by advertiserIds: Sample request

JSON

{
  "filters": {
    "advertiserIds": ["12345"]
  }
}

Sample response The API will return an array of Campaigns that match the provided filters:

JSON

{
  "data": [
    {
      "type": "Campaign",
      "id": "99999",
      "attributes": {
        "name": "My Campaign",
        "advertiserId": "12345",
        "goal": "Retention",
        "spendLimit": {
          "spendLimitType": "capped",
          "spendLimitRenewal": "daily",
          "spendLimitAmount": 123.45
        },
        "budgetAutomation": {
          "enabled": true,
          "automatedBudgetConfiguration": {
            "adSetOptimizationObjective": "conversions"
          }
        }
      }
    }
  ],
  "errors": []
}

Retrieving All Campaigns

When no filters are specified in the JSON payload, all campaigns in your portfolio will be returned, as in the example below:

{
  "filters": {}
}

Retrieving One Specific Campaign

You can also fetch the details for a single Campaign using a GET request: Sample response The response data will be a single object containing the Campaign details.

JSON

{
  "data": {
    "type": "Campaign",
    "id": "99999",
    "attributes": {
      "name": "My Campaign",
      "advertiserId": "12345",
      "goal": "Retention",
      "spendLimit": {
        "spendLimitType": "capped",
        "spendLimitRenewal": "daily",
        "spendLimitAmount": 123.45
      },
      "budgetAutomation": {
        "enabled": true,
        "automatedBudgetConfiguration": {
          "adSetOptimizationObjective": "conversions"
        }
      }
    }
  },
  "errors": []
}

Update Campaigns

The fields of one or more Campaigns can be updated by making a PATCH call to the Campaigns endpoint. The payload should be an array of partial or whole Campaigns, each specifying the fields to be modified. For example, the following call would update the spendLimit settings of an existing Campaign: Sample request

JSON

{
  "data": [
    {
      "type": "Campaign",
      "id": "99999",
      "attributes": {
        "spendLimit": {
          "spendLimitType": "capped",
          "spendLimitRenewal": "daily",
          "spendLimitAmount": 123.45
        },
        "budgetAutomation": {
          "enabled": true,
          "budgetConfiguration": {
            "adSetObjectives": "conversions"
          }
        }
      }
    }
  ]
}

Sample response The API will return an array of Campaigns that have been updated successfully in the response data.
These will contain only two parameters, type and id.

JSON

{
  "data": [
    {
      "type": "Campaign",
      "id": "99999"
    }
  ],
  "errors": [],
  "warnings": []
}

Partial Success / Partial Failure

Each Campaign update is processed individually and can succeed or fail without impacting other updates in the same payload. As a result, those Campaign updates processed successfully will be returned in the data array of the response, while Campaign updates that have failed will return as an entry in the errors array of the response.

HTTP Response CodesAs a result of this individual processing, the API may respond with a 200 HTTP response code, but the result of its processing may have one or more failures.

For instance, for this payload which intends to update two Campaigns: Sample request

JSON

{
  "data": [
    {
      "type": "Campaign",
      "id": "99999",
      "attributes": {
        "spendLimit": {
          "spendLimitRenewal": "daily",
          "spendLimitType": "capped",
          "spendLimitAmount": 123.5
        }
      }
    },
    {
      "type": "Campaign",
      "id": "88888",
      "attributes": {
        "spendLimit": {
          "spendLimitRenewal": "daily",
          "spendLimitType": "capped",
          "spendLimitAmount": -9000
        }
      }
    }
  ]
}

Sample response

JSON

{
  "data": [
    {
      "type": "Campaign",
      "id": "99999"
    }
  ],
  "errors": [
    {
      "traceIdentifier": "56ed4096-f96a-4944-8881-05468efe0ec8",
      "type": "validation",
      "code": "campaign--campaign-update-check--validation-failed-on-spend-limit",
      "instance": "@data/1",
      "title": "Validation failed on spend limit",
      "detail": "There was an issue with the spend limit value specified."
    }
  ],
  "warnings": []
}

Error instanceThe instance field for validation errors will specify the index of the related update, beginning with index 0. For the example above, @data/1 refers to the second requested update in the request’s data array.

A full list of error codes can be found on the Validation Errors page at the end of this section.
In addition to general API errors , you may encounter validation errors when updating a Campaign. Below is a list of error codes for Campaign validation and a more detailed description of their meaning.

Validation Errors and Warnings

Campaign Update Errors:
campaign--campaign-update-check--spend-limit-does-not-exist
An update to spend limit was attempted on a Campaign which does not have a spend limit (e.g. an uncapped Campaign). Alternatively, the requestor may not have permissions to update the spend limit of the Campaign. campaign--campaign-update-check--cannot-decrease-lifetime-spend-limit-below-what-is-already-spent
An update attempted to decrease a lifetime spend limit of a Campaign to a value lower than what has already been spent. campaign--campaign-update-check--validation-failed-on-spend-limit
TK campaign--campaign-update-check--cannot-update-same-campaign-multiple-times
The Campaign is included multiple times in the same update payload. All Campaign field updates should be consolidated into one array item. campaign--campaign-update-check--unavailable-feature-for-this-advertiser
TK Campaign Update Warnings:
campaign--campaign-update-check--new-spend-limit-amount-will-take-place-at-the-next-period-start
The update to spend limit was processed, but it will not take effect until the next period specified by spendLimitRenewal (e.g. the next day). This is typically because the new spend amount specified is lower than the amount already spent in the current period.

Introduction

Marketing Solutions Endpoints

Campaign Example

Campaign Attributes

Create a campaign

Searching Campaigns

Retrieving Campaigns by Filtering

Retrieving All Campaigns

Retrieving One Specific Campaign

Update Campaigns

Partial Success / Partial Failure

Validation Errors and Warnings

What’s next

​Campaign Example

​Campaign Attributes

​Create a campaign

​Searching Campaigns

​Retrieving Campaigns by Filtering

​Retrieving All Campaigns

​Retrieving One Specific Campaign

​Update Campaigns

​Partial Success / Partial Failure

​Validation Errors and Warnings

​What’s next

Campaign Example

Campaign Attributes

Create a campaign

Searching Campaigns

Retrieving Campaigns by Filtering

Retrieving All Campaigns

Retrieving One Specific Campaign

Update Campaigns

Partial Success / Partial Failure

Validation Errors and Warnings

What’s next