Apple Search Ads
1
Campaign Management API 3.0
Apple Search Ads Campaign Management API 3.0
Apple Search Ads
March 2021
Apple Search Ads Campaign Management API 3.0 6 ......................................
Authenticating 6 ..........................................................................................
Account Management 7 ..............................................................................
API Functionality 9 ......................................................................................
Partial Updates 9 ....................................................................................
Pagination 10 ..........................................................................................
Selectors 10 ............................................................................................
Partial Fetch 12 .......................................................................................
Campaigns 13 ..................................................................................................
Create a Campaign 14 .................................................................................
Find Campaigns 15 ......................................................................................
Update a Campaign 16 ................................................................................
CampaignUpdate Object 17 ...................................................................
Get Campaigns 18 .......................................................................................
Delete Campaigns 18 ..................................................................................
Campaign Object 19 ....................................................................................
Budget Orders 23 ............................................................................................
Get All Budget Orders 23 ............................................................................
BudgetOrder Object 24 ...............................................................................
Get a Budget Order 26 ................................................................................
BudgetOrderResponse Object 27 ...............................................................
LOCInvoiceDetails 28 ..................................................................................
LOCInvoiceDetails Object 28 .................................................................
Money Object 29 .........................................................................................
Ad Groups 30 ...................................................................................................
Search Match 30 .........................................................................................
Create an Ad Group 31 ................................................................................
Apple Search Ads
2
Campaign Management API 3.0
Find Ad Groups 32 ......................................................................................
Get Ad Groups 34 .......................................................................................
Update an Ad Group 34 ..............................................................................
Delete Ad Groups 35 ...................................................................................
Ad Group Object 35 ....................................................................................
Targeting Dimensions 37 .............................................................................
Keywords 42 ....................................................................................................
Keyword Object 42 ......................................................................................
Negative Keywords Object 44 ....................................................................
Ad Group Targeting Keywords 46 ....................................................................
Create Targeting Keywords 46 ....................................................................
Find Targeting Keywords 47 ........................................................................
Get Targeting Keywords 48 .........................................................................
Update Targeting Keywords 49 ...................................................................
Campaign Negative Keywords 50 ....................................................................
Create Campaign Negative Keywords 50 ...................................................
Find Campaign Negative Keywords 51 ........................................................
Get Campaign Negative Keywords 51 .........................................................
Update Campaign Negative Keywords 52 ..................................................
Delete Campaign Negative Keywords 52 ....................................................
Ad Group Negative Keywords 53 .....................................................................
Create Ad Group Negative Keywords 53 .....................................................
Find Ad Group Negative Keywords 54 ........................................................
Get Ad Group Negative Keywords 54 .........................................................
Update Ad Group Negative Keywords 55 ...................................................
Delete Ad Group Negative Keywords 55 .....................................................
Search 56 .........................................................................................................
Apple Search Ads
3
Campaign Management API 3.0
App Search 56 .............................................................................................
AppInfo Object 58 ..................................................................................
Search for Geo Locations 58 .......................................................................
Get a List of Geo Locations 61 ....................................................................
Creative Sets 62 ..............................................................................................
Get App Language, Device Sizes, and Assets Details 63 ...........................
Get App Preview Device Sizes 64 ...............................................................
Create an Ad Group Creative Sets Ad Variation 65 .....................................
Find a Ad Group Creative Sets Ad Variation 66 ...........................................
Update an Ad Group Creative Sets Ad Variation 67 ....................................
Delete an Ad Group Creative Sets Ad Variation 67 .....................................
Get a Creative Sets Ad Variation 68 ............................................................
Find a Creative Sets Ad Variation 68 ...........................................................
Assign a Creative Sets Ad Variation to an Ad Group 69 ..............................
Update a Creative Sets Ad Variation 69 ......................................................
Creative Sets and Ad Group Creative Sets Objects 70 ...............................
CreativeSet Object 70 ............................................................................
CreativeSetCreate Object 71 ..................................................................
FindCreativeSetRequest Object 71 .........................................................
Asset Object 72 ......................................................................................
CreativeSetAsset 72 ...............................................................................
CreativeSetAssetsDetail Object 73 ........................................................
CreativeSetLocaleDetail Object 73 .........................................................
AdGroupCreativeSet Object 74 ..............................................................
AdGroupCreativeSetUpdate Object 75 ..................................................
AssignAdGroupCreativeSetRequest 75 ..................................................
MediaAppPreviewOrScreenshotsDetail Object 75 .................................
Apple Search Ads
4
Campaign Management API 3.0
MediaAppPreviewOrScreenshots Object 76 ..........................................
MediaCreativeSetRequest Object 76 .....................................................
Reporting 77 ....................................................................................................
Get Campaign Level Reports 78 .................................................................
CampaignAppDetail Object 79 ...............................................................
Get Ad Group Level Reports 80 ..................................................................
Get Keyword Level Reports 82 ....................................................................
Get Search Terms Level Reports 84 ............................................................
Get Creative Set Level Reports 85 ..............................................................
ReportingRequest Object 86 ......................................................................
groupBy Dimensions 90 .........................................................................
ReportingResponse Object 93 ....................................................................
SpendRow and ExtendedSpendRow Objects 93 ...................................
Row Object 95 ........................................................................................
KeywordInsights Object 95 ....................................................................
KeywordBidRecommendation Object 96 ...............................................
Document Revision History 97.........................................................................
Apple Search Ads
5
Campaign Management API 3.0
Apple Search Ads Campaign Management API 3.0
The Apple Search Ads Campaign Management API 3.0 allows advertisers and agencies
to more efficiently manage their larger Apple Search Ads accounts and provide
additional functionality beyond the Apple Search Ads UI. With the API, advertisers and
agencies can create and manage a large number of campaigns programmatically,
manage ad groups, Creative Sets, targeting keywords, negative keywords, and run
reports for customer insights and trends.
Authenticating
Generate an API certificate to make requests to the Apple Search Ads API.
To make requests to the Apple Search Ads API, you need to authenticate using an API
certificate that is obtained from an Admin account through the Apple Search Ads UI.
1. Click the upper right-hand carrot and select Settings.
2. Click the API tab, then select Create API Certificate.
3. Choose certificate permissions based on roles. For more information, refer to the
roleNames field in the UserAcl object.
4. Click Create.
5. To download the API certificate, select Action, then Download.
Certificates expire after 24 months, at which time you can download a new PEM and
key.
The certificate you downloaded will enable you to establish two-way SSL
authentication.You can use the PEM and key independently, or you have the option to
convert the PEM file and private key into a PKCS#12 (.p12) file.
There are several methods to convert the received PEM file and private key file into a
PKCS#12 (.p12) file. The following OpenSSL command is one method for which an
example is provided below.
openssl pkcs12 -export -in <PEM_file>.pem -inkey <PRIVATE_KEY>.key
-out <FILENAME>.p12
You can test your access to the Apple Search Ads Campaign Management API by using
an example request. The following example command statement authenticates using
the .p12 file and specified password and fetches campaigns within your orgId. In all API
calls, the orgId must be included in the header. You can obtain your orgId via your
account details through the Apple Search Ads UI or by calling Get User ACL, which
returns roles and orgs your API certificate has access to.
Apple Search Ads
6
Campaign Management API 3.0
curl -X GET \
https://api.searchads.apple.com/api/v3/campaigns \
-H 'Authorization: orgId=<OrgID>' \
-H 'Content-Type: application/json' \
--cert-type p12 \
--cert <FILENAME>.p12 \
--pass <PASSWORD>
The example uses cURL. However, any other mechanism to establish SSL
authentication should work similarly. All successful calls will trigger a HTTP 200 OK
response. Unsuccessful calls will trigger error responses.
Account Management
The account structure used to manage campaigns allows for limiting user access. In the
Apple Search Ads UI, orgId is equivalent to a campaign group, If you need to manage
Search Ads for multiple clients, or if you need to restrict user access to a subset of your
campaigns, you can create additional campaign groups within your account and
manage each set of campaigns in a different campaign group. Otherwise, you can
create and manage all your campaigns under your default orgId/campaign group.
Org ID
API calls are used to manage campaigns and create reports within the context of an org.
An orgId is the org for which you make API calls. In all API calls, the orgId must be
included in the header.
Your orgId is considered a campaign group. If you need to manage Search Ads for
multiple clients, or if you need to restrict user access to a subset of your campaigns,
you can create additional campaign groups within your account. You can manage each
set of campaigns in a different campaign group. Otherwise, you can create and manage
all your campaigns under your default orgId/campaign group.
You can obtain your orgId via your account details through the Apple Search Ads UI or
by calling GET /v3/acls which returns roles and orgs the API certificate has access to.
The output is in org tree format.
User ACL
A User Access Control List (ACL) is used to obtain the roles in all organizations that the
certificate is a member of. Each certificate may have access to all or a subset of orgs in
the account org tree. What the certificate can do within each org is dependent on the
role it is assigned. Your orgId is not required if using a User ACL.
GET https://api.searchads.apple.com/api/v3/acls
Apple Search Ads
7
Campaign Management API 3.0
Get User ACL Response Example
{
"data": [
{
"currency": "USD",
"orgId": <orgId>,
"orgName": "<orgName>",
"paymentModel": "LOC",
"roleNames": ["Admin"]
},
{
"currency": "USD",
"orgId": <orgId>;,
"orgName": "<orgName>",
"paymentModel": "LOC",
"roleNames": ["Admin"]
}],
}
Role Names
Possible roleNames for an org include the following:
Payment Model
Possible paymentModel values include the following.
Value
Description
Account Read Only
View campaigns, ad groups, and keywords, pull
reporting.
Read Only
View campaigns, ad groups, and keywords, pull
reporting.
Campaign Manager
View and edit campaigns, ad groups, and keywords,
pull reporting.
Campaign Group
Manager
View and edit campaigns, ad groups, and keywords,
pull reporting.
Admin
View and edit campaigns, ad groups, and keywords,
pull reporting.
Value
Description
LOC
Line of credit.
PAYG
Pay as you go.
<empty string>
Payment method hasn’t been set.
Apple Search Ads
8
Campaign Management API 3.0
API Functionality
Versioning
API method endpoints are versioned. This document is exclusively for is 3.0, as shown
in the following example.
https://api.searchads.apple.com/api/v3/<ENDPOINT>
Endpoints provide access to related parameters. Required fields must be included when
objects are created. Optional fields may be included during creation. Updatable fields
may be modified after the object has been created. Fields that are neither required nor
updatable are read only and are obtained after the object has been created.
Structure and Format
JSON data formats are used exclusively in the API. Responses from the API will include
HTTP response codes, response data, and error messages. You can control the
returned response using pagination parameters, partial fetch, and selectors. Properties
and attributes may be added to the returned JSON objects.
Request Format
An API method endpoint may be a single name or may include elements of a hierarchy
and parameters. The following example returns all campaigns that belong to your org.
GET https://api.searchads.apple.com/api/v3/campaigns
Partial Updates
Field values can be edited using partial updates. When updating a record, you only need
to specify the fields that need to be updated. For example, to update the name and
budget of a specific campaign, use the following format.
PUT "https://api.searchads.apple.com/api/v3/campaigns/<campaignId>/
{
"clearGeoTargetingOnCountryOrRegionChange": true,
"campaign": {
"name": "<renamed campaign>",
"countriesOrRegions": [
"US",
"CA"
]
}
}
Apple Search Ads
9
Campaign Management API 3.0
Pagination
Example Response
{
"data":[
{ },
...
],
"pagination"{
"totalResults": <NUMBER>,
"startIndex": <NUMBER>,
"itemsPerPage": <NUMBER>
},
}
Selectors
Selector is a generic structure used to specify data to be returned when fetching
resources. Selector objects are used with /find and /report endpoints.
A selector object consists of one or more of the following elements.
Parameter
Description
limit
The number of items to return per request.
•
Default is 20 for most objects.
•
Max is 1000 for most objects.
offset
Offset pagination can be applied to most method calls to limit the
number of records returned. Offsets the start of each page by the
number specified. This is the index of the first matching result that
should be included in the result set. The default is 0.
In the following example, the two optional parameters are used to limit the
number of campaigns returned:
GET "https://api.searchads.apple.com/api/v3/campaigns?
limit=<LIMIT>&offset=<OFFSET>"
Apple Search Ads
10
Campaign Management API 3.0
Element
Description
Object Elements
conditions
A list of condition objects, which
allows users to filter the list of
records. This is analogous to the
SQL WHERE clause.
Multiple conditions are ANDed
together.
Each condition object consists of
the following elements:
•
field: the name of a field.
•
operator
-
IN: value is in the given list.
-
EQUALS: value is as specified.
-
GREATER_THAN: value is
greater than the given value.
May be used with time
parameters.
-
LESS_THAN: value is less than
the given value. May be used
with time parameters.
-
STARTSWITH: Used with the /
reporting API only.
•
values: a list of matching
values.
fields
A list of field names to return
within each record. For an
example, see Partial Fetch.
orderBy
•
Optionally specify the field to
use to sort the records
•
Optionally specify the sort
order (ASCENDING or
DESCENDING)
pagination
Limits the number of records
returned.
Apple Search Ads
11
Campaign Management API 3.0
Example Selector Usage
The following is an example of a selector call. Content of the findCampaigns.json file.
! {
"orderBy":[{"field":"id","sortOrder":"DESCENDING"}],
"fields":
["id","name","adamId","budgetAmount","dailyBudgetAmount","status","s
ervingStatus"],
"conditions":[
{
"field":"servingStatus",
"operator":"IN",
"values":["NOT_RUNNING"]
}
],
"pagination":{"offset":0,"limit":10}
}
Partial Fetch
When getting a list of records, users may use the optional fields parameter to limit the
fields within each record that are returned. For example, you can choose to only return
name, id and associated adGroup.id for each campaign.
GET "https://api.searchads.apple.com/api/v3/campaigns?
fields=id,name,adGroups.id,adGroups.name"
Errors and Responses
All successful calls will result in a HTTP 200 OK response.
Status Code
Response
Description
301
RESOURCE_MOVED_
PERMANENTLY
Error resulting from use of an Apple Search Ads
API 2.0 resource with a 1.0 URL.
400
Bad Request
Invalid query or missing required parameters.
401
Unauthorized
An unauthenticated call failed to get the
requested response.
403
Forbidden
Error related to authorization.
404
Not Found
Resource was not found.
405
Method not found
Method is unsupported or input incorrectly.
Apple Search Ads
12
Campaign Management API 3.0
Additional details are provided in the response body.
{
"errors": [
{
"messageCode": "<CODE>",
"message": "<MESSAGE>",
"field": "<FIELD>"
},
...
]
}
Campaigns
Essential points for creating campaigns include the following:
•
Use Search for iOS Apps to retrieve your adamId to use in the payload.
•
App Store territories are assigned with the countriesOrRegions parameter. If
you plan to advertise in multiple markets, then group countries and regions into a
single campaign using ISO country codes. See the campaign object for details on
using countriesOrRegions.
•
Set a budgetAmount and refine it with a daily spend cap using the
dailyBudgetAmount attribute in the currency of your org. For currencies
supported in the API, see the Money object.
After creating a campaign, set up Ad Groups.
500
Internal Server Error
The Apple Search Ads server is temporarily
down or not reachable. The request is probably
valid but needs to be retried at a later point.
503
Service Unavailable
Server is unavailable.
504
Gateway Timeout
Server cannot get a response.
Value
Description
messageCode
A system-assigned error code.
message
A non-localized (U.S. English only) user-friendly string that
describes the error.
field
Provides detailed information.
Apple Search Ads
13
Campaign Management API 3.0
Create a Campaign
Method
Endpoint
POST
https://api.searchads.apple.com/api/v3/campaigns
Example Request Payload:
{
"orgId": <orgId>,
"adChannelType": "SEARCH"
"supplySources": ["APPSTORE_SEARCH_RESULTS"],
"name": "name",
"budgetAmount": {
"amount": "2000",
"currency": "USD"
},
"dailyBudgetAmount": {
"amount": "300",
"currency": "USD"
},
"adamId": <adamId>,
"countriesOrRegions": ["US","AU"]
}
Apple Search Ads
14
Campaign Management API 3.0
Find Campaigns
Use selectors to find campaigns. See the campaign object for property descriptions and
Selector condition operators. If no selector conditions are specified, all campaigns are
returned.
Method
Endpoint
POST
POST https://api.searchads.apple.com/api/v3/campaigns/find
Example Request Payload:
{
"pagination": {
"offset": 0,
"limit": 1000
},
"orderBy": [
{
"field": "id",
"sortOrder": "ASCENDING"
}
],
"conditions": [
{
"field": "countriesOrRegions",
"operator": "CONTAINS_ALL",
"values": [
"US","CA"
]
}
]
}
Apple Search Ads
15
Campaign Management API 3.0
Update a Campaign
Update the countries or regions (App Store geo locations) where your app is being
promoted. Use the associated campaignId in the URI and use partial updates to edit a
subset of object properties without having to include all object properties in the
payload.
Method
Endpoint
PUT
https://api.searchads.apple.com/api/v3/campaigns/
{campaignId}
Example Request Payload:
{
"clearGeoTargetingOnCountryOrRegionChange": true,
"campaign": {
"name": "<name>",
"countriesOrRegions": [
"US",
"CA",
"GB",
"AU"
]
}
}
Apple Search Ads
16
Campaign Management API 3.0
CampaignUpdate Object
The list of campaign fields that can be updated.
Field
Type
Description
budgetAmount
Money
The total budget amount available to
the campaign. You can add to your
campaign but a budgetAmount
cannot be reduced once a campaign
has started. Once you set a budget,
your campaign will run until you
exhaust your budget, pause your
campaign, or reach the end date
youhave set.
budgetOrders
int64
The budget orders assigned to the
campaign. Applies only to campaigns
with a line of credit payment model.
See Get a Budget Order.
countriesOrRegions
string
The App Store geo locations in
which you want to promote your
app. The default value is US.
dailyBudgetAmount
Money
The daily spend cap. If daily spend
amount is reached, a campaign will
be paused for the remainder of the
day.
locInvoiceDetails
locInvoiceDet
ails
The standard invoice details that
can be set and edited using the
locInvoiceDetails object.
name
string
The name of the campaign, unique
within an org.
status
string
The user-controlled status to
enable or pause the campaign.
Values:
ENABLED
PAUSED
Apple Search Ads
17
Campaign Management API 3.0
Get Campaigns
Use this endpoint to return data on a specific campaign or all of your campaigns. You
can also use partial fetch.
Delete Campaigns
Deletes a specific campaign by campaign identifier.
Method
Endpoint
GET
https://api.searchads.apple.com/api/v3/campaigns
GET
https://api.searchads.apple.com/api/v3/campaigns/
{campaignId}
Method
Endpoint
DELETE
https://api.searchads.apple.com/api/v3/campaigns/
{campaignId}
Apple Search Ads
18
Campaign Management API 3.0
Campaign Object
Field Name
Type
Properties
Selectors
Description
adamId
int64
•
Required
•
Not
updatable
EQUALS, IN
adamId of the
promoted app.
adChannelType
String
•
Required
EQUALS
The channel
type of ads
used in a
campaign.
Value: SEARCH
budgetAmount
Amount
Object
•
Required
•
Updatable
EQUALS
LESS_THAN
GREATER_THAN
The total
budget
amount
available to
the campaign.
budgetOrders
List of
Number
•
Optional.
Must
specify
either
locInvoic
eDetails
or
budgetOrd
ers.
•
Updatable
Only for
campaigns
including LOC
Invoice
Details.
countriesOrRegions
ISO
ALPHA-
2
country
code
string list
Updatable
EQUALS,
CONTAINS_ANY,
CONTAINS_ALL
The App Store
geo location in
which you
want to
promote your
app. The
default value
is US.
countryOrRegionServ
ingStateReasons
Map
Read Only
When a
campaign is
not running, a
list of reasons
will be
returned as
strings.
Apple Search Ads
19
Campaign Management API 3.0
dailyBudgetAmount
Amount
Object
•
Optional
•
Updatable
EQUALS
LESS_THAN
GREATER_THAN
When the
daily cap is
reached, your
ads will stop
appearing for
that day and
will restart on
the next day, if
there is still
budget
remaining for
your
campaign.
deleted
Boolean
Read Only
EQUALS, IN
Indicates
whether the
campaign has
been soft
deleted or not.
displayStatus
Enum
(Strin
g)
Read Only
Values are:
RUNNING
ON_HOLD
PAUSED
DELETED
endTime
UTC-
timesta
mp
Read Only
EQUALS
LESS_THAN
GREATER_THAN
The
designated
campaign
endTime
(the ad group
with the last
endTime
associated
with your
campaign).
id
Number
Read Only
EQUALS, IN
A globally
unique
identifier.
locInvoiceDetails
The standard
invoice details
that can be
set and edited
using the
LOCInvoiceDe
tails object.
Apple Search Ads
20
Campaign Management API 3.0
modificationTime
UTC-
timesta
mp
Read Only
EQUALS
LESS_THAN
GREATER_THAN
When the
object was
last modified.
name
String
•
Required
•
Updatable
EQUALS, IN,
STARTSWITH
Has to be
unique within
the org.
orgId
Number
Read Only
Set according
to
authorization.
The orgId is
the ID
associated
with your
account in the
web UI.
paymentModel
Enum
Read Only
EQUALS, IN
Inherited from
the org. May
be null if the
payment
method is not
set up.
Values: LOC,
PAYG
servingStateReasons
List of
Strings
Read Only
When a
campaign is
not running, a
list of reasons
will be
returned as
strings.
servingStatus
Enum
string
Read Only
EQUALS, IN
Whether the
campaign is
serving or not.
Values are:
RUNNING
NOT_RUNNIN
G
Apple Search Ads
21
Campaign Management API 3.0
status
Enum
string
•
Optional
•
Updatable
EQUALS, IN
The condition
of an
operation.
Values are:
ENABLED
(default)
PAUSED
startTime
UTC-
timesta
mp
Read Only
EQUALS
LESS_THAN
GREATER_THAN
The
designated
campaign
startTime
(the adgroup
with the
soonest
startTime
associated
with your
campaign).
sapinLawResponse
Enum
string
Read Only
Identifies the
account as
agency or
non-agency.
This
parameter is
only settable
in the web UI.
Possible
values:
NOT_ANSWER
ED
FRENCH_BUSI
NESS
NOT_FRENCH
_BUSINESS
supplySources
Enum
string
•
Required
•
Not
updatable
CONTAINS_ANY
CONTAINS_ALL
The supply
source of ads
used in a
campaign.
Value:
APPSTORE_S
EARCH_RESU
LTS
Apple Search Ads
22
Campaign Management API 3.0
Budget Orders
A budget order is an optional feature for advertisers who are approved to pay by
monthly invoicing. Budget orders allow advertisers to set the maximum amount they
would like to spend across associated campaigns over a specific period of time. All
campaigns that are associated with the same budget order appear on the same invoice.
Get All Budget Orders
Retrieves a list of budget orders that have been assigned to the specified orgId and have not
completed or been cancelled.
Method
Endpoint
GET
https://api.searchads.apple.com/api/v3/
budgetorders
Example Response Payload:
{
"id": number,
"name": string,
"startDate": MM-DD-YYYY,
"endDate": MM-DD-YYYY,
"budget": {Amount Object},
"orderNumber": string,
"clientName": string,
"primaryBuyerName": string,
"primaryBuyerEmail": string,
"billingAddress": {Address Object},
"billingEmail": string,
"parentOrgId" : number,
"status": enum
}
Apple Search Ads
23
Campaign Management API 3.0
BudgetOrder Object
Field Name
Type
Selectors
Description
billingEmail
String
The billing email.
budget
Amount
Object
Once set, can only be
increased.
clientName
String
EQUALS
IN
STARTSWITH
CONTAINS
ENDSWITH
Required for agency-type
accounts. Typically
denotes the advertiser or
product.
endDate
Date string
The ending date for the
budget, in the format MM-
DD-YYYY.
id
Number
EQUALS
IN
Apple Search Ads-
assigned, globally unique
identifier.
name
String
EQUALS
IN
STARTSWITH
CONTAINS
ENDSWITH
Has to be unique within
the org.
orderNumber
String
EQUALS
IN
STARTSWITH
CONTAINS
ENDSWITH
Required for agency-type
accounts. Typically
denotes a PO number.
parentOrgId
Number
The org which owns the
Budget Order.
primaryBuyerEmail
String
A valid email address.
primaryBuyerName
String
The primary buyer’s name.
startDate
Date string
The starting date for the
budget, in the format MM-
DD-YYYY.
Apple Search Ads
24
Campaign Management API 3.0
status
Enum
EQUALS
IN
The status field is an
enum with the following
values:
INACTIVE: the budget
order has not started.
ACTIVE: budget order has
started.
COMPLETED: budget
order has reached its end
date.
EXHAUSTED: budget
order has exhausted its
budget, but has not
reached its end date.
CANCELLED: budget
order has been cancelled.
Only INACTIVE, ACTIVE,
or EXHAUSTED budget
orders will be returned.
supplySources
String
CONTAINS_ANY
CONTAINS_ALL
The supply source of ads
used in a campaign.
Value:
APPSTORE_SEARCH_RES
ULTS
Apple Search Ads
25
Campaign Management API 3.0
Get a Budget Order
Retrieves a specific budget order if it has been assigned to the specified org and also
returns orders that have been completed or cancelled.
Method
Endpoint
GET
/v3/budgetorders/{BUDGET_ORDER_ID}
Example Response Payload:
{ "data": [
{
"bo": {
"id": <id>,
"name": “<name>”,
"startDate": “2021-04-09T00:00:00.000",
"endDate": "2021-04-12T23:59:59.999",
"budget": {
"amount": "1",
"currency": "USD"
},
"orderNumber”: “<orderNumber>",
"clientName": "<clientName>",
"primaryBuyerName": "<primaryBuyerName>",
"primaryBuyerEmail": "<primaryBuyerEmail>",
"billingEmail": "<billingEmail>",
"status": "COMPLETED",
"parentOrgId": <parentOrgId>
"campaignCount": number,
"entireAccount": boolean,
"orgIdNameMap":
{
"<Org_Id>": "<name>"
},
"spent":
{
"amount": "0",
"currency": "USD"
}
}
],
"pagination": {
"totalResults": 1,
"startIndex": 0,
"itemsPerPage": 1
},
“error”: null
}
Apple Search Ads
26
Campaign Management API 3.0
BudgetOrderResponse Object
The response to requests for budget order details when a Budget Order ID is supplied.
Field Name
Type
Properties
Description
bo
BudgetOrder
Read Only
The details of the budget
order.
orgIdNameMap
Object Map
(Number, String)
Read Only
Map of Campaign Group Id
and name where the budget
order is being used.
spent
Amount
Read Only
Amount of budget spent to
date.
This field is only returned
when a budget order ID is
supplied.
entireAccount
Boolean
Specifies whether the budget
order was assigned to all orgs
within the org tree.
campaignCount
Amount
Read Only
Number of campaigns the
budget order is assigned to.
Includes archived campaigns.
Note: This field is only
returned when a budget order
ID is supplied.
Apple Search Ads
27
Campaign Management API 3.0
LOCInvoiceDetails
LOC Invoice Details applies only to advertisers who are approved to pay by monthly
invoicing. LOC Invoice Details contains billing information to be included on invoices.
Campaigns that are not associated with budget orders and have the same client names
and order numbers are invoiced together.
Either LOC Invoice Details or a Budget Order may be used, but not both.
Example Request Payload
{
"billingContactEmail": string,
"clientName" : string,
"orderNumber" : string,
"buyerName" : string,
"buyerEmail" : string
}
LOCInvoiceDetails Object
Field
Type
Properties
Description
billingContactEmail
String
•
Required
•
Updatable
A valid email
address.
buyerEmail
String
•
Required
•
Updatable
A valid email
address.
buyerName
String
•
Required
•
Updatable
The appropriate
name.
clientName
String
•
Optional
•
Updatable
Required for
agency-type
accounts. Typically
denotes the
advertiser or
product.
orderNumber
String
•
Optional
•
Updatable
Required for
agency-type
accounts. Typically
denotes a PO
number.
Apple Search Ads
28
Campaign Management API 3.0
Money Object
Amount is used whenever a currency value is needed.
Amount Sample Payload
{
"amount": string,
"currency": string
}
Field Name
Type
Properties
Description
amount
String
•
Required
•
Updatable
The monetary value in the specified
currency.
currency
String
Required
The currency string should match that of
the org currency.
Values:
AUD
CAD
EUR
GPD
JPY
MXN
NZD
RUB
USD
Apple Search Ads
29
Campaign Management API 3.0
Ad Groups
An ad group is a collection of criteria used to define who sees your ad in App Store
search results. You can add bid amounts, Targeting Dimensions, Targeting Keywords
and Negative Keywords, and Creative Sets. Use Search for Geo Locations to utilize in
targeting dimensions.
Search Match
When building a campaign promotion strategy, define keywords relevant to your app.
Relevant keywords increase the viability of your app to rank high in user searches.
To use keywords in Apple Search Ads, you need to bid on them. You can either
automate your keyword and bid strategy by using the Search Match feature or using
your own keywords and bid strategy. The Search Match feature is an algorithm that
uses multiple resources to match your ad to relevant searches on the AppStore. The
resources include metadata from your AppStore product page, information about
similar apps in the same genre, and other available search data. Search Match is a good
option if you don’t want to figure out all keyword possibilities and actively bid on them.
To enable Search Match, use Create an Ad Group or Update an Ad Group.
1. Set automatedKeywordsOptIn: true"
2. Set required field defaultCpcBid."
If you're using your own keywords and bid strategy, disable Search Match.
1. Set automatedKeywordsOptIn: false
2. Set required field defaultCpcBid.
3. Use the bidAmount field in Create Targeting Keywords and Update Targeting
Keywords to set a threshold price offered for a keyword used in a bidding auction.
Note: If you don't provide a bidAmount, the bidAmount uses the defaultCpcBid of
the corresponding ad group.
Apple Search Ads
30
Campaign Management API 3.0
Create an Ad Group
To create ad groups, use the associated campaignId in the URI path. Note, you cannot
create or update ad groups with geo targeting for campaigns with multiple
countriesOrRegions.
Method
Endpoint
POST
https://api.searchads.apple.com/api/v3/campaigns/
{campaignId}/adgroups
Example Request Payload:
{
"campaignId": <campaignId>,
"name": “<name>”,
"cpaGoal": {
"amount": “100”,
"currency": “USD”
},
"startTime": "2021-9-28T10:33:31.650",
"endTime": "2021-9-31T10:33:31.650",
"automatedKeywordsOptIn": true,
"defaultCpcBid": {
"amount": "100",
"currency": "USD"
},
"targetingDimensions": {
"age": {
"included": [
{
"minAge": 20,
"maxAge": 25
}
]
},
"gender": {
"included": [
"M"
]
},
"deviceClass": {
"included": [
"IPAD",
"IPHONE"
]
},
"daypart": {
"userTime": {
"included": [
1,
3,
22,
24
]
}
}
},
"orgId": <orgId>,
"status": "ENABLED"
}
Apple Search Ads
31
Campaign Management API 3.0
Find Ad Groups
Find Ad Groups within specified campaign using a selector.
Method
Endpoint
POST
https://api.searchads.apple.com/api/v3/campaigns/{campaignId}/
adgroups/find
Example Request Payload:
{
"pagination": {
"offset": 0,
"limit": 1000
},
"orderBy": [
{
"field": "id",
"sortOrder": "ASCENDING"
}
],
"conditions": [
{
"field": "id",
"operator": "EQUALS",
"values": [
"123"
]
}
]
}
Apple Search Ads
32
Campaign Management API 3.0
Example Response Payload:
{
"data": [
{
"id": <id>,
"campaignId": <campaignId>,
"name": "<name>",
"cpaGoal": null,
"startTime": "2021-04-07T07:00:00.000",
"endTime": null,
"automatedKeywordsOptIn": true,
"defaultCPCBid": {
"amount": "1",
"currency": "USD"
},
"targetingDimensions": {
"age": null,
"gender": null,
"country": null,
"adminArea": null,
"locality": null,
"deviceClass": {
"included": [
"IPHONE",
"IPAD"
]
},
"daypart": null,
"appDownloaders": {
"included": [],
"excluded": []
}
},
"orgId": <orgId>,
"modificationTime": "2021-08-07T23:30:17.280",
"status": "ENABLED",
"servingStatus": "RUNNING",
"servingStateReasons": null,
"displayStatus": "RUNNING",
"deleted": false
},
],
"pagination": {
"totalResults": 17,
"startIndex": 0,
"itemsPerPage": 17
},
"error": null
}
Apple Search Ads
33
Campaign Management API 3.0
Get Ad Groups
Returns data on a specific ad group or all ad groups for a specified campaign.
Update an Ad Group
To update ad groups, use the associated campaignId and adgroupId in the URI path. Use
partial updates as needed. With an ad group update, if you are updating targeting dimensions
then all targetingDimensions must be specified. You can set values to null where applicable.
If updating targetingDimensions then all dimensions must be specified.
Method
Endpoint
GET
/https://api.searchads.apple.com/api/v3/campaigns/
{campaignId}/adgroups/{adgroupId}
GET
https://api.searchads.apple.com/api/v3/campaigns/
{campaignId}/adgroups
Method
Endpoint
PUT
https://api.searchads.apple.com/api/v3/campaigns/
{campaignId}/adgroups/{adgroupId}
Example Request Payload:
{
"name": "<name>",
"cpaGoal": {"amount": "100","currency": "USD"},
"startTime": "2021-02-20T16:20:31.650",
"endTime": "2021-02-20T19:33:31.650",
"automatedKeywordsOptIn": false,
"defaultBidAmount": {"amount": "100","currency": "USD"},
"targetingDimensions": {
"age": {"included": [{"minAge": 20,"maxAge": 25}]},
"gender": {"included": ["M"]},
"country": null,
"adminArea": null,
"locality": null,
"deviceClass": {"included": ["IPAD","IPHONE"]},
"daypart": {"userTime": {"included": [1,3,22,24]}},
"appDownloaders": null
}
}
Apple Search Ads
34
Campaign Management API 3.0
Delete Ad Groups
Deletes an ad group with a campaign and ad group identifier.
Ad Group Object
Method
Endpoint
DELETE
https://api.searchads.apple.com/api/v3/campaigns/
{campaignId}/adgroups/{adgroupId}
Field
Type
Properties
Description
automatedKeywordsOpt
In
Boolean
•
Optional
•
Updatable
Indicates whether
Search Match has been
enabled for the ad
group or not.
campaignId
Number
Required
Set by the services
based on context.
•
On createCampaign,
the ID is set after the
campaign is created.
•
On createAdGroup,
the ID is set based on
the campaignID in the
URI.
cpaGoal
Amount
Object
•
Optional
•
Updatable
Optionally define your
cost-per-acquisition
goal.
defaultCpcBid
Amount
Object
•
Required
•
Updatable
You must define your
default cost-per-click
bid when creating a
campaign.
deleted
Boolean
Read Only
Indicates whether the
ad group has been soft-
deleted or not.
endTime
UTC-
timestamp
•
Required
•
Updatable
The time the designated
ad group ends.
id
Number
Read Only
An assigned, globally
unique identifier.
modificationTime
UTC-
timestamp
Read Only
When the object was
last modified.
Apple Search Ads
35
Campaign Management API 3.0
name
String
•
Required
•
Updatable
Has to be unique within
the org.
orgId
Number
Read Only
Set according to
authorization. The
orgId is the ID
associated with your
account in the web UI.
servingStateReasons
List of
strings
Read Only
When an Ad Group is
not running, a list of
reasons will be returned
as strings.
servingStatus
Enum
Read Only
Whether the campaign/
ad group is actually
serving or not.
Values are:
RUNNING
NOT_RUNNING
startTime
UTC-
timestamp
•
Required
•
Updatable
The time the designated
ad group starts.
status
Enum
•
Optional
•
Updatable
Values are:
ENABLED (default)
PAUSED
targetingDimensions
TargetingDi
mensions
Object
•
Optional
•
Updatable
If not set, defaults to
currently supported
devices of the promoted
app.
See Targeting
Dimensions for
additional details.
Apple Search Ads
36
Campaign Management API 3.0
Targeting Dimensions
Targeting dimensions are optional criteria to narrow the viewing audience of your ad.
Example Request Payload:
{
"targetingDimensions": {
"age": {
"included": [
{
"minAge": 20,
"maxAge": 25
}
]
},
"gender": {
"included": [
"F"
]
},
"country": {
"included": [
"US"
]
},
"adminArea": {
"included": [
"US|CA"
]
},
"locality": {
"included": [
"US|CA|Cupertino"
]
},
"deviceClass": {
"included": [
"IPAD",
"IPHONE"
]
},
"daypart": {
"userTime": {
"included": [
1,
3,
22
]
}
}
}
}
Apple Search Ads
37
Campaign Management API 3.0
Admin Area and Locality
Age
Field
Properties
Description
adminArea
•
Optional
•
Updatable
AdminAreaCriteria and LocalityCriteria
enable targeting users by geographic location. For
example, a campaign promoting a U.S. app can
target admin areas (states) and localities (cities)
within the U.S.
See also Geo Search.
locality
•
Optional
•
Updatable
Field
Properties
Description
age
•
Optional
•
Updatable
Targets by demographic. Limit the age group who you
want to show your ad to. Multiple ranges can be input as
a list.
Example Request Snippet: age
"included": [{
"minAge": 20,
"maxAge": 25
}]
},
Parameter
Type
Properties
Values
minAge
Int
Required
The minimum age targeting is 18.
maxAge
Int
•
Optional
•
Updatable
May be null. There is no limit for
maxAge.
Apple Search Ads
38
Campaign Management API 3.0
App Downloaders
The App Downloaders targeting dimension is used to limit viewing of your ad to
audiences who have or have not downloaded apps that you are trying to promote.
Field
Properties
Description
appDownloaders
•
Optional
•
Updatable
Enables you to target users who have
downloaded a specific app, or downloaded
multiple apps, or have not downloaded an app.
Values are a list of adamIds of your apps. You
can also search for the adamId using /v3/
search/apps.
Values can only include apps that you own. The
included list may only include an adamId that
belongs to the ITC that the parent-org is
associated with.
The excluded list can contain only campaigns
adamId of the app that you are trying to promote
with your campaign.
The included list contains the adamid of the
campaign or adamid of other apps dev owns.
Example Request Snippet: appDownloaders
"appDownloaders": {
"included": [],
"excluded": ["adamId"]
}
Apple Search Ads
39
Campaign Management API 3.0
Country
Daypart
Limit when you want to show your ad.
Field
Properties
Description
Country
•
Optional
•
Updatable
For country dimension, use a single country
code in ISO-ALPHA2-COUNTRYCODE
format. Use Geo Search with entity. Note,
Geo targeting is not supported for
campaigns served to multiple
countriesOrRegions. Use Update
Campaign Request to clear geo targeting
from a campaign update.
Example Request Snippet: country
{
"country": {
"included": [
"US"
]
}
}
Field
Properties
Description
daypart
•
Optional
•
Updatable
Targets by a specific time of day. The hours of a week
are represented by numbers. Numbers can be in the
range 0-167, which represent hours of the week,
starting from Sunday 12AM. For example, the hour
beginning Monday at 1:00AM is 25.
Example Request Snippet: daypart
"daypart": {
"userTime": {
"included": [1, 3, 22,24]
}
}
Apple Search Ads
40
Campaign Management API 3.0
Device Class
Gender
Field
Properties
Description
deviceClass
•
Optional
•
Updatable
Targets or excludes users by device type.
Device Class Values
•
IPAD
•
IPHONE (includes iPhone and iPod Touch)
Example Request Snippet: deviceClass
"deviceClass": {
"included": ["IPAD", "IPHONE"]
}
Field
Properties
Description
gender
•
Optional
•
Updatable
Targets by demographic. Specify the gender you want to
show your ad to. To specify both male and female, pass
NULL.
Gender Values
•
Gender: M, F
Example Request Snippet: gender
"gender": {
"included": ["M"]
}
Apple Search Ads
41
Campaign Management API 3.0
Keywords
Ad groups use two keyword object types: targeting and negative. Both are case
insensitive.
Use Search Match to automatically show ads on search terms relevant to your app. You
can use up to 5000 keywords for targeting and negative keywords. As a best practice
for performance, you can use up to 1000 keywords per API call.
•
Targeting keywords are relevant words or phrases used when you want to show ads
according to keywords when searching for your app. Also, for keywords that you want
to bid on. Targeting keywords supports up to one thousand keywords.
•
Negative keywords can be used with both campaigns and ad groups when you want
to prevent keywords from showing in App Store searches.
Keyword Object
Field
Type
Properties
Selectors
Description
adGroupId
Number
Read Only
EQUALS
IN
Represents the identifier
for the ad group.
bidAmount
Amount
Object
•
Required
•
Updatable
The bid amount to display
your ad for the matching text
value.
If not specified then the field
remains NULL. The system
will use the Ad Group
defaultCpcBid to charge the
spend.
deleted
Boolean
Read Only
EQUALS
IN
Indicates whether the
keyword has been soft
deleted or not. All
keywords, which belong to
an ad group that had been
soft deleted, are also soft
deleted.
id
Number
Read Only
EQUALS
IN
Assigned, globally unique
identifier.
matchType
Enum
•
Optional
Controls how ads are
matched to user searches.
Values are:
EXACT
BROAD (default)
Apple Search Ads
42
Campaign Management API 3.0
modificati
onTime
UTC-
timestamp
Read Only
When the object was last
modified.
status
Enum String
•
Optional
•
Updatable
Values are:
ACTIVE (default)
PAUSED
text
String
Required
The word or phrase to
match in user searches, to
show your ad.
Apple Search Ads
43
Campaign Management API 3.0
Negative Keywords Object
Field Name
Type
Properties
Selectors
Description
id
Number
Read Only
EQUALS
IN
A globally unique
identifier.
campaignId
Number
•
Required to
create
•
Required to
update
EQUALS
IN
Represents the
identifier for the
campaign.
adGroupId
Number
•
Required to
create
•
Required to
update
EQUALS
IN
Represents the
identifier for the ad
group.
This field is
applicable negative
keyword of ad
groups. For
campaigns the field
is not applicable.
modification
Time
UTC-
timestamp
Read Only
When the object was
last modified.
text
String
Required
The word or phrase
to match in user
searches, to show
your ad.
matchType
Enum
Required
Controls how ads are
matched to user
searches.
Values are:
EXACT
BROAD (default)
Status
Enum String
•
Optional
•
Updatable
Values are:
ACTIVE (default)
PAUSED
Apple Search Ads
44
Campaign Management API 3.0
deleted
Boolean
Read Only
•
Indicates whether
the negative
keyword has been
soft deleted or not.
•
All negative
keywords, which
belong to a soft
deleted campaign
or ad group, are
also soft deleted.
Apple Search Ads
45
Campaign Management API 3.0
Ad Group Targeting Keywords
Create Targeting Keywords
Creates targeting keywords in ad groups."
Method
Endpoint
POST
https://api.searchads.apple.com/api/v3/
campaigns/{campaignId}/adgroups/{adgroupId}/
targetingkeywords/bulk
Example Request Payload:
[ {
"text": "keyword 4",
"matchType": "BROAD",
"bidAmount": {
"amount": "1.50",
"currency": "USD"
}
},
{
"text": "keyword 5",
"matchType": "EXACT",
"bidAmount": {
"amount": "2",
"currency": "USD"
}
}
]
Apple Search Ads
46
Campaign Management API 3.0
Find Targeting Keywords
Find keywords in ad groups within specified campaign using selector conditions. If no selector
conditions are specified, keywords across all ad groups of the campaign are returned. Add
selector adGroupId to narrow results to specific ad groups.
Method
Endpoint
POST
https://api.searchads.apple.com/api/v3/campaigns/
{campaignId}/adgroups/targetingkeywords/find
Example Request Payload:
{
"pagination": {
"offset": 0,
"limit": 1000
},
"orderBy": [
{
"field": "id",
"sortOrder": "ASCENDING"
}
],
"conditions": [
{
"field": "matchType",
"operator": "EQUALS",
"values": [
"BROAD"
]
}
]
}
Apple Search Ads
47
Campaign Management API 3.0
Get Targeting Keywords
Returns all keywords in ad groups.To return all targeting keywords used in a campaign,
use the associated campaignId and adgroupId in the URI. You can also use partial
fetch.
Method
Endpoint
GET
https://api.searchads.apple.com/api/v3/
campaigns/{campaignId}/adgroups/{adgroupId}/
targetingkeywords
GET
https://api.searchads.apple.com/api/v3/
campaigns/{campaignId}/adgroups/{adgroupId}/
targetingkeywords/{keywordId}
Apple Search Ads
48
Campaign Management API 3.0
Update Targeting Keywords
To update targeting keywords, use the associated campaignId and adgroupId in the URI.
The id in the payload must belong to a keyword that exists inside the ad group in the
URI. The status and bidAmount fields are modifiable in the payload. Use Partial
Updates to edit a subset of object properties without having to include all object
properties in the payload.
Method
Endpoint
PUT
https://api.searchads.apple.com/api/v3/campaigns/
{campaignId}/adgroups/{adgroupId}/targetingkeywords/
bulk
Example Request Payload:
[
{
"id": <id>,
"adGroupId": <adGroupId>,
"text": "keyword1",
"status": "PAUSED",
"matchType": "BROAD",
"bidAmount": {
"amount": "2",
"currency": "USD"
},
"deleted": false
},
{
"id": <id>,
"adGroupId": <adGroupId>,
"text": "keyword2",
"status": "PAUSED",
"matchType": "EXACT",
"bidAmount": {
"amount": "1",
"currency": "USD"
},
"deleted": false
}
]
Apple Search Ads
49
Campaign Management API 3.0
Campaign Negative Keywords
Negative keywords are words or phrases for which you want to prevent your ad from
being shown when searches are run containing the selected negative keyword.
Create Campaign Negative Keywords
To create campaign negative keywords, use the associated campaignId in the URI.
Method
Endpoint
POST
https://api.searchads.apple.com/api/v3/campaigns/
{campaignId}/negativekeywords/bulk
Example Request Payload:
[
{
"text": "keyword 1",
"matchType": "BROAD"
},
{
"text": "keyword 2",
"matchType": "EXACT"
}
]
Apple Search Ads
50
Campaign Management API 3.0
Find Campaign Negative Keywords
To find campaign negative keywords, use the associated campaignId in the URI. Find
calls use selectors. If no selector conditions are specified, all negative keywords in the
campaign are returned in the response. See NegativeKeyword object for details on
Selector Condition operators per field.
Get Campaign Negative Keywords
To return a specific campaign negative keyword or all campaign negative keywords, use
the associated campaignId and keywordId in the URI. You can also use partial fetch.
Method
Endpoint
POST
https://api.searchads.apple.com/api/v3/campaigns/
{campaignId}/negativekeywords/find
Example Request Payload:
{
"pagination": {
"offset": 0,
"limit": 1000
},
"orderBy": [
{
"field": "id",
"sortOrder": "ASCENDING"
}
],
"conditions": [
{
"field": "matchType",
"operator": "EQUALS",
"values": [
"BROAD"
]
}
]
}
Method
Endpoint
GET
/campaigns/{campaignId}/negativekeywords
GET
/campaigns/{campaignId}/negativekeywords/
{keywordId}
Apple Search Ads
51
Campaign Management API 3.0
Update Campaign Negative Keywords
To update campaign negative keywords, use the associated campaignId in the URI. The
id used in the payload must belong to a negative keyword that exists inside the
campaign specified in the URI. The status field are modifiable with PAUSED or ACTIVE
values. Use partial updates to edit a subset of object properties without having to
include all object properties in the payload.
If data is not updated, PUT calls for negative keywords returns a null response.
Delete Campaign Negative Keywords
To delete campaign negative keywords, use the associated campaignId in the URI.
Include each keywordId in the payload.
Method
Endpoint
PUT
https://api.searchads.apple.com/api/v3/campaigns/
{campaignId}/negativekeywords/bulk
Example Request Payload:
[
{
"text": "negative keyword 1",
"matchType": "EXACT"
},
{
"text": "negative keyword 2",
"matchType": "BROAD"
}
]
Method
Endpoint
POST
https://api.searchads.apple.com/api/v3/campaigns/
{campaignId}/negativekeywords/delete/bulk
Example Request Payload:
[
<keywordId>,
<keywordId>,
<keywordId>
]
Apple Search Ads
52
Campaign Management API 3.0
Ad Group Negative Keywords
Negative keywords prevent your ad from showing up for App Store searches. Negative
keywords can belong to a campaign or an ad group.
Create Ad Group Negative Keywords
Method
Endpoint
POST
https://api.searchads.apple.com/api/v3/campaigns/
{campaignId}/adgroups/{adGroupId}/
negativekeywords/bulk
Example Request Payload:
[
{
"id": "000000",
"status": "PAUSED"
},
{
"id": "000000",
"status": "PAUSED"
}
]
Apple Search Ads
53
Campaign Management API 3.0
Find Ad Group Negative Keywords
To find negative keywords, use the associated campaignId and adgroupId in the URI.
Find calls use selectors. If no Selector Condition operators are included in the payload,
then the API returns all negative keywords across all ad groups of the campaign. Use
the adGroupId field with selector conditions to narrow results to specific ad groups.
Get Ad Group Negative Keywords
Fetches all or a specific negative keyword in an ad group."
Method
Endpoint
POST
/campaigns/{campaignId}/adgroups/{adGroupId}/
negativekeywords/find
Example Request Payload:
{
"pagination": {
"offset": 0,
"limit": 1000
},
"orderBy": [
{
"field": "id",
"sortOrder": "ASCENDING"
}
],
"conditions": [
{
"field": "matchType",
"operator": "EQUALS",
"values": [
"BROAD"
]
}
]
}
Method
Endpoint
GET
/campaigns/{campaignId}/adgroups/{adGroupId}/
negativekeywords
GET
/campaigns/{campaignId}/adgroups/{adGroupId}/
negativekeywords/{keywordId}
Apple Search Ads
54
Campaign Management API 3.0
Update Ad Group Negative Keywords
To update campaign negative keywords, use the associated campaignId in the URI. The
id used in the payload must belong to a negative keyword that exists inside the
campaign specified in the URI. The status field are modifiable with PAUSED or ACTIVE
values. Use partial updates to edit a subset of object properties without having to
include all object properties in the payload.
Delete Ad Group Negative Keywords
To delete an ad group, include the associated campaignId and adgroupId in the URI
path. This is a soft deletion.
Method
Endpoint
PUT
https://api.searchads.apple.com/api/v3/campaigns/
{campaignId}/negativekeywords/bulk
Method
Endpoint
POST
https://api.searchads.apple.com/api/v3/campaigns/
{campaignId}/adgroups/{adgroupId}/negativekeywords/
delete/bulk
Example Request Payload:
[
<keywordId>,
<keywordId>,
<keywordId>
]
Apple Search Ads
55
Campaign Management API 3.0
Search
Search is used to fetch app and geo criteria used for audience refinement. Search also
returns important data used elsewhere in the API.
App Search
Use this endpoint to search for iOS apps that you can promote in a campaign. You can
Use Query Params to fetch data.
An app search returns your adamId which can be used in Create a Campaign in addition
to the AppDownloaderCriteria targeting dimension. You can apply targeting
dimensions to ad groups using Create an Ad Group or Update an Ad Group.
Enables retrieval of a list of apps based on adamId.
Using QueryParams
All search patterns use a prefix-matching algorithm.
•
Spaces are allowed in search patterns.
•
The entire pattern needs to be enclosed in internal quotes.
•
QueryParams require a minimum of three characters.
•
If you are sending a quoted search string via cURL, use HTML encoding.
Method
Endpoint
GET
https://api.searchads.apple.com/api/v3/search/apps
Query Param
Type
Properties
Description
Query
String
Required
Search for a list of iOS apps based on adamId
using a matching query prefix.
Example QueryParam: query for adamId
"https://api.searchads.apple.com/api/v3/search/apps?query=Run%20Ke"
Apple Search Ads
56
Campaign Management API 3.0
Query Param
Type
Properties
Description
limit
Number
Optional
A limit on the number of apps in the
response.
Example QueryParam: limit
"https://api.searchads.apple.com/api/v3/search/apps?limit=100
returnedOwnApps
True/False
Optional
Use returnedOwnApps to return the
list of apps that are owned by the iTC
accounts (if any) linked to the orgId
specified in the header.
Example QueryParam: returnedOwnApps
"https://api.searchads.apple.com/api/v3/search/apps?
query="appexample"&returnOwnedApps=true"
Example Request Payload:
[
{
"adamId": long,
"appName": "string",
"developerName": "string"
"countryCodes": [list of "<ISO_ALPHA2_COUNTRYCODE>"
strings]
},
...
]
Apple Search Ads
57
Campaign Management API 3.0
AppInfo Object
The response to an app search request.
Search for Geo Locations
Search for a list of targetable user locations (country, admin area, sub-admin area) with
a prefix matching the query.
The targetable location id that is returned can be used as an input value when setting
the applicable targeting location dimensions.
Required fields are id and entity. If no parameters are input, all applicable values will
be returned.
Note: The API does not currently support DMA or zip code targeting for U.S. geo
search.
Using QueryParams
All search patterns use a prefix-matching algorithm.
•
Spaces are allowed in search patterns.
•
The entire pattern needs to be enclosed in internal quotes.
•
QueryParams require a minimum of three characters.
•
If you are sending a quoted search string via cURL, use HTML encoding.
Field Name
Type
Description
adamId
int64
Your unique App Store Connect application
identifier.
appName
string
The name of the app.
countryOrRegionCodes
string
A list of ISO-ALPHA2-COUNTRYCODE
strings.
developerName
string
The developer name for the app.
Apple Search Ads
58
Campaign Management API 3.0
Method
Endpoint
GET
https://api.searchads.apple.com/api/v3/search/geo
Example QueryParam: query
"https://api.searchads.apple.com/api/v3/search/geo?
query=%22New%20H%22"
Example Request Payload:
{
"data":[
{
"id": "US",
"entity": "Country",
"displayName": "United States"
},
{
"id": "US|NY",
"entity": "AdminArea"
"displayName": "New York, United States"
},
{
"id": "US|NY|New York",
"entity": "Locality"
"displayName": "New York, New York, United States"
}
],
Apple Search Ads
59
Campaign Management API 3.0
QueryParam
Type
Properties
Description
Entity
String
Optional
The QueryParam searches the displayNames
for Locality and AdminArea in all languages.
Search results will be in the preferred language
according to your org. Based on matching
language, the returned preferred language result
might be different, even though it represents the
same entity correctly.
Values:
AdminArea
Locality
Example QueryParam: limit and entity
"https://api.searchads.apple.com/api/v3/search/geo?
limit=1000&entity=Locality"
QueryParam
Type
Properties
Description
id
String
Optional
Geographic location. Formatted by
CountryCode|AdminArea|Locality.
• CountryCode is a ISO-ALPHA2-
COUNTRYCODE string.
• AdminArea is state.
• Locality is city.
Example QueryParam: id
"https://api.searchads.apple.com/api/v3/search/geo?id==US|NY|
York"
limit
Number
Optional
A limit on the number of geo locations in the
response.
Example QueryParam: limit
"https://api.searchads.apple.com/api/v3/search/geo?limit=100
Apple Search Ads
60
Campaign Management API 3.0
Get a List of Geo Locations
Use this endpoint to return corresponding display names based on geo id. Use display
names to specify a geographic targeting location. First, use the Search for Geo
Locations endpoint to fetch a geo id to use in the payload.
Search for a list of geo locations including id and entity type to return displayNames.
Method
Endpoint
POST
/search/geo
Example Request Payload:
[
{
"id": "US|NY|New York Mills",
"entity": "Locality"
}
]
Apple Search Ads
61
Campaign Management API 3.0
Creative Sets
Creative Sets is a grouping of screenshots and app previews you select from your App
Store product page to create more ad variations. With ad variations, you can test
different variations of your ad in ad groups and optimize for different devices and
display sizes. See searchads.apple.com for some suggestions on testing ad variations
across campaigns.
After setting up your app and assets on App Store Connect, you can create and link
Creative Sets to ad groups through the API or through the Apple Search Ads UI.
Supplying Asset Details to App Store Connect
Using Creative Sets in the Apple Search Ads Campaign Management API requires
assets of your app to be uploaded to App Store Connect. There are two important
requirements that must be met for the API to return asset data.
•
Your app needs a minimum number of assets. See the Asset object,
MediaAppPreviewOrScreenshots and MediaAppPreviewOrScreenshotsDetail for app
asset descriptions.
•
The supported language linked to your campaign must be the same as the App Store
Connect geo location of your app.
After you have uploaded your app assets to App Store Connect:
1. Use Get App Language, Device Sizes, and Assets Details to identify supported
languages for your app and countries or regions.
2. Create Ad Group Creative Sets.
3. Creative Sets can be reassigned to another ad group using Assign Creative Sets to
an Ad Group.
4. You can measure campaign performance based on metrics returned through Get
Creative Set Level Reports.
Apple Search Ads
62
Campaign Management API 3.0
Get App Language, Device Sizes, and Assets Details
Fetches assets used with Creative Sets. Use this endpoint to return assets for an app
associated with an adamId. Use your adamId in the URI.
Your iTunes application identifier is your adamId. Each time you use an adamId in the
API it must match the adamId used in your campaign. Use Get Campaigns to obtain
your adamId and correlate it to the correct campaign.
Method
Endpoint
POST
https://api.searchads.apple.com/api/v3/
creativeappassets/{adamId}
1st step Request Payload:
{
"countriesOrRegions": [
"US"
]
}
2nd step Request Payload:
{
"countriesOrRegions": [
"US"
],
"assetsGenIds": [
"<assetGenId>",
"<assetGenId>"
]
}
Apple Search Ads
63
Campaign Management API 3.0
In the first step, use the assetGenIds for each asset returned in the response to get
specific assets of apps assigned to Creative Sets ad variations. In this case, pass each
assetGenId attribute in the payload for step 2.
If successful, the HTTP status code is 200 (OK) and the
MediaCreativeSetDetailResponse object is returned.
Note: Assets are organized within the app by language and device size. There must be
enough assets available under the device size for them to be returned. If you have
upload some assets and they are not being returned, make sure the minimum number of
assets required for Creative Sets per device, orientation and asset type have been
uploaded to App Store Connect.
Get App Preview Device Sizes
Fetches supported app preview device size mappings. Use this endpoint to return a
complete list of supported app preview device size mappings. If successful, the HTTP
status code is 200 (OK) and the AppPreviewDevicesMappingResponse object is
returned.
Method
Endpoint
GET
https://api.searchads.apple.com/api/v3/
creativeappmappings/devices
Example Response Payload:
{
"data": {
"ipadPro": "iPad 12.9",
"iphone6+": "iPhone 5.5",
"iphone_5_8": "iPhone 5.8",
"iphone5": "iPhone 4",
"iphone6": "iPhone 4.7",
"ipadPro_2018": "iPad 11",
"ipad": "iPad 9.7",
"iphone_6_5": "iPhone 6.5",
"ipad_10_5": "iPad 10.5"
}
}
Apple Search Ads
64
Campaign Management API 3.0
Create an Ad Group Creative Sets Ad Variation
Use this endpoint to create a Creative Sets ad variation and assign it to an ad group.
AdGroupCreativeSet relationships must be created through the Apple Search Ads UI.
API users can onlyRead and Update AdGroupCreativeSet.
Each AdGroupCreativeSet relationship has a unique entry and can be managed
independently per adGroup (e.g. Enabled, Paused, Removed). A Creative Sets ad
variation can only serve if the AdGroupCreativeSet status is Enabled and the ad group
serving status is Running.
To create an Ad Group Creative Sets ad variation, pass the adamId and assetGenIds in
the request payload. To obtain assetGenIds, link a supported language to your app.
See Payload Example: Get App Language, Device Sizes, and Assets Details.
• Use the assetGenIds for each asset returned in the response to get specific assets
of apps assigned to a Creative Sets ad variation. See Payload Example: Get App
Language, Device Sizes and Assets Details Using assetGenId. The assetGenId is
assigned to each of your Creative Sets assets.
• When you create a Creative Sets ad variation and assign it to an ad group, the
system generates an id and a creativeSetId in the response payload.
To obtain your adamId and correlate it to the correct campaign for use in the payload,
use Get Campaigns.
Method
Endpoint
POST
https://api.searchads.apple.com/api/v3/campaigns/
{campaignId}/adgroups/{adgroupId}/
adgroupcreativesets/creativesets
Example Request Payload:
{
"creativeSet": {
"adamId": <adamId>,
"name": "<name>",
"languageCode": "en-US",
"assetsGenIds": [
"<assetsGenId>",
"<assetsGenId>",
"<assetsGenId>",
"<assetsGenId>"
]
}
}
Apple Search Ads
65
Campaign Management API 3.0
The API returns assets in the response payload organized by language and device size.
If you upload assets and they are not returned, make sure the minimum number of
assets required for Creative Sets per device, orientation, and asset type are uploaded to
App Store Connect.
Find a Ad Group Creative Sets Ad Variation
Use this endpoint to fetch all Creative Sets assigned to ad groups. Use this endpoint to
find all Creative Sets ad variations assigned to an ad group. Use the corresponding
campaignId of the ad group in the URI. Use the id field with its corresponding ad
group as a value in the request payload.
Method
Endpoint
POST
https://api.searchads.apple.com/api/v3/campaigns/
{campaignId}/adgroupcreativesets/find
Example Request Payload:
{
"selector": {
"conditions": [
{
"field": "id",
"operator": "EQUALS",
"values": [
"11111111"
]
}
]
}
}
Apple Search Ads
66
Campaign Management API 3.0
Update an Ad Group Creative Sets Ad Variation
Use this endpoint to updates ad group Creative Sets using an identifier. To pause or
enable a adgroupcreativeset, use the corresponding adgroupId and campaignId in
the URI path and use values: PAUSED or ENABLED.
Delete an Ad Group Creative Sets Ad Variation
Use this endpoint to deletes Creative Sets from a specified ad group. To delete a
Creative Sets ad variation from an ad group, retrieve your AdGroupCreativeSetIds
from Find AdGroupCreativeSets to use in the request payload as an array. The
response is the number of adgroupcreativesets deleted.
Method
Endpoint
PUT
https://api.searchads.apple.com/api/v3/campaigns/
{campaignId}/adgroup/{adgroupId}/
adgroupcreativeset/{adgroupcreativesetId}
Example Request Payload:
{"status":"PAUSED"}
Method
Endpoint
POST
https://api.searchads.apple.com/api/v3/campaigns/
{campaignId}/adgroups/{adgroupId}/
adgroupcreativesets/delete/bulk
Example Request Payload:
[11111111,22222222,33333333,4444444]
Apple Search Ads
67
Campaign Management API 3.0
Get a Creative Sets Ad Variation
Use this endpoint to fetch asset details of a Creative Sets ad variation. To return asset
details for specific Creative Sets, use the associated creativeSetId in the URI path.
You obtain a creativeSetId when you Create an Ad Group Creative Set. Your app
needs a minimum number of assets to return asset data.
Find a Creative Sets Ad Variation
Use this endpoint to fetch all Creative Sets assigned to an organization. Use this
endpoint to find all Creative Sets assigned to an organization. Use the name or id field
with its corresponding campaignId as a value in the request payload.
Method
Endpoint
GET
https://api.searchads.apple.com/api/v3/
creativesets/{creativeSetId}
Method
Endpoint
POST
https://api.searchads.apple.com/api/v3/
creativesets/find
Example Request Payload:
{
"selector": {
"conditions": [
{
"field": "id",
"operator": "EQUALS",
"values": [
"11111111"
]
}
]
}
}
Apple Search Ads
68
Campaign Management API 3.0
Assign a Creative Sets Ad Variation to an Ad Group
Use this endpoint to create a Creative Sets assignment or reassignment to an ad group.
In the request payload, use the creativeSetId obtained when you create an ad group
Creative Sets ad variation.
Update a Creative Sets Ad Variation
Use this endpoint to reassign to update a Creative Sets name using an identifier. To
update a Creative Sets name, use the associated creativeSetId in the URI path. Use
Find Creative Sets to obtain a creativeSetId assigned to your org.
Method
Endpoint
POST
https://api.searchads.apple.com/api/v3/campaigns/
{campaignId}/adgroups/{adgroupId}/
adgroupcreativesets
Example Request Payload:
{
"creativeSetId": <creativeSetId>
}
Method
Endpoint
PUT
https://api.searchads.apple.com/api/v3/
creativesets/{creativeSetId}
Example Request Payload:
{
"name":"<name>”
}
Apple Search Ads
69
Campaign Management API 3.0
Creative Sets and Ad Group Creative Sets Objects
CreativeSet Object
The basic details of a Creative Sets ad variation.
Field Name
Type
Description
id
int64
The identifier of a Creative Sets ad variation.
name
string
The name of a Creative Sets ad variation.
adamId
int64
Your App Store Connect application identifier. The
adamId must be the same as the app promoted in
your campaign.
creativeSetAs
sets
CreativeSet
Asset object
The assignment relationship between an asset and
a Creative Sets ad variation.
languageCode
string
The language code that comes from the media
response; for example, en-US.
orgId
int64
The authorization organization. You can obtain your
orgId via your account details through the Apple
Search Ads UI or by calling Get User ACL, which
returns roles and orgs that the API certificate has
access to.
status
string
The user-controlled status to enable or pause the
Creative Sets ad variation.
Values are:
ENABLED (default)
PAUSED
statusReasons
string
The reason for the Creative Sets ad variation
status. The reason gets returned only if the
Creative Sets status is invalid.
Apple Search Ads
70
Campaign Management API 3.0
CreativeSetCreate Object
The response to creating a new Creative Sets ad variation.
FindCreativeSetRequest Object
The request to find Creative Sets.
Field Name
Type
Description
adamId
int64
Your App Store Connect application identifier. The
adamId must be the same as the app promoted in
your campaign.
name
string
The name of a Creative Sets ad variation.
languageCode
string
The language code that comes from the media
response; for example, en-US.
assetGenId
string
The identifier for app preview or screenshot.
Field Name
Type
Description
selector
Selector
A generic structure used to specify data to be
returned when fetching resources. Use
selector objects with find and report endpoints.
includeDeletedCr
eativeSetAssets
boolean
Includes deleted Creative Sets in the response
payload. To include deleted Creative Sets, use
the includeDeletedCreativeSetAssets
query param and set to true as shown the
following example. The default is false.
https://api.searchads.apple.com/api/
v3/creativesets/<creativeSetId>?
includeDeletedCreativeSetAssets=true
Apple Search Ads
71
Campaign Management API 3.0
Asset Object
The assets used to create Creative Sets.
CreativeSetAsset
The assets of a Creative Sets ad variation.
Field Name
Type
Description
appPreviewDev
ice
string
The device for which the asset is available,
corresponding to the display size. See Get App
Preview Device Sizes for device mapping in the
API.
assetGenId
string
The identifier for app preview or screenshot.
deleted
boolean
Indicates whether the ad group has been soft-
deleted or not. All keywords, which belong to an ad
group that had been soft deleted, are also soft
deleted.
orientation
string
The orientation of the asset uploaded to App Store
Connect.
Values are:
Portrait
Landscape
Unknown
type
string
The type of asset.
App previews are still images of video assets that
you have uploaded to App Store Connect. Note,
the playable URL is not in the response.
A screenshot is a standard image of the app that
you have uploaded to App Store Connect.
Values are:
APP_PREVIEW
SCREENSHOT
Field Name
Type
Description
asset
Asset object
The asset used to create the Creative Sets ad
variation.
id
boolean
A unique identifier for a Creative Sets ad
variation asset assigned to an ad group.
Apple Search Ads
72
Campaign Management API 3.0
CreativeSetAssetsDetail Object
The asset details to create a Creative Sets ad variation.
CreativeSetLocaleDetail Object
Field Name
Type
Description
creativeSetDetails
The asset details to create a Creative Sets ad
variation.
Field Name
Type
Description
appPreviewDeviceWithAssets
string
The device display name, fallback
device display names, and associated
assets.
isPrimaryLocale
boolean
The language of the primary locale for
the app used in the Creative Sets ad
variation.
languageCode
string
The language code; for example, en-
US.
languageDisplayName
string
The language used in the Creative
Sets detail.
Apple Search Ads
73
Campaign Management API 3.0
AdGroupCreativeSet Object
Field Name
Type
Properties
Selectors
Description
id
int64
Read Only
EQUALS, IN
Represents the identifier
for the
AdGroupCreativeSet
campaignId
int64
EQUALS, IN
Represents the
identifier for the
campaign.
adGroupId
int64
EQUALS, IN
Represents the
identifier for the ad
group.
creativeSetId
int64
Represents the
identifier for the
Creative Sets ad
variation.
status
string
EQUALS, IN
Values are:
ENABLED (default)
PAUSED
servingStatus
string
Read Only
Whether the campaign/
ad group is serving or
not.
Values:
RUNNING
NOT_RUNNING
servingStatusR
easons
enum
string
Read Only
When an ad group is not
running, a list of
reasons will be returned
as strings.
deleted
boolean
Read Only
EQUALS, IN
Indicates whether the
ad group has been soft-
deleted or not.
modificationTi
me
UTC
Date
Read Only
When the object was
last modified.
Apple Search Ads
74
Campaign Management API 3.0
AdGroupCreativeSetUpdate Object
The response to ad group Creative Sets update requests.
AssignAdGroupCreativeSetRequest
The request to assign Creative Sets to an ad group.
MediaAppPreviewOrScreenshotsDetail Object
The app asset details of a device.
Field Name
Type
Description
status
string
The user-controlled status to enable or pause
the adgroupcreativeset.
Values:
ENABLED
PAUSED
Field Name
Type
Description
creativeSetId
int64
The unique identifier for the Creative Sets
assigned to an ad group. When you create a
Creative Sets ad variation, the system sets a
CreativeSetId.
Field Name
Type
Description
deviceDisplayName
string
The display name of the device
previewing the app. See Get App
Preview Device Sizes for how devices
are mapped in the API.
fallBackDevicesDisplay
Names
Number
The device mappings for all the
devices that use assets. Devices that
do not have assets uploaded use the
fallback device mapping.
screenshots
Number
Standard images of your app used for
App Previews.
appPreviews
Number
Still images of video assets used for
App Previews.
Apple Search Ads
75
Campaign Management API 3.0
MediaAppPreviewOrScreenshots Object
The asset details of the app preview or app screenshots.The fields of this object
correspond to the asset details in MediaAppPreviewOrScreenshotsDetail. App
Store Connect refers to this feature as an app preview poster frame.
MediaCreativeSetRequest Object
The request body for getting Creative Sets ad variation assets.
Field Name
Type
Description
assetGenId
string
The identifier for app preview or
screenshot.
assetType
string
The type of asset.
App previews are still images of video
assets that you have uploaded to App
Store Connect. Note, the playable
URL is not in the response.
A screenshot is a standard image of
the app that you have uploaded to
App Store Connect.
assetURL
string
The resolved URL for the screenshot
or a screenshot of the video asset.
orientation
string
The orientation of the asset uploaded
to App Store Connect.
sortPosition
int64
The position of the asset.
sourceHeight
int32
The height of the asset.
sourceWidth
int32
The width of the asset.
Field Name
Type
Description
assetsGenIds
string
The relationship between a Creative
Sets ad variation and an asset.
countryOrRegions
string
The App Store country or region you
are promoting your app. The default
value is US. See Get App Language,
Device Sizes, and Assets Details.
This field is required.
Apple Search Ads
76
Campaign Management API 3.0
Reporting
You can fetch reports for campaigns, ad groups, targeting keywords, search terms, and
creative sets. See the ReportingRequest object for guidance for setting up your
reporting request payloads.
Use endpoints to fetch reports on Creative Sets used within your campaigns.
• You can use a Selector Condition with values to filter results.
• All fields are available to use with the orderBy selector to specify fields to sort the
records list by ASCENDING or DESCENDING.
Apple Search Ads
77
Campaign Management API 3.0
Get Campaign Level Reports
Fetches reports on campaigns.
Method
Endpoint
POST
https://api.searchads.apple.com/api/v3/
reports/campaigns
Example Request Payload:
{
"startTime": "2019-02-20",
"endTime": "2019-02-28",
"selector": {
"orderBy": [
{
"field": "countryOrRegion",
"sortOrder": "ASCENDING"
}
],
"conditions": [
{
"field": "countriesOrRegions",
"operator": "CONTAINS_ANY",
"values": [
"US",
"GB"
]
},
{
"field": "countryOrRegion",
"operator": "IN",
"values": [
"US"
]
}
],
"pagination": {
"offset": 0,
"limit": 1000
}
},
"groupBy": [
"countryOrRegion"
],
"timeZone": "UTC",
"returnRecordsWithNoMetrics": true,
"returnRowTotals": true,
"returnGrandTotals": true
}
Apple Search Ads
78
Campaign Management API 3.0
The following fields and metadata are returned as a ReportingCampaign object. All
fields may be used with the orderBy selector except app, appName, adamId and
servingStateReasons.
CampaignAppDetail Object
Field
Type
Conditions: Operator
adChannelType
String
EQUALS
app
CampaignAppDet
ail
campaignId
Long
EQUALS, IN, STARTSWITH
campaignName
String
EQUALS
campaignStatus
Enum
EQUALS
countriesOrRegions
List of strings
countryOrRegionServin
gStateReasons
String
dailyBudget
Amount object
deleted
Boolean (True,
False)
EQUALS, IN
modificationTime
Timestamp
orgId
Int64
servingStateReasons
List of strings
servingStatus
Enum
EQUALS
supplySources
String
CONTAINS_ANY, CONTAINS_ALL
totalBudget
Amount object
Field
Type
Conditions: Operator
appName
String
EQUALS, IN, STARTSWITH
adamId
Long
EQUALS
Apple Search Ads
79
Campaign Management API 3.0
Get Ad Group Level Reports
Fetches reports on ad groups within a campaign.
Method
Endpoint
POST
https://api.searchads.apple.com/api/v3/reports/
campaigns/{campaignId}/adgroups
Example Request Payload:
{
"startTime": "2019-02-20",
"endTime": "2019-02-28",
"selector": {
"orderBy": [
{
"field": "adGroupId",
"sortOrder": "ASCENDING"
}
],
"conditions": [
{
"field": "deleted",
"operator": "EQUALS",
"values": [
"false"
]
}
],
"pagination": {
"offset": 0,
"limit": 1000
}
},
"timeZone": "UTC",
"returnRecordsWithNoMetrics": true,
"returnRowTotals": true,
"returnGrandTotals": true
}
Apple Search Ads
80
Campaign Management API 3.0
The following fields and metadata are returned as the ReportingAdGroup object. All
fields may be used with the orderBy selector except adGroupServingStateReasons.
Field
Format
Conditions: Operator
adGroupDisplayStatus
Enum: RUNNING,
ON_HOLD, PAUSED
adGroupId
Long
EQUALS, IN, STARTSWITH
adGroupName
String
EQUALS, IN, STARTSWITH
adGroupServingStateReaso
ns
List of strings
adGroupServingStatus
Enum: RUNNING,
NOT_RUNNING
EQUALS
adGroupStatus
Enum: ENABLED,
PAUSED
EQUALS
automatedKeywordsOptIn
Boolean
EQUALS
campaignId
Int64
EQUALS, IN, STARTSWITH
cpaGoal
Amount object
defaultCpcBid
Amount object
deleted
Boolean (True, False)
EQUALS, IN
endTime
Timestamp
modificationTime
Timestamp
orgId
Int64
startTime
Timestamp
Apple Search Ads
81
Campaign Management API 3.0
Get Keyword Level Reports
Fetches reports on targeting keywords within a campaign.
Method
Endpoint
POST
https://api.searchads.apple.com/api/v3/reports/
campaigns/{campaignId}/keywords
Example Request Payload:
{
"returnRowTotals": true,
"granularity": "DAILY",
"timeZone": "UTC",
"returnGrandTotals": true,
"startTime": "2020-07-01",
"selector": {
"orderBy": [
{
"field": "localSpend",
"sortOrder": "ASCENDING"
}
],
"conditions": [
{
"field": "deleted",
"operator": "IN",
"values": [
"false",
"true"
]
}
],
"pagination": {
"offset": 0,
"limit": 1000
}
},
"endTime": "2020-07-02",
"returnRecordsWithNoMetrics": true
}
Apple Search Ads
82
Campaign Management API 3.0
The following fields and metadata are returned as the ReportingKeyword object. All
fields may be used with the orderBy selector.
Field
Format
Conditions: Operator
adGroupDeleted
Boolean (True, False)
EQUALS, IN
adGroupId
Long
EQUALS, IN, STARTSWITH
adGroupName
String
bidAmount
Amount object
deleted
Boolean (True, False)
EQUALS, IN
keyword
String
EQUALS, IN, STARTSWITH
keywordDisplayStatus
Enum:
EQUALS
keywordId
Long
EQUALS, IN, STARTSWITH
keywordStatus
Enum:
matchType
Enum: EXACT, BROAD
EQUALS
modificationTime
Timestamp
Apple Search Ads
83
Campaign Management API 3.0
Get Search Terms Level Reports
Fetches reports on search terms used in a campaign.
The following fields and metadata are returned as ReportingSearchTerm object. All
fields may be used with the orderBy selector.
•
If searchTermSource is AUTO, then keywordMatchType will be AUTO.
•
If searchTermSource is TARGETED, then keywordMatchType will be either BROAD or
EXACT.
Method
Endpoint
POST
https://api.searchads.apple.com/api/v3/reports/
campaigns/{campaignId}/searchterms
Field
Format
Conditions: Operator
adGroupDeleted
Boolean (True, False)
EQUALS, IN
adGroupId
Long
EQUALS, IN, STARTSWITH
adGroupName
String
bidAmount
Amount object
deleted
Boolean (True, False)
EQUALS, IN
keyword
String
EQUALS, IN, STARTSWITH
keywordDisplayStatus
Enum: ACTIVE, PAUSED
EQUALS, IN
keywordId
Long
EQUALS, IN, STARTSWITH
keywordStatus
String
EQUALS
matchType
Enum: BROAD, EXACT
searchTermSource
Enum: AUTO, TARGETED
EQUALS, IN
searchTermText
String
EQUALS, IN, STARTSWITH
Apple Search Ads
84
Campaign Management API 3.0
Get Creative Set Level Reports
Fetches reports on Creative Sets used within a campaign.
The following metadata is returned as the ReportingCreativeSet object.
Method
Endpoint
POST
https://api.searchads.apple.com/api/v3/reports/
campaigns/{campaignId}/creativesets
Field
Format
Conditions: Operator
adGroupCreativeSetId
Long
adGroupId
Long
EQUALS, IN
campaignId
Long
creationTime
Timestamp
creativeSetId
Long
EQUALS, IN, STARTSWITH
creativeSetLanguage
String
creativeSetLanguageDi
splayName
String
creativeSetName
String
EQUALS, IN, STARTSWITH,
CONTAINS, ENDSWITH
deleted
Boolean (True, False)
EQUALS, IN
displayStatus
String
EQUALS, IN
modificationTime
Timestamp
orgId
Int64
status
String
Apple Search Ads
85
Campaign Management API 3.0
ReportingRequest Object
Field
Type
Properties
Values/Description
startTime
String
Required
yyyy-mm-dd
endTime
String
Required
yyyy-mm-dd
timeZone
Enum
Optional
ORTZ is the default time zone. The
default timezone is set during account
creation. Values can be ORTZ, UTC.
groupBy
List of
strings
Optional
Use the groupBy field to group
responses by selected dimensions. If
groupBy specifies age, gender, and
geo dimensions, then
returnRowTotals and
returnGrandTotals must be false.
Note: ageRange, countryCode,
gender, adminArea, and locality
records with fewer than 100
impressions are grouped in the API
response as “other”.
The following groupBy descriptions
include supported values per
dimension.Field to groupBy is
maximum one in the list.
Currently supported field options for
campaigns and adGroups are:
adminArea
ageRange
countryCode
countryOrRegion
deviceClass
gender
locality
See GroupBy Dimensions for selector
conditions.
Apple Search Ads
86
Campaign Management API 3.0
selector
Selector
Required
Selector consists of the following:
conditions: additional types of filters
(optional, used to further filter the data).
orderBy: required, specify how the
response should be sorted.
•
Can sort on most metadata.
•
Can sort on all groupBy dimensions.
•
Can sort on all metrics (other than
conversion rate)
•
Only one field is allowed.
pagination: optional, specify how many
records to return per page (the default is
20).
Apple Search Ads
87
Campaign Management API 3.0
granularity
String
Optional
The report data organized by hour, day,
week, and month.
Note: if granularity is specified in the
payload, then returnRowTotals and
returnGrandTotals must be false. See
the payload example with granularity in Get
Campaign Level Reports.
Allowed values:
Hourly
Daily
Weekly
Monthly
HOURLY — startTime and endTime <=
7 days apart and startTime <= 30 days in
the past.
Use:
“granularity”:
“HOURLY”,
DAILY — startTime and endTime <= 90
days apart and startTime <= 24 months
in the past.
Use:
“granularity”:
“DAILY”,
WEEKLY — startTime and endTime > 14
days and <= 365 days apart and
startTime <= 24 months in the past.
Use:
“granularity”:
“DAILY”,
MONTHLY — startTime and endTime >
3 months apart and startTime <= 24
months in the past.
Apple Search Ads
88
Campaign Management API 3.0
returnRowTotals
Boolean
Optional
Specify whether to return the total of
each row. Default is false.
Note: returnRowTotals can be used
to get the sum of the metrics but
cannot be used in conjunction with
granularity.
If granularity is specified then
returnRowTotals must be false.
returnGrandTotals
Boolean
Optional
•
Used to return total for all the rows in
the result set.
•
This can only be used if
returnRowTotals is also true.
Note: returnGrandTotals can be used
to get the sum of the metrics but cannot
be used in conjunction with
granularity.
returnRecordsWith
NoMetrics
Boolean
Optional
Specifies whether records with no stats
should also be returned. Default is
false.
Apple Search Ads
89
Campaign Management API 3.0
groupBy Dimensions
If a groupBy dimension is specified, then metadata will return groupBy dimension
fields. Grouping or filtering by age, gender, or geo, records with fewer than 100
impressions will be grouped into an "other" bucket.
Note: groupBy is not supported with keywords level reports, Creative Set level reports,
and search term level reports..
Dimension
Format
Conditions:
Operator
Description
adminArea
String
UNKNOWN
EQUALS, IN
The adminArea
dimension is a group of
States or the equivalent
according to its
associated Country. See
Search for Geo Locations
to retrieve geo locations.
In Get Ad Group Level
Reports, you must use
the adminArea
dimension with
countryCode. The
locality dimension is
optional.
ageRange
Enum: 18-24, 25-34,
35-44, 45-54, 55-64,
65\+, UNKNOWN
EQUALS, IN
The ageRange dimension
is a group of the user
demographic age ranges.
In Get Ad Group Level
Reports, the ageRange
dimension is available to
use with deviceClass.
Apple Search Ads
90
Campaign Management API 3.0
countryCode
ISO Alpha-2
UNKNOWN
EQUALS, IN
The countryCode
dimension is a group of
country codes that
indicate where the
campaign ads are served
on the App Store.
In Get Ad Group Level
Reports, the
countryCode dimension
is available to use with
deviceClass,
adminArea, and
locality.
countryOrReg
ion
String (ISO-ALPHA2
country code)
EQUALS, IN
The countryOrRegion
dimension is a group of
country and regions.
In Get Campaign Level
Reports, Get Ad Group
Level Reports, Get
Keyword Level Reports,
and Get Search Terms
Level Reports the
countryOrRegion
dimension is available to
use with deviceClass.
The countryOrRegion
dimension is available to
use in Get Creative Set
Level Reports without the
deviceClass
dimension.
deviceClass
Enum: IPHONE, IPAD,
UNKNOWN
EQUALS
The deviceClass
dimension is a group of
device classes that the
promoted application
supports.
In Get Ad Group Level
Reports, the
deviceClass dimension
is available to use with
any other dimension.
Apple Search Ads
91
Campaign Management API 3.0
gender
Enum: M, F, UNKNOWN
EQUALS
The gender dimension is
a group of user-
demographic genders.
In Get Ad Group Level
Reports, the gender
dimension is available to
use with deviceClass.
locality
String
UNKNOWN
EQUALS, IN
The locality
dimension is the city or
the equivalent according
to its associated
adminArea. See Search
for Geo Locations to
retrieve geo locations.
In Get Ad Group Level
Reports, the locality
dimension with higher
dimensions is available to
use with countryCode
and adminArea.
Apple Search Ads
92
Campaign Management API 3.0
ReportingResponse Object
The ReportingResponse Body is a container for returned data. The
ReportingResponse Body also includes pagination details that refer to the rows in the
ReportingResponse object.
SpendRow and ExtendedSpendRow Objects
Provides tap, conversion, and monetary totals.
Expressed as SpendRow in the response, which is the same as ExtendedSpendRow
except with the date attribute. See Reporting Response.
Field
Type
Properties
Description
avgCPA
Amount
object
Read Only
Average cost-per-acquisition (CPA) is total
spend divided by the number of installs
received within a period.
avgCPT
Amount
object
Read Only
CPT (cost-per-tap) is treated as the same
metric as CPC (cost-per-click). Ratio is
spend over taps.
conversionRate
Double
Read Only
The total number of conversions received
within a period divided by total number of
taps within the same period.
date
String
Read Only
Date range of the report. Format is MM-
DD-YYYY HH.
Note: this attribute is in
ExtendedSpendRow only.
impressions
Double
Read Only
The number oftimes your ad appeared in
AppStore search results within the
reporting time period.
installs
Enum
Read Only
The total number of downloads or
redownloads resulting from an ad within
the reporting period. Apple SearchAds
installs are attributed within a 30-day tap-
through window.
latOnInstalls
Double
Read Only
Installs from users who have enabled Limit
Ad Tracking (LAT) on their device.
latOffInstalls
Double
Read Only
Installs from users who have not enabled
Limit Ad Tracking (LAT) on their device.
Apple Search Ads
93
Campaign Management API 3.0
localSpend
Double
Read Only
The calculated sum of cost associated
with each impression served. Spend is
measured in the currency used in the
campaign.
newDownloads
Double
Read Only
App downloads from new users who have
never before installed yourapp.
redownloads
Double
Read Only
Occurs when a user downloads your app,
deletes it, and downloads the same app
again following a tap on an ad on the
AppStore, or downloads the same app to
an additional device.
taps
Number
Read Only
The number oftimes your ad was tapped
by users within the reporting time period.
ttr
Double
Read Only
The tap-through rate (TTR) is the number
oftimes your ad was tapped by customers
divided by the total impressions your ad
received.
Apple Search Ads
94
Campaign Management API 3.0
Row Object
The report metrics organized by time granularity."
KeywordInsights Object
KeywordInsights help you apply your bid strategy to exact match keywords and
similar keywords used in broad match. Use KeywordInsights to optimize campaign
performance though your Search Match discovery campaigns.
Field
Type
Description
granularity
ExtendedSpendRow
object
See ReportingRequest Object for details.
metadata
MetaDataObject
Reporting request data.
other
boolean
Corresponds to targeting dimensions criteria
that fall below a threshold of fewer than 100
demographic dimensions and fewer than 10
for search terms returned in reports.
If true, the corresponding dimensions are
null.
total
SpendRow
The tap, conversion, and monetary totals.
Expressed as SpendRow, which is the same
as ExtendedSpendRow except it also
includes the date attribute.
insights
InsightsObject
The bid recommendations according to
currency type. Includes range and amount.
See KeywordInsights and Get Keyword Level
Reports
Field
Type
Description
bidRecommendation
KeywordBidRecommendati
on Object
The bid recommendation
for a keyword.
Apple Search Ads
95
Campaign Management API 3.0
KeywordBidRecommendation Object
A KeywordBidRecommendation is an indicator that varies over time to help you
incrementally increase the likelihood of your ad showing in searches on App Store
Connect. A KeywordBidRecommendation changes once per day and should not be
considered a representation of a bid floor or ceiling. If there is an existing bid on a
keyword, the bid recommendation is always greater.
Field
Type
Description
bidMax
Money Object
The maximum bid amount
indicator according to
currency type.
bidMin
Money Object
The minimum bid amount
indicator according to
currency type.
Apple Search Ads
96
Campaign Management API 3.0
Document Revision History
Date
Notes
March 2021
Initial version.
Apple Search Ads
97
Campaign Management API 3.0
Apple Inc.
Copyright © 2021 Apple Inc.
All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or
by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written
permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store
documentation on a single computer or device for personal use only and to print copies of documentation
for personal use provided that the documentation contains Apple’s copyright notice. No licenses, express
or implied, are granted with respect to any of the technology described in this document. Apple retains all
intellectual property rights associated with the technology described in this document. This document is
intended to assist application developers to develop applications only for Apple-branded products.
Apple Inc.
Ad Platforms
One Apple Park Way
Cupertino, CA 95014, USA
APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT
TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR
PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE
ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE
LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING
FROM ANY DEFECT, ERROR OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of
such damages. Some jurisdictions do not allow the exclusion of implied warranties or liability, so the
above exclusion may not apply to you.
Apple Search Ads
98
Campaign Management API 3.0
