/* Title: Understanding Advertising Management API Sort: 10 */

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

• Access our Advertising Management API documentation
• Configure API management
• Create a service account
• Manage apps and campaigns
• Manage bids and source bids
• Manage budgets
• Manage creatives and creative packs

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

• How to get started with Advertising Management API.
• 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.
• 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.
• A change log.

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.

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 [email protected].

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.

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.

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.

4. In the Keys section, click Create new key to generate a Key ID and a Secret key.
5. 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.

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.

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.

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.

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.

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.

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.

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

[List ROAS campaign eligibility](https://services.docs.unity.com/advertise/v1/index.html#operation/advertise-listRoasInfo)	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](https://services.docs.unity.com/advertise/v1/index.html#operation/advertise-listRoasBids)	API endpoint returns ROAS campaign bids.
[Update ROAS campaign bids](https://services.docs.unity.com/advertise/v1/index.html#operation/advertise-replaceRoasBids)	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](https://services.docs.unity.com/advertise/v1/index.html#operation/advertise-listRetentionInfo)	API endpoint returns information about which countries are currently available to be used in Retention campaigns.
[List Retention campaign bids](https://services.docs.unity.com/advertise/v1/index.html#operation/advertise-listRetentionBids)	API endpoint returns Retention campaign bids.
[Update Retention campaign bids](https://services.docs.unity.com/advertise/v1/index.html#operation/advertise-replaceRetentionBids)	API endpoint used to replace Retention campaign bids with a new set of bids.

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.

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

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.

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.