Unity Advertising Management API

Introduction

The Management API is a streamlined solution designed to automate and optimize your acquire advertising operations. It offers dynamic apps & campaign management, budget allocation and creative management through robust API endpoints. This translates into a reduced manual workload and an increase in dynamic, data-driven decision-making capabilities.

With Management API you can:

Automate bulk campaign & app creation and adjustments
Seamlessly adjust budget allocations for your campaigns
Efficiently manage and assign your creatives and creative packs

How to use this documentation?

The Get Started guide will help you set up the Service account and start using the API
The Basic Concepts section will provide you with general information about the Management API, including API structure, versioning, and deprecation policy
The Endpoints section has all the information about actual API endpoints and error handling

If you have any questions or feedback regarding the API you can reach out to us at unityads-support@unity3d.com.

Get Started

Prerequisites: You have the Unity account.

To get started, you will first need to create a service account and assign suitable roles for it. Note that you must be an Organization Owner to manage service accounts.

How to Gain Access?

Note: 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.

Set up a service account

You can find information on how to create a service account here.

After the service account has been created, you will need to authenticate an API and choose the roles that would be assigned to it.

Authentication & Authorization

To learn how to authenticate your requests, please visit the Admin API authentication page

Roles and Permissions

The service account must have the relevant access to be able to call the APIs. Please see below for the available service account roles and their corresponding access rights:

Role	Access Rights
Advertise API Admin	Grants full read and write access.
Advertise API Viewer	Grants access to all the read endpoints.
Advertise API Apps Editor	Grants access to all the read and update endpoints for apps.
Advertise API Campaigns Editor	Grants access to all the read and update endpoints for campaigns.
Advertise API Bids Editor	Grants access to all the read and update endpoints for all the bid types.
Advertise API Creative Packs Editor	Grants access to all the read and update endpoints for creatives, creative packs and assigned creative packs.
Advertise API Targeting Editor	Grants access to all the read and update endpoints for targeting options.

You can learn more about the roles available for Management API on the Admin API authentication page under Growth section.

First Call: List Apps

Learn how to send your first API request with Management API. Before we start, please make sure that you have set up a Service Account with necessary roles. The first call we will perform is List Apps

GET

request. To be able to perform this request, the service account needs to have one of the following roles:

Advertise API Viewer
Advertise API Apps Editor
Advertiser API Admin

In this guide, we are going to be using the

curl

command line tool in the Unix terminal.

Follow these steps:

Step 1

The key ID and secret key that you should have gotten as part of the service account setup should be Base64 encoded before authenticating an API with the Unix terminal. Assuming you have key ID

7e0f1152-e0dd-4b14-8e37-04cab07efeb0

and secret key

NKxoRp2m2w3e9gzJfssNQnTfypFgtJn7

, the following command will Base64 encode the key string:


echo -n "7e0f1152-e0dd-4b14-8e37-04cab07efeb0:NKxoRp2m2w3e9gzJfssNQnTfypFgtJn7" | base64

In the output you should get a string that looks like this:

N2UwZjExNTItZTBkZC00YjE0LThlMzctMDRjYWIwN2VmZWIwOk5LeG9ScDJtMnczZTlnekpmc3NOUW5UZnlwRmd0Sm43

Step 2

Get the organization ID following the guide in the Resource IDs section. You should end up with an ID that looks like this:

5772562874846

Step 3

Construct the API call URL. For the List Apps endpoint, it has the following format:

https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps

. If we use the organization ID from the previous step, the full URL is going to be

https://services.api.unity.com/advertise/v1/organizations/5772562874846/apps

Step 4

Let's put all the pieces together and construct the

curl

command that will perform the List Apps request:


curl -H "Authorization: Basic N2UwZjExNTItZTBkZC00YjE0LThlMzctMDRjYWIwN2VmZWIwOk5LeG9ScDJtMnczZTlnekpmc3NOUW5UZnlwRmd0Sm43" \ https://services.api.unity.com/advertise/v1/organizations/5772562874846/apps

If your organization has multiple apps, you can consider limiting the number of returned apps to make it easier to check the result. It can be done by adding the

limit

query parameter:


curl -H "Authorization: Basic N2UwZjExNTItZTBkZC00YjE0LThlMzctMDRjYWIwN2VmZWIwOk5LeG9ScDJtMnczZTlnekpmc3NOUW5UZnlwRmd0Sm43" \ https://services.api.unity.com/advertise/v1/organizations/5772562874846/apps?limit=1

Step 5

Check the

curl

output. If your organization does not have any apps, the result will look like this:


{"total":0,"offset":0,"limit":1000,"results":[]}

If your organization has apps, the result will contain a list of apps:


{"total":10,"offset":0,"limit":1,"results":[{"id":"651bffb0c4466ba162a56531","name":"My awesome game","store":"apple","storeId":"1358236","gameId":500269499,"adomain":null,"createdAt":"2023-10-03T11:49:04.953Z","updatedAt":"2023-10-03T11:49:04.953Z"}]}

Step 6

Congratulations! You’re ready to manage your apps and campaigns with the Management API.

Feel free to let us know what you think of this guide: unityads-support@unity3d.com.

Basic Concepts

Overview

The guides in this series provide an overview of the entities, methods and endpoints available in the Management API. After reading these guides, you will understand the following key concepts:

How the Management API is structured
How Management API versioning works
Which API endpoints to use to retrieve entities
Which API endpoints to use to modify entities
How to structure and sequence API calls

The API endpoints are hosted at the following base URL: https://services.api.unity.com.

Glossary

This section provides a more detailed explanation of the vocabulary used in the API.

Apps and Campaigns

Entity	Description
App	App that is published in an app store and contains a set of campaigns. Apps are identified by campaignSetId.
Campaign	Campaign holds the details of your advertisement campaign such as which bids to set and which ad assets to use.

Bid Types

Entity	Description
CPI Bid	CPI (cost per install) bids are used for targeting and pricing on a per-country basis within your ad campaign.
Source Bid	Source bids are used for granularly targeting and pricing apps (sources) on a per-country basis within your ad campaign.
ROAS Bid	ROAS (Return On Ad Spend) bids are dynamically priced bids that are used for targeting users that are predicted to generate revenue through in-app purchases or watching ads.
Retention Bid	Retention bids are dynamically priced bids that are used for targeting users that are likely to remain in your game 7 days after install.

Creative Packs and Creatives

Entity	Description
Creative	Creative holds either one or two ad assets (files). More information about creative types can be found in the Creative Types section.
Creative Pack	A creative pack combines 1-3 creatives into one entity that can be assigned to one or more campaigns. More information about creative pack types can be found in the Creative Pack Types section.

Creative Types

Creative Type	Description
End Card Creative	End cards are creative assets displayed at the end of a video with a call to action for users to download the advertised product. It can be either a single square image or combination of portrait and landscape images.
Playable Creative	Playable ads allow users to play a quick interactive demo of your game.
Video Creative	Video creative is a video that is used for marketing your app.

Creative Pack Types

Creative Pack Type	Description
Video and static end card	A video ad with an image-type end card. Consists of 1 or 2 Video creatives (portrait/landscape) and one End Card creative.
Playable	A playable is an interactive ad. Includes only Playable creative.
Video and playable end card	A video ad with an interactive-type end card. Consists of 1 or 2 Video creatives (portrait/landscape) and one Playable creative.

Entity Relationships

This section provides an overview on what the different resources in the API are and how they relate to each other.

At the top level, the API has a resource that is called

App

. The

App

resource corresponds to a single app/game that has been published in a single app store. If you have published your app/game in more than one app store then you will have a separate

App

resource for each of those stores. Note that it is also possible to have more than one

App

resources that correspond to the same app/game in a store. The following diagram visualizes this relationship for a game called

My Game

Apps contain advertisement campaigns and resources related to those campaigns such as budgets, bids and creatives:

Resource IDs Used in the API Calls

To identify your organization as well as its apps and campaigns we use the following identifiers:

organizationId: identifies your organization
campaignSetId: identifies your app (collection of campaigns) within your organization
campaignId: identifies a single advertising campaign within your app

How to Look Up organizationId

To look up the

organizationId

, please use the following steps:

Open the Acquire Dashboard
Select Settings from the navigation.
On the settings page, you will see two separate Organization ID fields. For the Advertising Management API, pick the value from the
```
Organization Core ID
```
field.

Note: The organizations are identified with two separate identifiers due to legacy reasons. The full name of the organization identifier used in the Advertising Management API is

Organization Core ID

but due to practical reasons it has been shortened to be

organizationId

in this API documentation.

How to Look Up campaignSetId and campaignId

To look up the

campaignSetId

and

campaignId

, the following options are available:

Apps and their respective campaignSetIds can be retrieved using the List Apps endpoint. In the API response, the

id

-field holds the campaignSetId. Likewise, campaigns and their respective campaignIds can be retrieved using the List Campaigns endpoint.

The campaignSetId and campaignId identifiers are also available via the Advertising Statistics API where you can find them under the columns

app id

and

campaign id

, respectively.

It is also possible to find all the identifiers from the URLs of the Unity Acquire dashboard. First, open the dashboard and then click Apps and choose an app and a campaign to view. After that the IDs are visible in the URL in following spots:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID>/acquire/campaign-sets/<CAMPAIGN_SET_ID>/campaigns/<CAMPAIGN_ID>

Versioning

Our API endpoints are versioned and typically structured in the following format:


<BASE_URL>/<VERSION>/<API_NAMESPACE>/<...>

where

<VERSION>

is the version number of the API (example: v1).

The API may receive non-breaking changes without its version number being changed. Breaking changes are introduced only to new API versions.

The current API version is v1. For all API updates, view our API changelog.

Breaking/Non-breaking Changes Explained

Non-breaking changes can include (but are not limited to) for example:

Adding new optional request headers
Adding new fields to the response
Adding new status codes to the response status codes list
Changing a required field to be optional
Changes to rate limits
Under-the-hood fixes that don’t change the URL signature, the request format or the response format

Breaking changes can include (but are not limited to) for example:

Changing the URL signature
Removing a field from the response
Adding a new required field to the request
Removing endpoints
Behavioral changes in filters or options
Request format alterations for endpoints

Deprecation Policy

If a newer version of the API is released or if the service is discontinued, the API or one of its versions may be deprecated and eventually shutdown.

Deprecation of an API version will occur in 2 steps:

Unity's client partner or support team will email Organization owners, informing them of the new version's imminent release and the current version's deprecation date. A deprecation notice will appear on the HTTP headers of any deprecated API, and the documentation will be updated as such.
After 3 months of continued support for a deprecated version, Unity may cease support or shut down the version entirely. A complete shutdown notice will be sent 1 month in advance.

Feature Release Lifecycle

The Management API is designed to mirror the feature lifecycle stages — Closed Beta, Open Beta, and General Availability (GA) — ensuring a seamless user experience. If you have access to a feature in the Closed Beta phase within the platform, you can expect parallel API-level access. This congruency extends through the Open Beta and onto GA, offering a consistent interface for interactions and functionality. In essence, API capabilities evolve in tandem with the feature's lifecycle for a unified workflow.

If you find that a feature you have access to isn't available on the Management API, please reach out to your Client Partner or contact our support team for assistance at unityads-support@unity3d.com.

Rate Limits

The API has rate limiting in place. The maximum number of requests per IP address is limited to 10 to 20 requests per second and to 4000 requests per 30 minutes.

Additionally, all operations that modify resources (

PUT

PATCH

DELETE

) are limited so that it is possible to modify a single resource per endpoint at most 100 times per 30 minutes or at most once per a second. This means that for example the CPI bids of a single campaign can be updated at most 30 times inside a 30-minute time interval. The endpoints don't share the quota, so it is possible to do also other updates (e.g. source bids) to that same campaign during that same time interval.

Similarly, operations that create resources (

POST

) are limited so that it is possible to create at most 30 new resources per endpoint under a single app or campaign per 30 minutes or at most once per a second. This means that it is possible to for example upload at most 30 creatives into a single app within a 30-minute interval. During that same time window it is possible to also create other resources or apply updates to the campaigns that are under the app. Each endpoint has its own quota.

If you need to update multiple campaigns fast, you can do that. It is for example possible to update CPI bids of hundreds of campaigns within a short time interval, as long as the number of requests stays in the overall bounds of max 6 to 10 requests per second and max 4000 requests per 30 minutes.

The API responds with

HTTP status code if the rate limit is exceeded.

Quick Reference

What is limited	How many requests are allowed per second	How many requests are allowed per 30 minutes	Notes
Apps endpoints	20	4000	Takes all requests into account.
Bids endpoints	10	4000	Takes all requests into account.
Campaigns endpoints	20	4000	Takes all requests into account.
Creatives endpoints	20	4000	Takes all requests into account.
Creative-Packs endpoints	20	4000	Takes all requests into account.
`PUT` , `PATCH` , `DELETE`	1	100	Applied per `Campaign` , `Creative` or `Creative Pack` for each endpoint separately.
`POST`	1	30	Applied per `App` endpoint for those resources that are directly under the `App` such as `Campaigns` . If the resource in question is under `Campaign` , such as `Creative Pack Assignment` then the limit is applied per `Campaign` endpoint.

RateLimit HTTP Headers

Every successful response includes

RateLimit HTTP headers

, providing essential information about the maximum limit per endpoint and the remaining quota. For example, utilizing the "Unity-RateLimit" header assists in calculating the average number of requests per second. You can read more about the RateLimit HTTP headers here.

Response Compression

The API supports response compression. The responses are compressed if either

Accept-Encoding: gzip

Accept-Encoding: deflate

header is provided in the request.

Example:


curl -H "Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS>" -H "Accept-Encoding: gzip" https://services.api.unity.com/advertise/v1/organizations/5772680389521/apps/5ee23a52c10f9455722a5ead/campaigns/5ee23a557de7e87ee0958dfc/source-bids

Change Log

This changelog lists all additions and updates to the Management API, in chronological order.

January 10, 2025

Added support for Update Creative Pack endpoint.
Added support for
```
appleProductPageId
```
-field and
```
androidStoreListing
```
-field in the Creative Packs endpoints.

January 10, 2024

Added pagination support for List Creatives endpoint.

January 2, 2024

Added support for updating partial bids in the Bids endpoints.

December 14, 2023

Added support for requesting additional campaign data in get campaign endpoint.

October 16, 2023

Added support for regional targeting in retrieving a campaign targeting options and updating a campaign targeting options.

October 02, 2023

Added support for category targeting in retrieving a campaign targeting options and updating a campaign targeting options.

September 21, 2023

Added support for screen density in retrieving a campaign targeting options and updating a campaign targeting options.

September 20, 2023

Added support for screen size in retrieving a campaign targeting options and updating a campaign targeting options.
Added support for connection type in retrieving a campaign targeting options and updating a campaign targeting options.

September 19, 2023

Added support to filter Campaign by status in the list Campaigns endpoint by
```
enabled
```
.

August 07, 2023

Added support for Creative Testing campaign in the Bids endpoints.

April 13, 2023

Added support for Creative Testing campaign in the Campaigns endpoints.

March 8, 2023

Updated the Rate Limits policy.

February 15, 2023

Added support for
```
gameId
```
-field to the response body of create App and get App and list Apps endpoints.

February 1, 2023

Added support for three decimal bids in the Bids endpoints.

January 17, 2023

Removed deprecated shared budgets endpoints. Please use campaign budget endpoints instead.

January 14, 2023

Added support for setting unlimited campaign budget for campaigns with manual biddingStrategy by supporting 0 in update campaign budget endpoint.

December 14, 2022

Added support for three decimal bids in the Bids endpoints for the Closed Beta participants.

November 24, 2022

Added support for
```
postInstallWindow
```
-field to the request body of create Campaign endpoint.

September 19, 2022

Added support for
```
biddingStrategy
```
-field to the request body of create Campaign endpoint.

September 5, 2022

Added new endpoints for getting and updating a campaign budget.

August 31, 2022

Added
```
biddingStrategy
```
-field to the response body of get Campaign and list Campaigns endpoints.

July 27, 2022

Added
```
billingType
```
-field to the request body of create campaign endpoint.

May 12, 2022

Added support for deleting an app.

May 6, 2022

Added support for updating an app.

May 3, 2022

Added
```
adomain
```
-field to the request body of create App endpoint.

April 19, 2022

Added
```
adomain
```
-field to the responses of get App and list Apps endpoints.

January 28, 2022

Added support for retrieving a campaign targeting options.

January 26, 2022

Added support for updating targeting options.

December 16, 2021

Increased the default rate limit to 6 requests per second.

December 10, 2021

Added support for retrieving a campaign Budget.

December 2, 2021

Added support to filter Apps in the list Apps endpoint by
```
store
```
and
```
storeId
```
.

November 29, 2021

Added support for retrieving an app.

November 25, 2021

Added support for creating apps.

November 15, 2021

Make the
```
storeId
```
field nullable in the App listing endpoint.

October 14, 2021

Added support for creating playable creatives.

October 11, 2021

Fixed some error messages for enabled campaigns that were referring to them as "live" campaigns.

October 1, 2021

Added support for updating a campaign.

September 28, 2021

Added support for deleting a campaign.

September 21, 2021

Added support for campaign creation.

September 10, 2021

Added support for retrieving a Campaign.

September 6, 2021

Fixed an issue that caused the update Campaign Budget endpoint to have too strict rate limit.

September 1, 2021

Changed the list Campaigns endpoint to include

enabled, attributionClickUrl, attributionStartUrl, scheduleStart, scheduleEnd

fields.

August 23, 2021

Added pagination support for list Creative Packs endpoint.

August 13, 2021

Added support for create Campaign Budget endpoint.

July 27, 2021

Added support for Video and Playable creative pack type in the create creative pack endpoint.

July 26, 2021

Added support for listing Retention information.

July 22, 2021

Added support for replace Retention bids.

July 20, 2021

Added support for listing Retention bids.

July 19, 2021

Added
```
storeId
```
-field to the responses of list Apps endpoint.

July 14, 2021

Added support for listing ROAS information.

July 7, 2021

Changed the list Campaigns endpoint to include the ROAS types field for ROAS campaigns.

July 7, 2021

Added support to filter creative packs in the list Creative Packs endpoint by name.

July 2, 2021

Added
```
campaignIds
```
-field to the responses of get Creative Pack and list Creative Packs endpoints.

July 1, 2021

Added support for replace ROAS (Return On Ad Spend) bids.

June 30, 2021

Changed the list CPI bids and list source bids endpoints to return a 404 error if the campaign type is not Installs.

June 23, 2021

Changed support contact address to unityads-support@unity3d.com.

June 17, 2021

Added support for listing ROAS (Return On Ad Spend) bids.

May 20, 2021

Added support for updating a Campaign Budget.

May 14, 2021

Added support for assigning a Campaign Budget.

May 7, 2021

Added support for unassigning a Campaign Budget.

May 6, 2021

Added support for retrieving Assigned Budget.

May 3, 2021

Added support for listing Campaign Budgets.

April 28, 2021

Added support for listing Apps.

April 19, 2021

Added billingType field to list campaigns endpoint.

April 8, 2021

Unity Advertising Management API version 1 (beta) released.

February 17, 2021

First draft of the version 1 of the Unity Advertising Management API.

Guides

This section contains guides on how to use the API.

Uploading and Assigning Creatives

Creatives and creative packs are the content of your ad campaigns. This article covers the following steps:

Overview
Step 1: Upload Your Creatives
Step 2: Create a Creative Pack
Step 3: Assign a Creative Pack to a Campaign

Overview

The ad assets (files) such as videos, playables and end cards are managed using two concepts called

Creatives

and

Creative Packs

. Creatives directly hold your creative files while creative packs combine 1-3 creatives into a pack that can be assigned to one or more campaigns.

The process for creating and assigning creative packs to campaigns is as follows:

Step 1: Upload Your Creatives

You can upload your creatives by using the Create Creative endpoint.

The following creative assets can be uploaded currently through the API:

Square end card: this creative type contains a single square shaped 800 × 800 image.
End card pair: this creative type contains a 600 × 800 portrait image and a 800 × 600 landscape image.
Portrait video: this creative type contains a 9:16 portrait video.
Landscape video: this creative type contains a 16:9 landscape video.
Playable: this creative type contains an MRAID 2.0 compliant HTML document in a landscape, portrait or responsive orientation. Refer to the Creative packs documentation.

Usually you call the

Create Creative

endpoint once for each file you wish to upload. The only exception to this is the end card pair creative which includes both portrait and landscape images in one creative.

Upload a Video

Below is an example how the upload endpoint can be called using the command line command

curl

. To try it out, replace the

/path/to/your/file/myPortraitVideo.mp4

with your local video file path and replace

<ORGANIZATION_ID>

<SERVICE_ACCOUNT_CREDENTIALS>

and

<CAMPAIGN_SET_ID>

with values matching your organization and app.


curl --verbose \ --form 'creativeInfo={"name": "My Portrait Video", "language": "en", "video": {"fileName":"myPortraitVideo.mp4"}}' \ --form "videoFile=@/path/to/your/file/myPortraitVideo.mp4" \ --header "Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS>" \ https://services.api.unity.com/advertise/v1/organizations/<ORGANIZATION_ID>/apps/<CAMPAIGN_SET_ID>/creatives

After the upload has completed successfully, you will receive a HTTP

response with a response payload such as below:


  {"id": "5fd363cf5d84aa0ed76956b1","name": "My Portrait Video","language": "en","type": "portraitVideo","createdAt": "2020-12-11T12:19:29.004Z","status": "uploaded"  }

Upload a Square End Card

Uploading a square end card works in similar fashion as uploading videos but you'll need to adjust the request in the following way:

Adjust the
```
creativeInfo
```
to contain a
```
squareEndCard
```
field instead of a
```
video
```
field.
Instead of passing the file in a
```
videoFile
```
field, pass the file in a field called
```
squareEndCardFile
```
.

Example:


curl --verbose \ --form 'creativeInfo={"name":"My End Card", "language":"en", "squareEndCard": {"fileName":"mySquareEndCard.jpeg"}}' \ --form "squareEndCardFile=@/path/to/your/file/mySquareEndCard.jpeg" \ --header "Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS>" \ https://services.api.unity.com/advertise/v1/organizations/<ORGANIZATION_ID>/apps/<CAMPAIGN_SET_ID>/creatives

Upload an End Card Pair

Uploading an end card pair works in similar fashion as uploading videos and square end card but you'll need to include both end card files in the request:


curl --verbose \   --form 'creativeInfo={"name":"My End Card Pair", "language":"en", "portraitEndCard": {"fileName":"myPortraitEndCard.jpeg" }, "landscapeEndCard": {"fileName":"myLandscapeEndCard.jpeg"}}' \   --form "portraitEndCardFile=@/path/to/your/file/600x800.jpeg" \   --form "landscapeEndCardFile=@/path/to/your/file/800x600.jpeg" \   --header "Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS>" \   https://services.api.unity.com/advertise/v1/organizations/<ORGANIZATION_ID>/apps/<CAMPAIGN_SET_ID>/creatives

Creative Status

After having been uploaded, all new creatives undergo a content moderation process to ensure that they follow Unity's advertising content policy. Before entering the moderation queue, the video creatives go through a processing state that can take few minutes.

You can check the latest status of the uploaded creative with Get Creative endpoint.

Creatives can be added into a creative pack immediately after they have been uploaded. It isn't necessary to wait for the moderation to complete. However, a creative pack can go live only after all its creatives have passed the moderation.

Step 2: Create a Creative Pack

After you've uploaded your creatives, you can use Create Creative Pack endpoint to create a creative pack out of them. A creative pack combines 1-3 creatives into one entity that can be assigned to one or more campaigns.

The following creative combinations are allowed when creating a creative pack through the API:

Portrait video + end card
Landscape video + end card
Portrait video + landscape video + end card
Responsive playable
Portrait playable
Landscape playable
Portrait playable + landscape playable

While only one video or playable is required, uploading one for each orientation yields better optimization. When a creative pack contains both, Unity’s valuation algorithm selects the best orientation to display.

Below is an example that creates a creative pack that contains one portrait video (with ID

5fd363cf5d84aa0ed76956b1

) and one square end card (with ID

5feb40a6ff3d91a3af53c678


curl --verbose \ --request POST \ --data '{"name": "Portrait video with square end card", "creativeIds": ["5fd363cf5d84aa0ed76956b1", "5feb40a6ff3d91a3af53c678"], "type": "video"}' \ --header "Content-Type: application/json" \ --header "Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS>" \ https://services.api.unity.com/advertise/v1/organizations/<ORGANIZATION_ID>/apps/<CAMPAIGN_SET_ID>/creative-packs

Replace the

creativeIds

<ORGANIZATION_ID>

<CAMPAIGN_SET_ID>

and

<SERVICE_ACCOUNT_CREDENTIALS>

with values that match your app and organization.

For a successful request, the response HTTP status code is

and the response body follows following format:


{  "id": "5feb4574ff3d91a3af53c67e",  "name": "Video with end card",  "type": "video",  "creativeIds": [  "5fd363cf5d84aa0ed76956b1",  "5feb40a6ff3d91a3af53c678"  ]}

Step 3: Assign a Creative Pack to a Campaign

To assign a creative pack to your campaign, use the assign Creative Pack endpoint.

If your creative pack's ID is for example

5f15703772f10b00138f6d8d

, you can assign it to your campaign with a POST request:


curl --verbose \ --request POST \ --data '{"id": "5f15703772f10b00138f6d8d"}' \ --header "Content-Type: application/json" \ --header "Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS>" \ https://services.api.unity.com/advertise/v1/organizations/<ORGANIZATION_ID>/apps/<CAMPAIGN_SET_ID>/campaigns/<CAMPAIGN_ID>/assigned-creative-packs

The currently assigned creative packs can be listed with a GET query:


curl --header "Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS>" \ https://services.api.unity.com/advertise/v1/organizations/<ORGANIZATION_ID>/apps/<CAMPAIGN_SET_ID>/campaigns/<CAMPAIGN_ID>/assigned-creative-packs

The response contains a list of creative pack IDs.

A campaign must contain at least one approved creative pack in order to go live. If your live campaign includes a mix of approved and pending creative packs, the pending ones will automatically run when approved.

To unassign a creative pack from a campaign, use the unassign Creative Pack endpoint.

You can unassign a creative pack with a DELETE query that includes the creative pack's ID in the URL:


curl --verbose \ --request DELETE \ --header "Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS>" \ https://services.api.unity.com/advertise/v1/organizations/<ORGANIZATION_ID>/apps/<CAMPAIGN_SET_ID>/campaigns/<CAMPAIGN_ID>/assigned-creative-packs/<ASSIGNED_CREATIVE_PACK_ID>

Download OpenAPI specification:

Get App

This endpoint returns the app information for a given app ID.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "Get App"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

HTTP response status codes for "Get App":

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Get App":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}"

Response example

{ "id": "5eb26a338a232100e4bb5893", "name": "My Game", "store": "apple", "storeId": "com.companyname.appname", "adomain": "example.com", "gameId": 500000007, "createdAt": "2020-07-20T18:30:51.243Z", "updatedAt": "2020-08-25T11:55:20.651Z", "appAttributionClickUrl": "https://example.com/{ifa}", "appAttributionStartUrl": "https://example.com/{ifa}"}

Update App

This endpoint is used to update an App.

Note: this endpoint supports partial updates.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "Update App"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

Request body for "Update App"

Media Type:

application/json

adomain

string

example: example.com

The advertiser domain of the app.

An advertiser domain is the organization's identifying URL and can be the company or app's homepage.

appAttributionClickUrl

string

example: https://example.com/{ifa}

Fired when the player clicks the download button.

appAttributionStartUrl

string

example: https://example.com/{ifa}

Fired when players start viewing the video.

appLevelAttributionUpdateType

string

The app level attribution update type.

HTTP response status codes for "Update App":

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Update App":

Request example

curl -X PATCH \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ -H "Content-Type: application/json" \ -d '{ "adomain": "example.com", "appAttributionClickUrl": "https://example.com/{ifa}", "appAttributionStartUrl": "https://example.com/{ifa}", "appLevelAttributionUpdateType": "newAudiences"}' \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}"

Response example

Delete App

This endpoint is used to delete an App.

Note: all campaigns, bids and creative packs belonging to the app will also be deleted. Deleted apps cannot be recovered.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "Delete App"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

HTTP response status codes for "Delete App":

No Content

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Delete App":

Request example

curl -X DELETE \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}"

Response example

{ "title": "Bad Request", "status": 400, "detail": "Something is wrong", "details": [ { "code": "ERROR_CODE_123", "path": "nested.value", "message": "Invalid value" } ], "requestId": "aad109f8-033f-4a24-8b77-5032eb3a6158"}

List Apps

This endpoint returns all available apps

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "List Apps"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

Query parameters for "List Apps"

offset

The offset indicates how many entities to skip before retrieving entities.

offset=0

is the same as omitting the offset clause. If both

offset

and

limit

are present, then

offset

entities are skipped before starting to count the

limit

entities that are returned.

limit

Amount of entities to return.

filter

object

List of filters in the format

filter[key]=value&filter[key2]=value2

. Currently we only support filtering by the store and storeId with

filter[storeId]=com.store.id&filter[store]=google

HTTP response status codes for "List Apps":

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "List Apps":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps"

Response example

{ "total": 1, "offset": 0, "limit": 1000, "results": [ { "id": "5eb26a338a232100e4bb5893", "name": "My Game", "store": "apple", "storeId": "com.companyname.appname", "adomain": "example.com", "gameId": 500000007, "createdAt": "2020-07-20T18:30:51.243Z", "updatedAt": "2020-08-25T11:55:20.651Z", "appAttributionClickUrl": "https://example.com/{ifa}", "appAttributionStartUrl": "https://example.com/{ifa}" } ]}

Create App

This endpoint creates a new app

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "Create App"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

Request body for "Create App"

Media Type:

application/json

store

string

required

No description

storeId

string

required

example: 1234567

The app's App Store ID.

adomain

string

example: example.com

The advertiser domain of the app.

An advertiser domain is the organization's identifying URL and can be the company or app's homepage.

appAttributionClickUrl

string

example: https://example.com/{ifa}

Fired when the player clicks the download button.

appAttributionStartUrl

string

example: https://example.com/{ifa}

Fired when players start viewing the video.

HTTP response status codes for "Create App":

Created

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Create App":

Request example

curl -X POST \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ -H "Content-Type: application/json" \ -d '{ "store": "apple", "storeId": "1234567", "adomain": "example.com", "appAttributionClickUrl": "https://example.com/{ifa}", "appAttributionStartUrl": "https://example.com/{ifa}"}' \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps"

Response example

List Creatives

This endpoint returns all available creatives that are under the given app.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "List Creatives"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

Query parameters for "List Creatives"

offset

The offset indicates how many entities to skip before retrieving entities.

offset=0

is the same as omitting the offset clause. If both

offset

and

limit

are present, then

offset

entities are skipped before starting to count the

limit

entities that are returned.

limit

Amount of entities to return.

HTTP response status codes for "List Creatives":

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "List Creatives":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/creatives"

Response example

{ "total": 1, "offset": 0, "limit": 2000, "results": [ { "id": "5eb26a338a232100e4cc9945", "name": "My Creative", "language": "en", "type": "landscapeVideo", "files": [ { "name": "string", "url": "https://example.com/directory/image.jpg" } ], "createdAt": "2020-07-20T18:30:51.243Z", "status": "approved" } ]}

Create Creative

Upload an end card or video creative using this endpoint.

Three different types of creatives can currently be created through this API:

Square end card: a single square shaped 800 × 800 image.
End card pair: a 600 × 800 portrait image and a 800 × 600 landscape image.
Video: contains either a 9:16 portrait video or a 16:9 landscape video.
Playable: contains an MRAID 2.0 compliant HTML document in a portrait, landscape or responsive orientation. Refer to the Creative packs documentation.

Each creative type requires a slightly different JSON payload and a different set of binary files:

one image file for a square end card,
two image files for an end card pair,
one video file for a video creative.
one HTML file for a playable creative.

To create a creative, you will need to send a HTTP request with content type of

multipart/form-data

to the API endpoint. The first part of the multipart form should contain a field named

creativeInfo

that contains JSON metadata about the creative, followed by one or more additional parts containing the binary data for each creative file.

Example

For a square end card the raw HTTP request could look for example following:


POST /advertise/v1/organizations/<ORGANIZATION_ID>/apps/<CAMPAIGN_SET_ID>/creatives HTTP/1.1Host: services.api.unity.com:443Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS>Content-Type: multipart/form-data; boundary=--------------------------371131627955007232942795Content-Length: 51165----------------------------371131627955007232942795Content-Disposition: form-data; name="creativeInfo"Content-Type: application/json{  "name": "My Creative",  "language": "en",  "squareEndCard": {    "fileName": "myCreative.jpeg"  }}----------------------------371131627955007232942795Content-Disposition: form-data; name="squareEndCardFile"; filename="myCreative.jpeg"<IMAGE_BINARY_DATA>----------------------------371131627955007232942795--

Notice that the place holders

<ORGANIZATION_ID>

<CAMPAIGN_SET_ID>

<SERVICE_ACCOUNT_CREDENTIALS>

and

<IMAGE_BINARY_DATA>

need to be replaced with valid values.

When uploading creative assets, ensure that you follow Unity’s advertising content policy.

A continuous data flow is expected when uploading the file. The creative upload is allowed to take at most 5 minutes. This means that if you are creating a creative that contains a video that has the maximum file size of 100 MB then your average upload speed must at least 2.7 Mbps. If the upload takes longer than 5 minutes then the request will fail. If the upload halts (no bytes are transferred) for over 30 seconds then the request will fail.

If the same files have already been uploaded as part of a previous creative, the existing creative is returned and no new one is created.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "Create Creative"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

Request body for "Create Creative"

Media Type:

multipart/form-data

creativeInfo

object

required

Field that contains creative metadata in JSON format.

name

string

required

example: My Creative

Creative name.

type

This field is deprecated. Given value is omitted.

language

string

required

example: en

What language is the creative in? The accepted values are a subset of the IANA language subtag registry. Note the two special values:

zxx

for No linguistic content and

und

for Undetermined.

Collecting creative language information will help improve Unity's machine learning algorithms, further enabling you to find the right players at scale.

squareEndCard

object

required

Creative file metadata

fileName

string

required

example: GameXVideoFile.mp4

Name of the creative file. The name could be for example mySquareEndCard.jpeg for an end card or my_horizontal_video.mp4 for a video creative.

squareEndCardFile

string

required

The file that contains the square end card image.

The image dimensions must be 800 × 800. The file format must be either PNG, JPEG or GIF. The maximum file size is 5MB.

creativeInfo

object

required

Field that contains creative metadata in JSON format.

name

string

required

example: My Creative

Creative name.

type

string

This field is deprecated. Given value is omitted.

language

string

required

example: en

What language is the creative in? The accepted values are a subset of the IANA language subtag registry. Note the two special values:

zxx

for No linguistic content and

und

for Undetermined.

Collecting creative language information will help improve Unity's machine learning algorithms, further enabling you to find the right players at scale.

portraitEndCard

object

required

Creative file metadata

fileName

string

required

example: GameXVideoFile.mp4

Name of the creative file. The name could be for example mySquareEndCard.jpeg for an end card or my_horizontal_video.mp4 for a video creative.

landscapeEndCard

object

required

Creative file metadata

fileName

string

required

example: GameXVideoFile.mp4

Name of the creative file. The name could be for example mySquareEndCard.jpeg for an end card or my_horizontal_video.mp4 for a video creative.

portraitEndCardFile

string

required

The file that contains the portrait end card image.

The image dimensions must be 600 × 800. The file format must be either PNG, JPEG or GIF. The maximum file size is 5MB.

Dynamic cropping may occur for portrait and landscape end cards to account for different device sizes. To avoid losing critical information, allow a buffer from the image borders.

landscapeEndCardFile

string

required

The file that contains the landscape end card image.

The image dimensions must be 800 × 600. The file format must be either PNG, JPEG or GIF. The maximum file size is 5MB.

Dynamic cropping may occur for portrait and landscape end cards to account for different device sizes. To avoid losing critical information, allow a buffer from the image borders.

creativeInfo

object

required

Field that contains creative metadata in JSON format.

name

string

required

example: My Creative

Creative name.

type

string

This field is deprecated. Given value is omitted.

language

string

required

example: en

What language is the creative in? The accepted values are a subset of the IANA language subtag registry. Note the two special values:

zxx

for No linguistic content and

und

for Undetermined.

Collecting creative language information will help improve Unity's machine learning algorithms, further enabling you to find the right players at scale.

video

object

required

Creative file metadata

fileName

string

required

example: GameXVideoFile.mp4

Name of the creative file. The name could be for example mySquareEndCard.jpeg for an end card or my_horizontal_video.mp4 for a video creative.

videoFile

string

required

File that contains the video ad asset.

The video should be 30 seconds or less and in H.264-encoded MP4 format. The recommended file size is 10MB, and the maximum file size is 100MB. The video can be either in portrait format with 9:16 aspect ratio or in landscape format with 16:9 aspect ratio.

creativeInfo

object

required

Field that contains creative metadata in JSON format.

name

string

required

example: My Creative

Creative name.

language

string

required

example: en

What language is the creative in? The accepted values are a subset of the IANA language subtag registry. Note the two special values:

zxx

for No linguistic content and

und

for Undetermined.

Collecting creative language information will help improve Unity's machine learning algorithms, further enabling you to find the right players at scale.

playable

object

required

Playable creative file metadata

fileName

string

required

example: GameXVideoFile.mp4

Name of the creative file. The name could be for example mySquareEndCard.jpeg for an end card or my_horizontal_video.mp4 for a video creative.

orientation

string

required

example: both

Creative's Orientation

playableFile

string

required

File that contains the playable ad asset.

The maximum file size is 5MB.

HTTP response status codes for "Create Creative":

Created

Bad Request

Unauthorized

Forbidden

Not Found

Payload Too Large

Too Many Requests

Internal Server Error

Service Unavailable

Gateway Timeout

Code samples for "Create Creative":

Request example

curl -X POST \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ -H "Content-Type: multipart/form-data" \ -d '{"creativeInfo":{"name":"My Creative","type":null,"language":"en","squareEndCard":{"fileName":"GameXVideoFile.mp4"}},"squareEndCardFile":"string"}' \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/creatives"

Response example

{ "id": "5eb26a338a232100e4cc9945", "name": "My Creative", "language": "en", "type": "landscapeVideo", "files": [ { "name": "string", "url": "https://example.com/directory/image.jpg" } ], "createdAt": "2020-07-20T18:30:51.243Z", "status": "approved"}

Get Creative

This endpoint returns a creative by the creative ID and campaign set ID.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "Get Creative"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

creativeId

required

ID of the creative

HTTP response status codes for "Get Creative":

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Get Creative":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/creatives/{creativeId}"

Response example

List Creative Packs

This endpoint returns creative packs that are under the given app.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "List Creative Packs"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

Query parameters for "List Creative Packs"

offset

The offset indicates how many entities to skip before retrieving entities.

offset=0

is the same as omitting the offset clause. If both

offset

and

limit

are present, then

offset

entities are skipped before starting to count the

limit

entities that are returned.

limit

Amount of entities to return.

filter

object

List of filters in the format

filter[key]=value&filter[key2]=value2

. Currently we only support filtering by the creative pack name with

filter[name]=*name*filter*

HTTP response status codes for "List Creative Packs":

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "List Creative Packs":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/creative-packs"

Response example

{ "total": 1, "offset": 0, "limit": 700, "results": [ { "id": "5eb26a338a232100e4cc9945", "name": "My Creative Pack", "creativeIds": [ "5eb26a338a232100e4cc9945" ], "type": "video", "campaignIds": [ "5eb26a338a232100e4bb6361" ], "androidStoreListing": null, "appleProductPageId": "db126c25-8179-4d3b-8e86-73b5e02db18f" } ]}

Create Creative Pack

Create a creative pack using this endpoint.

Three different types of creative packs can be currently created through this API:

video: this creative pack type contains a single end card creative (square end card or end card pair) and one or two video creatives (one end card + 1-2 videos).
playable: this creative pack type contains one or two playable creatives.
video and playable: this creative pack type contains one or two video creatives and a single responsive playable.

Each creative pack type requires different

creativeIds

which have to match with the given creative pack type. If the creatives referenced by the

creativeIds

do not match with the creative pack's

type

then the API will respond with

bad request.

Available creatives for your app can be listed via list Creatives endpoint.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "Create Creative Pack"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

Request body for "Create Creative Pack"

Media Type:

application/json

name

string

required

example: My Creative Pack

Creative pack name.

creativeIds

array[string]

required

Array of creative IDs.

type

string

required

No description

androidStoreListing

string

example: null

Only available for Google application.

appleProductPageId

string

example: db126c25-8179-4d3b-8e86-73b5e02db18f

Only available for Apple application.

HTTP response status codes for "Create Creative Pack":

Created

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Create Creative Pack":

Request example

curl -X POST \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ -H "Content-Type: application/json" \ -d '{ "name": "My Creative Pack", "creativeIds": [ "5eb26a338a232100e4cc9945" ], "type": "video", "androidStoreListing": null, "appleProductPageId": "db126c25-8179-4d3b-8e86-73b5e02db18f"}' \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/creative-packs"

Response example

{ "id": "5eb26a338a232100e4cc9945", "name": "My Creative Pack", "creativeIds": [ "5eb26a338a232100e4cc9945" ], "type": "video", "campaignIds": [ "5eb26a338a232100e4bb6361" ], "androidStoreListing": null, "appleProductPageId": "db126c25-8179-4d3b-8e86-73b5e02db18f"}

Get Creative Pack

This endpoint returns a creative pack by the creative pack ID and campaign set ID.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "Get Creative Pack"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

creativePackId

required

ID of the creative pack

HTTP response status codes for "Get Creative Pack":

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Get Creative Pack":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/creative-packs/{creativePackId}"

Response example

Update Creative Pack

This endpoint is used to update a creative pack.

Note: The

campaignIds

in the response is always empty.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "Update Creative Pack"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

creativePackId

required

ID of the creative pack

Request body for "Update Creative Pack"

Media Type:

application/json

name

string

example: My Creative Pack

Creative pack name.

androidStoreListing

string

example: null

Only available for Google application.

appleProductPageId

string

example: db126c25-8179-4d3b-8e86-73b5e02db18f

Only available for Apple application.

HTTP response status codes for "Update Creative Pack":

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Update Creative Pack":

Request example

curl -X PATCH \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ -H "Content-Type: application/json" \ -d '{ "name": "My Creative Pack", "androidStoreListing": null, "appleProductPageId": "db126c25-8179-4d3b-8e86-73b5e02db18f"}' \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/creative-packs/{creativePackId}"

Response example

Delete Creative Pack

This endpoint removes a creative pack by the creative pack ID and campaign set ID.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "Delete Creative Pack"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

creativePackId

required

ID of the creative pack

HTTP response status codes for "Delete Creative Pack":

No Content

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Delete Creative Pack":

Request example

curl -X DELETE \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/creative-packs/{creativePackId}"

Response example

List Campaigns

This endpoint returns campaigns for the given app.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "List Campaigns"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

Query parameters for "List Campaigns"

filter

object

List of filters in the format

filter[key]=value&filter[key2]=value2

. Currently we only support filtering by the campaign status with

filter[enabled]=true

HTTP response status codes for "List Campaigns":

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "List Campaigns":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/campaigns"

Response example

{ "total": 1, "results": [ { "id": "5eb26a338a232100e4bb6361", "name": "CPI campaign for My Game", "goal": "installs", "billingType": "cpi", "enabled": true, "attributionClickUrl": "https://example.com/{ifa}", "attributionStartUrl": "https://example.com/{ifa}", "scheduleStart": "2020-08-25", "scheduleEnd": "2020-11-02", "createdAt": "2020-07-20T18:30:51.243Z", "updatedAt": "2020-08-25T11:55:20.651Z", "biddingStrategy": "manual", "cpiBids": [ { "country": "US", "bid": "0.201" } ], "sourceBids": [ { "country": "US", "sourceAppId": "0a1b2c3D4E5f", "bid": "0.201" } ], "retentionBids": [ { "country": "US", "baseBid": "0.755", "maxBid": "0.255" } ], "eventOptimizationBids": [ { "country": "US", "bid": "0.755" } ], "eventOptimizationType": "level_complete", "sdkEventName": "level_complete_1", "budget": { "total": "2500.20", "dailySpent": "1800.32", "spent": "1800.32" } } ]}

Create Campaign

This endpoint is used to create a campaign.

In order to complete the campaign setup, take the following steps:

You can Upload Creatives or use the old ones if you already have uploaded them.
You can Create Creative Pack or use any approved creative pack you already have.
You should Assign Creative Pack to the campaign.
Depending on the
```
goal
```
of your campaign you need to update CPI/ROAS/Retention bids by calling the right Bids endpoint.
Finally if you prepared all requirements you can change the
```
enabled
```
status by calling the Update Campaign endpoint.

Note: The campaign must have the below prerequisites to go live:

At least one assigned and approved creative pack.
Tracking attribution links.
Specify countries you would like to advertise in.
The organization is required to have a budget and also, you can optionally update the campaign-level budget.

Note: If null values are passed for the links (

attributionClickUrl

attributionStartUrl

), and the app that campaign belongs to has one or many app-level attribution urls set, a modified campaign would automatically get the app-level attribution url values.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "Create Campaign"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

Request body for "Create Campaign"

Media Type:

application/json

goal

name

string

required

example: CPI campaign for My Game

Campaign's name.

goal

string

required

example: installs

Campaign's goal. Available options:

installs: cost per install - campaign is optimized for getting the most installs possible with your target cost.
roas: return on ad spend - campaign is optimized for finding users who are predicted to bring your target return on ad spend during the first 7 days in your app.
retention: campaign is optimized for finding users who are likely to remain in your app for 7 days or more after installing.
creativeTesting: campaign is for testing and comparing the creative performance.
eventOptimization: campaign is optimized for finding users who are likely to perform a specific in-app event.

billingType

string

example: cpi

Indicates the type of the campaign billing. Possible options:

cpi: cost per install, you will be billed based on each install your app receives. This is only available where we receive non-aggregated postback data.
cpm: cost per impression, you will be billed based on each impression the app receives. It supports aggregated postback data for campaigns.

biddingStrategy

string

example: manual

Type of campaign bidding strategy. Possible options:

manual: Control your target cost by setting country-level static CPI bids. We recommend this if you want to maintain an average CPI.
automated: Let us automatically determine the best possible bids for maximizing the amount of installs with your daily budget. We recommend this if you want to use a daily budget below $500 or save time from manually adjusting bids to optimise performance.

Note: Automated bidding strategy is only available for campaigns using CPM billing type.

attributionClickUrl

string

example: https://example.com/{ifa}

Fired when the player clicks the download button.

attributionStartUrl

string

example: https://example.com/{ifa}

Fired when players start viewing the video.

scheduleStart

string

example: 2020-08-25

UTC date describing the start date of the campaign.

scheduleEnd

string

example: 2020-11-02

UTC date describing the end date of the campaign.

HTTP response status codes for "Create Campaign":

Created

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Create Campaign":

Request example

curl -X POST \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ -H "Content-Type: application/json" \ -d '{ "name": "CPI campaign for My Game", "goal": "installs", "billingType": "cpi", "biddingStrategy": "manual", "attributionClickUrl": "https://example.com/{ifa}", "attributionStartUrl": "https://example.com/{ifa}", "scheduleStart": "2020-08-25", "scheduleEnd": "2020-11-02"}' \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/campaigns"

Response example

{ "id": "5eb26a338a232100e4bb6361", "name": "CPI campaign for My Game", "goal": "installs", "billingType": "cpi", "enabled": true, "attributionClickUrl": "https://example.com/{ifa}", "attributionStartUrl": "https://example.com/{ifa}", "scheduleStart": "2020-08-25", "scheduleEnd": "2020-11-02", "createdAt": "2020-07-20T18:30:51.243Z", "updatedAt": "2020-08-25T11:55:20.651Z", "biddingStrategy": "manual", "cpiBids": [ { "country": "US", "bid": "0.201" } ], "sourceBids": [ { "country": "US", "sourceAppId": "0a1b2c3D4E5f", "bid": "0.201" } ], "retentionBids": [ { "country": "US", "baseBid": "0.755", "maxBid": "0.255" } ], "eventOptimizationBids": [ { "country": "US", "bid": "0.755" } ], "eventOptimizationType": "level_complete", "sdkEventName": "level_complete_1", "budget": { "total": "2500.20", "dailySpent": "1800.32", "spent": "1800.32" }}

Get Campaign

This endpoint returns the campaign information for a given campaign id.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "Get Campaign"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

campaignId

required

ID of the campaign

Query parameters for "Get Campaign"

includeFields

List of extra fields to be included in the response in the format

includeFields=cpiBids&includeFields=budget

includeFields

parameter tells to extend campaign response with specified values. If the campaign type does not match the requested field, i.e. campaign is CPI and roasBids are requested, the query parameter is ignored.

HTTP response status codes for "Get Campaign":

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Get Campaign":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/campaigns/{campaignId}"

Response example

Update Campaign

This endpoint is used to update a campaign.

Note: this endpoint supports partial updates. The payload can contain, for example, only a new value for the

enabled

field.

Note: If null values are passed for the links (

attributionClickUrl

attributionStartUrl

), and the app that campaign belongs to has one or many app-level attribution urls set, a modified campaign would automatically get the app-level attribution url values.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "Update Campaign"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

campaignId

required

ID of the campaign

Request body for "Update Campaign"

Media Type:

application/json

name

string

example: CPI campaign for My Game

Campaign's name.

enabled

boolean

example: true

Indicates the status of the campaign.

attributionClickUrl

string

example: https://example.com/{ifa}

Fired when the player clicks the download button.

attributionStartUrl

string

example: https://example.com/{ifa}

Fired when players start viewing the video.

scheduleStart

string

example: 2020-08-25

UTC date describing the start date of the campaign.

scheduleEnd

string

example: 2020-11-02

UTC date describing the end date of the campaign.

autoStart

string

example: disabled

Indicates the campaign's auto start status. Possible options:

enabled: The campaign will be enabled automatically when all the assigned creative packs are approved.
disabled: The campaign will not be enabled automatically.

Note: Auto start is only available when campaign's goal is creativeTesting. Auto start will be automatically disabled if you remove the campaign's attribution click url, change assigned creative packs, remove all the bids or enable the campaign.

HTTP response status codes for "Update Campaign":

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Update Campaign":

Request example

curl -X PATCH \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ -H "Content-Type: application/json" \ -d '{ "name": "CPI campaign for My Game", "enabled": true, "attributionClickUrl": "https://example.com/{ifa}", "attributionStartUrl": "https://example.com/{ifa}", "scheduleStart": "2020-08-25", "scheduleEnd": "2020-11-02", "autoStart": "disabled"}' \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/campaigns/{campaignId}"

Response example

Delete Campaign

This endpoint is used to delete a campaign.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "Delete Campaign"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

campaignId

required

ID of the campaign

HTTP response status codes for "Delete Campaign":

No Content

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Delete Campaign":

Request example

curl -X DELETE \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/campaigns/{campaignId}"

Response example

List Assigned Creative Packs

This endpoint returns creative packs that are assigned to a campaign.

Note: you can also use the list Creative Packs endpoint to check which creative packs are currently assigned to which campaigns.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "List Assigned Creative Packs"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

campaignId

required

ID of the campaign

HTTP response status codes for "List Assigned Creative Packs":

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "List Assigned Creative Packs":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/campaigns/{campaignId}/assigned-creative-packs"

Response example

{ "total": 1, "results": [ { "id": "5eb26a338a232100e4cc9945" } ]}

Assign Creative Pack

Assign a creative pack to a campaign.

Note about iOS Campaigns

Please note that there is a limit of 50 creative pack assignments in apps sharing the same store id that you can use on your live campaigns for iOS apps. You can find more information about this limit here.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "Assign Creative Pack"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

campaignId

required

ID of the campaign

Request body for "Assign Creative Pack"

Media Type:

application/json

id

string

required

example: 5eb26a338a232100e4cc9945

Unique identifier of the creative pack.

HTTP response status codes for "Assign Creative Pack":

Created

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Assign Creative Pack":

Request example

curl -X POST \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ -H "Content-Type: application/json" \ -d '{ "id": "5eb26a338a232100e4cc9945"}' \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/campaigns/{campaignId}/assigned-creative-packs"

Response example

{ "id": "5eb26a338a232100e4cc9945"}

Unassign Creative Pack

Unassign a creative pack from a campaign.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "Unassign Creative Pack"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

campaignId

required

ID of the campaign

assignedCreativePackId

required

ID of the assigned creative pack

HTTP response status codes for "Unassign Creative Pack":

No Content

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Unassign Creative Pack":

Request example

curl -X DELETE \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/campaigns/{campaignId}/assigned-creative-packs/{assignedCreativePackId}"

Response example

List CPI Bids

This endpoint returns the campaign’s CPI bids; including bids for static bidding CPI campaigns and max bids for automated bidding CPI campaigns.

Note about iOS Campaigns

CPI campaigns are now target CPI campaigns while your campaign optimization goals, such as Installs, ROAS or Retention, do not change.

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 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. Target CPI (tCPI) bids are set the same way as CPI bids via APIs.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "List CPI Bids"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

campaignId

required

ID of the campaign

HTTP response status codes for "List CPI Bids":

List of CPI bids

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "List CPI Bids":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/campaigns/{campaignId}/cpi-bids"

Response example

{ "total": 1, "results": [ { "country": "US", "bid": "0.201" } ]}

Update CPI Bids

This endpoint replaces a campaign’s CPI bids with a new set of bids. Applicable for bids update on static bidding CPI campaigns and max bid update for automated bidding CPI campaigns.

To remove all the CPI bids of a campaign, send an empty array in the request body.

Note about iOS Campaigns

CPI campaigns are now target CPI campaigns while your campaign optimization goals, such as Installs, ROAS or Retention, do not change.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "Update CPI Bids"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

campaignId

required

ID of the campaign

Request body for "Update CPI Bids"

Media Type:

application/json

Array Type:

Array of CPI bids.

[ { "country": "US", "bid": "0.201" }]

HTTP response status codes for "Update CPI Bids":

Successfully updated the CPI bids

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Update CPI Bids":

Request example

curl -X PUT \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ -H "Content-Type: application/json" \ -d '[ { "country": "US", "bid": "0.201" }]' \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/campaigns/{campaignId}/cpi-bids"

Response example

{ "total": 1, "results": [ { "country": "US", "bid": "0.201" } ]}

Update Partial CPI Bids

This endpoint partially updates a campaign’s CPI bids with the specified bid changes. Applicable for bids update on static bidding CPI campaigns and max bid update for automated bidding CPI campaigns.

To remove a specific CPI bid, send the country code with a null bid value in the request body.

Note about iOS Campaigns

CPI campaigns are now target CPI campaigns while your campaign optimization goals, such as Installs, ROAS or Retention, do not change.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "Update Partial CPI Bids"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

campaignId

required

ID of the campaign

Request body for "Update Partial CPI Bids"

Media Type:

application/json

Array Type:

Array of CPI bids.

[ { "country": "US", "bid": "0.201" }]

HTTP response status codes for "Update Partial CPI Bids":

Successfully updated the CPI bids

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Update Partial CPI Bids":

Request example

curl -X PATCH \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ -H "Content-Type: application/json" \ -d '[ { "country": "US", "bid": "0.201" }]' \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/campaigns/{campaignId}/cpi-bids"

Response example

{ "total": 1, "results": [ { "country": "US", "bid": "0.201" } ]}

List Source Bids

This endpoint returns a campaign's source bids.

Note about iOS Campaigns

CPI campaigns are now target CPI campaigns while your campaign optimization goals, such as Installs, ROAS or Retention, do not change.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "List Source Bids"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

campaignId

required

ID of the campaign

HTTP response status codes for "List Source Bids":

List of source bids

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "List Source Bids":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/campaigns/{campaignId}/source-bids"

Response example

{ "total": 1, "results": [ { "country": "US", "sourceAppId": "0a1b2c3D4E5f", "bid": "0.201" } ]}

Update Source Bids

This endpoint is used to replace a campaign's source bids with a new set of source bids.

To remove all source bids of a campaign, send an empty array in the request body.

Note about iOS Campaigns

CPI campaigns are now target CPI campaigns while your campaign optimization goals, such as Installs, ROAS or Retention, do not change.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "Update Source Bids"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

campaignId

required

ID of the campaign

Request body for "Update Source Bids"

Media Type:

application/json

Array Type:

Array of source bids.

[ { "country": "US", "sourceAppId": "0a1b2c3D4E5f", "bid": "0.201" }]

HTTP response status codes for "Update Source Bids":

Successfully updated the source bids

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Update Source Bids":

Request example

curl -X PUT \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ -H "Content-Type: application/json" \ -d '[ { "country": "US", "sourceAppId": "0a1b2c3D4E5f", "bid": "0.201" }]' \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/campaigns/{campaignId}/source-bids"

Response example

{ "total": 1, "results": [ { "country": "US", "sourceAppId": "0a1b2c3D4E5f", "bid": "0.201" } ]}

Update Partial Source Bids

This endpoint partially updates a campaign's source bids with the specified bid changes.

To remove a specific source bid, send the country code with a null bid value in the request body.

Note about iOS Campaigns

CPI campaigns are now target CPI campaigns while your campaign optimization goals, such as Installs, ROAS or Retention, do not change.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "Update Partial Source Bids"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

campaignId

required

ID of the campaign

Request body for "Update Partial Source Bids"

Media Type:

application/json

Array Type:

Array of source bids.

[ { "country": "US", "sourceAppId": "0a1b2c3D4E5f", "bid": "0.201" }]

HTTP response status codes for "Update Partial Source Bids":

Successfully updated the source bids

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Update Partial Source Bids":

Request example

curl -X PATCH \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ -H "Content-Type: application/json" \ -d '[ { "country": "US", "sourceAppId": "0a1b2c3D4E5f", "bid": "0.201" }]' \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/campaigns/{campaignId}/source-bids"

Response example

{ "total": 1, "results": [ { "country": "US", "sourceAppId": "0a1b2c3D4E5f", "bid": "0.201" } ]}

Get targeting options

This endpoint returns the targeting options for a certain campaign.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "Get targeting options"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

campaignId

required

ID of the campaign

HTTP response status codes for "Get targeting options":

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Get targeting options":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/campaigns/{campaignId}/targeting"

Response example

{ "appTargeting": { "allowList": [ "0a1b2c3D4E5f" ] }, "deviceTargeting": { "limitedAdTracking": [ "USERS_ALLOWING_AD_TRACKING" ], "osMin": "2.3", "osMax": "latest", "connectionType": [ "wifi" ], "screenSize": [ "small" ], "screenDensity": [ "ldpi" ] }, "categoryTargeting": { "allowList": [ "Unknown" ] }, "regionalTargeting": [ { "country": "AD", "subdivisions": [ 0 ] } ]}

Update targeting options

This endpoint is used to update targeting options.

Note: this endpoint supports partial updates. The payload can contain, for example, only a new value for the

appTargeting

option.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "Update targeting options"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

campaignId

required

ID of the campaign

Request body for "Update targeting options"

Media Type:

application/json

appTargeting

No description

deviceTargeting

No description

categoryTargeting

No description

regionalTargeting

array[object]

Use this option to target users based on their country and region. You can target users in one or more countries and regions.

Note: If no values are set, by default all the countries from bids are targeted.

HTTP response status codes for "Update targeting options":

targeting options

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Update targeting options":

Request example

curl -X PATCH \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ -H "Content-Type: application/json" \ -d '{ "appTargeting": { "allowList": [ "0a1b2c3D4E5f" ] }, "deviceTargeting": { "limitedAdTracking": [ "USERS_ALLOWING_AD_TRACKING" ], "osMin": "2.3", "osMax": "latest", "connectionType": [ "wifi" ], "screenSize": [ "small" ], "screenDensity": [ "ldpi" ] }, "categoryTargeting": { "allowList": [ "Unknown" ] }, "regionalTargeting": [ { "country": "AD", "subdivisions": [ 0 ] } ]}' \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/campaigns/{campaignId}/targeting"

Response example

Get Budget

This endpoint is used to get campaign budget for a certain campaign.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "Get Budget"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

campaignId

required

ID of the campaign

HTTP response status codes for "Get Budget":

Bad Request

Unauthorized

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Get Budget":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/advertise/v1/organizations/{organizationId}/apps/{campaignSetId}/campaigns/{campaignId}/budget"

Response example

{ "total": "2500.20", "dailySpent": "1800.32", "spent": "1800.32"}

Update Budget

This endpoint is used to update campaign budget.

Note: this endpoint supports partial updates. The payload can contain, for example, only a new value for the

total

option.

Authorizations

Authentication

HTTP: Authentication

HTTP Authorization Scheme: basic

Path parameters for "Update Budget"

organizationId

required

Core ID of the organization.

You can look up your Organization's ID by opening up the Acquire Dashboard and by looking up the ID from the browser's address bar:

https://dashboard.unity3d.com/organizations/<ORGANIZATION_ID_IS_HERE>/acquire/about

For more information about the IDs, refer to the Resource IDs documentation.

campaignSetId

required

Unique identifier for an App.

campaignId

required

ID of the campaign

Request body for "Update Budget"

Media Type:

application/json

total

No description

daily

No description

total

No description

dailyPerCountry

object

example: {"US":"123.45","FI":"9.00"}

A map with a country code mapped to the amount of money that can be spent daily for the country in dollars.

Unity recommends a minimum daily budget of $500 per country for CPI billed campaigns and $50 per country for CPM billed campaigns. Campaigns with less than the recommended daily cap per country might not get any exposure due to budget restrictions.

Having a low daily limit might result in overspending during the first few days, as the system might not be able to accurately predict the performance of your campaign.

The country daily limit is disabled when the single daily for all countries is set to

. Disabling the daily limit means that the spend is capped only by the budget's total limit.

If you are using country daily budgets and missing a daily budget for one or more countries which you have bids, Unity won't be delivering in these countries until a daily budget has been specified.

Each individual daily amount should be at least

$0.1

string

example: 2500.20