Knowledge base

Understanding Advertising Management API

The Unity Advertising Management API allows advertisers to programmatically manage advertising campaigns through a RESTful API. In this article, we discuss how to:

API Documentation

While this article is an overview, our Advertising Management API documentation includes all available API endpoints. In addition, this API documentation also includes:

Continue reading this article for an overview of Advertising Management API or go to our API documentation site for more detailed instructions on how to use the API.

Configuring API Management

To be able to access the API and to create service accounts, your organization needs to have access granted to the Advertising Management API. Please contact your Unity Client Partner or email us at unityads-support@unity3d.com.

Once you have access to Advertising Management API, authenticate your API requests by:

  1. Creating a Service Account.
  2. Adding Service Account credentials to your API requests.

Note: You must be an Organization owner to manage service accounts and access your API keys.

GrowthScreen

Creating a service account

How to create a new service account

To obtain the required API access keys, first create a service account:

  1. To obtain the required API access keys, first create a service account:
  2. Go to Growth > User Acquisition > API Management.
  3. Click Service Account.
  4. From the Service Accounts panel, click Create service account.
  5. Add a service account name, a service account description, then click Create.

The new service account will appear in the list of service accounts.

GrowthScreen

How to create an API key

Note: You must be an Organization owner to manage service accounts and access your API keys.

  1. From the Service Accounts page, select an existing account.
  2. Click the three dot menu, then choose Edit.
  3. Navigate to the Access section. Set the roles you need to Enabled to allow access to the corresponding API endpoints. To understand the roles, see the details in the API doc.

Note: Unity recommends using the Advertise API Admin role if you do not wish to edit your service account to allow access to new API endpoints in the future.

  1. In the Keys section, click Create new key to generate a Key ID and a Secret key.
  2. When the key is created, copy the Key ID and the Secret key to a safe place, such as a text file for future reference because you won't be able to view them again.

GrowthScreen

API endpoints overview

Managing apps and campaigns

Advertisers may programmatically add an app or create and configure campaigns via a RESTful API. For more information, view our API documentation to manage apps or campaigns.

Managing apps

Manage apps with the following API endpoints:

Add a new iOS/Android app API endpoint to add a new iOS/Android app with a store URL.
Get app API endpoint used to return app information for a given app ID.
List apps API endpoint to return all available apps.

Managing campaigns

Manage campaigns with the following API endpoints:

List campaigns API endpoint returns campaigns for the given app.
Create campaign API endpoint used to create a campaign.
Get campaign API endpoint returns the campaign information for a given campaign ID.
Get targeting options API endpoints returns the targeting options for a certain campaign.
Update campaign API endpoint used to update a campaign.
Delete campaign API endpoint used to delete a campaign.

App Targeting

Advertisers may target (allowlist) or block (blocklist) a specific list of apps or devices on a campaign. Manage app targeting with the following API endpoints:

Allow or block apps on a campaign API endpoint to target (allowlist) or block (blocklist) a specific list of source app IDs. Use the Update targeting options endpoint and specify the appTargeting body schema.

Device Targeting

Advertisers may refine targeted devices on a campaign. Manage device targeting with the following API endpoints:

Target devices by operating system API endpoint to select targeted devices per operating system. Use the Update targeting options endpoint and specify the deviceTargeting body schema.
Target devices by LAT setting API endpoint to select targeted devices per LAT setting. API endpoint to select targeted devices per operating system. Use the Update targeting options endpoint and specify the deviceTargeting body schema.
Target device by iOS device model. API endpoints to select targeted devices by iOS device model. API endpoint to select targeted devices per operating system. Use the Update targeting options endpoint and specify the deviceTargeting body schema.

Managing bids and source bids

Managing bids and source bids for installs campaign types

Manage CPI and source bids for install campaigns with the following API endpoints:

List CPI bids API endpoint returns campaign’s CPI bids.
Update CPI bids API endpoint replaces a campaign’s CPI bids with a new set of bids.
List source bids API endpoint returns a campaign’s source bids.
Update source bids API endpoint used to replace a campaign’s source bids with a new set of source bids.

Managing bids and source bids for ROAS and Retention campaigns

Manage bids on Return on Ad Spend (ROAS) and Retention campaign types with the following API endpoints:

List ROAS campaign eligibility API endpoint returns information about which countries are currently eligible to be used in the Return on Ad Spend (ROAS) campaigns and additional ROAS-related information.
List ROAS campaign bids API endpoint returns ROAS campaign bids.
Update ROAS campaign bids API endpoint used to replace ROAS campaign bids with a new set of ROAS bids. Note that ROAS bids can be set only for eligible countries.
List Retention campaign eligibility API endpoint returns information about which countries are currently available to be used in Retention campaigns.
List Retention campaign bids API endpoint returns Retention campaign bids.
Update Retention campaign bids API endpoint used to replace Retention campaign bids with a new set of bids.

Managing budgets

Programmatically manage campaign budgets with the following API endpoints.

List budgets API endpoint lists campaign budgets for a single app.
Create budget API endpoint used to create a campaign budget.
Get budget API endpoint returns the campaign budget information for a given budget ID.
Update budget API endpoint used to update campaign budget.
Assign budget API endpoint used to assign a budget to a campaign. This endpoint can also be used for changing a previously assigned budget to another budget.
Unassign budget API endpoint used to unassign the current budget of a campaign.
Get assigned budget API endpoint used to return the budget assigned to a given campaign.

Notes about budgets

  • The Campaign budget dictates how much marketing spend your campaigns could consume.
  • A budget has an overall limit for the marketing spend of a campaign. This can also have a daily cap.
  • A budget is first created and then assigned to the desired campaigns. If a budget is assigned to multiple campaigns then all of those campaigns consume that same budget.
  • By default a campaign does not have a budget assigned to it, meaning that by default a campaign has an unlimited budget.

Managing creatives and creative packs

Managing creatives

Manage creatives with the following API endpoints.

List creatives API endpoint returns all available creatives that are under the given app.
Create creatives API endpoint for uploading an end card or video creative.
Get creatives API endpoint returns a creative by the creative ID and campaign set ID.

Managing creative packs

Manage creative packs with the following API endpoints.

List creative packs API endpoint returns creative packs under the given app.
Create creative pack API endpoint to create a video, playable, or video and playable creative pack.
Get creative pack API endpoint returns a creative pack by the creative pack ID and campaign set ID.
Delete creative pack API endpoint removes a creative pack by the creative pack ID and campaign set ID.
Still need help? Get in touch!
Last updated on 16th May 2022