Apple Search Ads data integration solution

Last updated 10/05/2026

Last updated: 2022-07-18

1. Integration plan overview

tip

Note that data generated by third-party data integration counts toward the cluster's data consumption

Summary

This document describes how to send Apple Search Ads data back to Agentic Engine (hereinafter the AE system). This solution supports:

Sending back aggregated metric data through the Apple Search Ads Report API, including impression, click, install, and cost metrics

Process

The process for connecting Apple Search Ads data is as follows:

Create a user with API permissions (skip this step if such a user already exists)
Generate a private key and a public key, log in to the Apple Search Ads dashboard as the user with API permissions, upload the public key, and provide the following to ThinkingAI staff:
1. client_id
2. team_id
3. key_id
4. The private key file
Determine the data dimensions, metric types, pull frequency, and time range to pull
ThinkingAI staff complete the data pull development
Build dashboards and reports in the AE backend, and complete data validation

2. Preparation before integration

Before you pull ASA data, you first need to generate an Access Token. The process consists of the following steps:

Create a user with API access
Generate a private key and a public key, and upload the public key to the ASA dashboard
Create a client secret
Request an access token

2.1 Create a user with API access

An admin account can create a user with API permissions as follows:

Go to Apple Search Ads UI and log in with the admin account
Go to Account Settings > User Management
Click Invite Users to invite a user in your ASA organization
In the User Details section, enter the user's name and Apple ID
In the User Access and Role section, select a user role with API access
Click Send Invite to send the invitation email. The invited user receives an email with a secure code. The user clicks the Apple URL in the email and enters the secure code to activate the account

2.2 Generate a private key and a public key

tip

If you use Windows, download and install OpenSSL

Run the following command on the command line to generate a private key (the private key file is private-key.pem)

openssl ecparam -genkey -name prime256v1 -noout -out private-key.pem

Then, in the same directory, run the following command to generate a public key (the public key file is public-key.pem)

openssl ec -in private-key.pem -pubout -out public-key.pem

Go to Apple Search Ads UI, select Account Settings > API, and copy the public key into the Public Key section. After you click Save, you can see clientId, teamId, and keyId above the Public Key section. The following is sample data:

clientId SEARCHADS.aeb3ef5f-0c5a-4f2a-99c8-fca83f25a9
teamId SEARCHADS.hgw3ef3p-0w7a-8a2n-77c8-scv83f25a7
keyId a273d0d3-4d9e-458c-a173-0db8619ca7d7

2.3 Provide the following information to ThinkingAI staff

Next, provide the following information to ThinkingAI staff

client_id
team_id
key_id
The private key file (private-key.pem) that corresponds to the public key configured in the ASA dashboard

ThinkingAI staff will then create the Access Token.

3. Data pull

Basic interface information

Interface	API type	Productized	Data granularity	Attribution	Cost	Revenue	Impressions	Clicks	Conversions
Reporting API	Pull	No	Aggregated data		Yes		Yes	Yes	Yes

3.1 Data pull rules

The Apple Search Ads Reporting API provides data reports at multiple levels. Currently, the AE system supports pulling data at the following levels:

Campaign-Level Reports: get hourly data reports at the campaign level

Ad Group-Level Reports: get hourly data reports at the ad group level within a campaign

Keyword-Level Reports: get hourly data reports at the keyword level within a campaign

Creative Set-Level Reports: get daily data reports at the creative set level within a campaign

By default, we pull report data at all four levels in a single data pull task

3.2 API parameters

Time:
- Time range: data is pulled by day
- Time granularity: aggregated by day or by hour (by hour)
- Time zone: you can choose the UTC time zone or the time zone set in the ASA dashboard

3.3 Ingestion rules

3.3.1 Campaign level

Campaign-level data is aggregated data, so we use a fixed value as its user identifier. You can think of all the data as attached to one virtual user
The date field in the data, that is, the date of the data, is set as the #event_time of the aggregated data
The event name for Campaign-level data is asa_campaign_level_data
The following are the ingested fields at the Campaign level

------------------------Dimension fields------------------------
campaignId
campaignName
deleted
campaignStatus
app.adamId
servingStatus
servingStateReasons
countriesOrRegions
modificationTime
totalBudget.amount
totalBudget.currency
dailyBudget.amount
dailyBudget.currency
displayStatus
supplySources
adChannelType
orgId
countryOrRegionServingStateReasons
billingEvent
------------------------Metric fields------------------------
impressions
taps
installs
newDownloads
redownloads
latOnInstalls
latOffInstalls
ttr
avgCPA.amount
avgCPA.currency
avgCPT.amount
avgCPT.currency
avgCPM.amount
avgCPM.currency
localSpend.amount
localSpend.currency
conversionRate

3.3.2 Ad Group level

Ad Group-level data is aggregated data, so we use a fixed value as its user identifier. You can think of all the data as attached to one virtual user
The date field in the data, that is, the date of the data, is set as the #event_time of the aggregated data
The event name for Ad Group-level data is asa_adgroup_level_data
The following are the ingested fields of Ad Group-level data

------------------------Dimension fields------------------------
campaignId
adGroupId
adGroupName
adGroupDisplayStatus
adGroupStatus
adGroupServingStatus
adGroupServingStateReasons
deleted
cpaGoal
orgId
modificationTime
automatedKeywordsOptIn
pricingModel
defaultBidAmount.amount
defaultBidAmount.currency
------------------------Metric fields------------------------
impressions
taps
installs
newDownloads
redownloads
latOnInstalls
latOffInstalls
ttr
avgCPA.amount
avgCPA.currency
avgCPT.amount
avgCPT.currency
avgCPM.amount
avgCPM.currency
localSpend.amount
localSpend.currency
conversionRate

3.3.3 Keywords level

Keywords-level data is aggregated data, so we use a fixed value as its user identifier. You can think of all the data as attached to one virtual user
The date field in the data, that is, the date of the data, is set as the #event_time of the aggregated data
The event name for Keywords-level data is asa_keyword_level_data
The following are the ingested fields of Keywords-level data

------------------------Dimension fields------------------------
keywordId
keywordStatus
matchType
deleted
keywordDisplayStatus
adGroupId
adGroupDeleted
------------------------Metric fields------------------------
impressions
taps
installs
newDownloads
redownloads
latOnInstalls
latOffInstalls
ttr
avgCPA.amount
avgCPA.currency
avgCPT.amount
avgCPT.currency
localSpend.amount
localSpend.currency
conversionRate

3.3.4 Creative Set level

Creative Set-level data is aggregated data, so we use a fixed value as its user identifier. You can think of all the data as attached to one virtual user
The date field in the data, that is, the date of the data, is set as the #event_time of the aggregated data
The event name for Creative Set-level data is asa_creative_level_data
The following are the ingested fields of Creative Set-level data

------------------------Dimension fields------------------------
creativeSetId
creativeSetName
displayStatus
creativeSetLanguageDisplayName
deleted
status
orgId
campaignId
adGroupId
adGroupCreativeSetId
creationTime
modificationTime
countryOrRegion
adFormat
------------------------Metric fields------------------------
impressions
taps
installs
newDownloads
redownloads
latOnInstalls
latOffInstalls
ttr
avgCPA.amount
avgCPA.currency
avgCPT.amount
avgCPT.currency
localSpend.amount
localSpend.currency
conversionRate

4. Data integration configuration template

After reading the documentation above, we recommend that you fill in the following template and send it to your customer success manager at ThinkingAI. We will pull the Apple Search Ads data based on this template:

Data interface: Apple Search Ads Report API
---------
AE customer company name: XXX
AE customer project name: XXX
AE project environment: XXX (SAAS/on-premises)
AE customer project app_id: XXX
AE data receiving URL push_url: XXX
---------
keyId: XXX
clientId: XXX
teamId: XXX
orgId list: XXX
Time zone: [UTC/ASA] time zone configured in the dashboard
Time granularity: [day/hour] (Note: creative set-level reports don't support hourly data pulls, only daily pulls)
Time range for historical data pull: yyyy/mm/dd - yyyy/mm/dd
Scheduled pull: pull the previous day's data at X:00 every day

5. Integration testing

View the following events on the Events page in the AE backend:

asa_campaign_level_data: campaign level, with more dimensions and metrics
asa_adgroup_level_data: ad group level, with finer analysis granularity
asa_keyword_level_data: delivery performance data of keywords
asa_creative_level_data: ad creative level, with finer analysis granularity

Was this page helpful?

1. Integration plan overview​

Summary​

Process​

2. Preparation before integration​

2.1 Create a user with API access​

2.2 Generate a private key and a public key​

2.3 Provide the following information to ThinkingAI staff​

3. Data pull​

3.1 Data pull rules​

3.2 API parameters​

3.3 Ingestion rules​

3.3.1 Campaign level​

3.3.2 Ad Group level​

3.3.3 Keywords level​

3.3.4 Creative Set level​

4. Data integration configuration template​

5. Integration testing​