Knowledge base

Understanding Advertising Management API


The Unity Advertising Management API allows advertisers to programmatically manage advertising campaigns through a RESTful API. The API currently offers endpoints to:

API Documentation

The Advertising Management API documentation includes all available API endpoints, and previews upcoming new API endpoints.

In addition, it includes:

  • An overview of the different resources in the API and how they relate to each other.
  • How to locate resource IDs used in API calls (for example, organizationId, campaignSetId, campaignId).
  • Authentication methods used in the API calls, and how to select roles and permissions.
  • Applicable rate limiting.
  • Response compression.
  • Guidance about how to use the APIs.
  • A glossary.

Configuring the API Management page

To authenticate your API requests, you need to:

  1. Create a Service Account
  2. Add Service Account Credentials to your API requests

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


Creating a service account

How to create a new 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.


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.


API Overview

Managing bids and source bids

Managing bids and source bids for installs campaign types

To programmatically manage bids and source bids for installs campaign types, use these APIs.

All iOS campaigns are now billed by Cost per Impression (CPM). In this billing method, you are charged based on the total number of impressions your campaign receives. You can learn more about this billing type here.

Bids are now Target CPI (tCPI) bids, the average amount you wish to pay per install. Target CPI is a bidding strategy that sets bids to help you get as many installs (conversions) as possible within a tight range of the target cost-per-install you set.

This strategy automatically optimizes bidding for your ad each time it is eligible to appear. Use APIs to set target CPI (tCPI) bids. The goal is to optimize your campaign to maximize installs.

Managing bids and source bids for ROAS and Retention

Manage bids on the campaign types with the following new APIs:

List ROAS eligibility Return eligible countries that can be used in the ROAS campaigns; along with country specific suggestions like suggestedIapGoal and suggestedAdRevenueGoal
List ROAS bids View applied D7 ROAS Goal & Max Bid per country for a ROAS campaign.
Update ROAS bids Update campaign's bids with a new set of values. Note: Bids can be set only for eligible countries.
List retention eligibility Return eligible countries that can be used in the Retention campaigns.
List retention bids View applied Base Bid & Max Bid per country for a Retention campaign.
Update retention bids Update campaign's bids with a new set of values. Note: Bids can be set only for eligible countries

Note: Bids can be set only for eligible countries

For more information, see the API doc

Managing budgets with APIs

Programmatically manage campaign budgets with these APIs.

Update Budget API endpoint 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 to unassign the current budget of a campaign.
Get Assigned Budget API endpoint to return 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 with APIs

Manage your creative packs and creatives, such as videos and end cards, with these APIs.

  • Upload creative assets with the Create Creative endpoint, only available for video and end card assets - square, landscape and portrait images and videos.
  • Build creative packs and assign or unassign creative packs from campaigns among others.

For more information aboutthe Unity Ads API

See the Unity Services API doc.

Still need help? Get in touch!
Last updated on 18th Jan 2022