Campaign

Campaign Example

The following is an example of the JSON data structure of an Campaign.

Additional details about the individual attributes of Campaigns can be found below.

{
    "type": "Campaign",
    "id": "99999",
    
    "attributes": {
        "name": "My Campaign",
        "advertiserId": 12345,
        "goal": "Retention",
        "spendLimit": {
            "spendLimitRenewal": "daily",
            "spendLimitType": "capped",
            "spendLimitAmount": 123.45
        }
    }

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.spendLimitRenewal
The cadence of spend limit renewal. Can be daily, monthly, lifetime, or undefined in the case of an uncapped limit type.

spendLimit.spendLimitType
Whether the Campaign spend is capped or not. Can be capped or uncapped.

spendLimit.spendLimitAmount
A decimal value representing the spend limit for the Campaign. If spendLimitType is uncapped, the value will be null.

Create a campaign

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

📘

Spend Limit

spendLimitRenewal and spendLimitAmount are only relevant when spendLimitType is set to capped.

📘

Goal

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

/marketing-solutions/campaigns

{
  "data":
	{
    "type": "Campaign",
    "id": "99999",
     
    "attributes": {
        "name": "My Campaign",
        "advertiserId": 12345,
        "goal": "Retention",
        "spendLimit": {
            "spendLimitRenewal": "daily",
            "spendLimitType": "capped",
            "spendLimitAmount": 123.45
        }
   }
}

The API will return an array of the 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
      },
      "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:

/marketing-solutions/campaigns/search

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

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

{
    "data": [
        {
            "type": "Campaign",
            "id": "99999",
            "attributes": {
               "name": "My Campaign",
               "advertiserId": 12345,
               "goal": "Retention",
               "spendLimit": {
                    "spendLimitRenewal": "daily",
                    "spendLimitType": "capped",
                    "spendLimitAmount": 123.45
                }
            }
        }
    ],
    "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:

/marketing-solutions/campaigns/search

{
    "filters": {}
}

Retrieving One Specific Campaign

You can also fetch the details for a single Campaign using a GET request:

/marketing-solutions/campaigns/{campaignId}

The response data will be a single object containing the Campaign details.

{
    "data": {
        "type": "Campaign",
        "id": "99999",
        "attributes": { ... }
    },
    "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:

/marketing-solutions/campaigns

{
    "data": [
        {
            "type": "Campaign",
            "id": "99999",
            "attributes": {
                "spendLimit": {
                    "spendLimitRenewal": "daily",
                    "spendLimitType": "capped",
                    "spendLimitAmount": 123.45
                }
            }
        }
    ]
}

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.

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

As 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:

/marketing-solutions/campaigns

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

The response might look like:

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

The 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.