Integrating your Apple Search Ads accounts
Connect your Apple Search Ads accounts to bring App Store search campaign performance — including ad-level reporting with Creative and Custom Product Page breakdowns — into Clarisights alongside your other marketing channels.
At a glance
| Authentication | OAuth 2.0 with ES256 JWT (public/private key pair generated by Clarisights) |
| Permissions needed | API Account Read Only or API Account Manager role on each Apple Search Ads org. Account Admin alone is not sufficient. |
| Account discovery | Automatic — every org (account) the API user has access to is discovered after credentials are validated |
| Data freshness | Hourly |
| Lookback window | Apple's standard reporting window (rolling) |
| Backfill on connect | Historical data available since the account was created |
| Timezone | Account-level (UTC by default; ORTZ if configured on the Apple side) |
| Currency | Account native currency (auto-converted via Currency Conversion) |
| Levels supported | Account (Org) · Campaign · Ad Group · Keyword · Ad |
| Limited rollout | No |
Prerequisites
An active Apple Search Ads account in the Apple Search Ads UI
A user on that account with the API Account Read Only or API Account Manager role. Account Admin alone will not work — you may need to invite or create a dedicated API user.
Access to the Apple Search Ads Account Settings → API page so you can paste a public key and capture the resulting
clientId,teamId, andkeyId
Steps to Connect
Step 1 — Add an API user in Apple Search Ads
In your Apple Search Ads account, invite or create a user with the API Account Read Only role (API Account Manager also works). This user is the one whose credentials Clarisights will use.
Common error — "Insufficient permissions" when fetching accounts: The user is an Account Admin but does not have the API role. Re-open the user in Apple Search Ads and explicitly assign API Account Read Only or API Account Manager.
Step 2 — Generate a public key in Clarisights
In Clarisights, open the Apple Search Ads integration page and enter the API user's username and email. Clarisights will generate a public/private key pair for this user. The private key never leaves Clarisights; only the public key is shown back to you.
Step 3 — Upload the public key to Apple Search Ads
Hover over the generated key in Clarisights and click to copy it. Make sure you include the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- lines with their dashes.
In Apple Search Ads, go to Account Settings → API and paste the key into the Public Key field, then click Save.
Apple will display three values above the public key field:
clientId
teamId
keyId
Common error — "Invalid public key" on Apple's side: Most often caused by missing the BEGIN/END lines or pasting only the body of the key. Copy the full block (including the dashes) and try again.
Step 4 — Paste credentials back into Clarisights
Return to the Apple Search Ads integration page in Clarisights and paste the clientId, teamId, and keyId into the corresponding fields, then click Update. Clarisights validates the credentials by issuing a JWT and exchanging it for an access token, and then automatically discovers every org the API user has access to.
Common error — "Accounts couldn't be fetched for this user": One of
clientId,teamId, orkeyIdis wrong, or Apple hasn't yet propagated the public key. Wait a minute, double-check the three values, and click Update again.
Step 5 — Select the orgs (accounts) to connect
Clarisights will show every org the API user can access. Select the ones you want to bring into Clarisights and confirm. All selected orgs are then activated and start syncing.
Verify the connection
Go to Integrations → Apple Search Ads. Each connected org should show as Active with the correct currency and timezone.
First report data appears within 1–2 hourly sync cycles after activation.
Quick start: open a new report, choose Apple Search Ads as the data source, and add Account · Campaign · ASA: Impressions · ASA: Taps · ASA: Cost.
Data available
Hierarchy
How Apple Search Ads' native levels map to the standard Clarisights levels:
Native level (Apple Search Ads) | Clarisights level |
Org | Account |
Campaign | Campaign |
Ad Group | Ad Group |
Keyword (targeted) | Keyword (sub-level under Ad Group) |
Ad (with Creative + Custom Product Page) — added Q1 2026 | Ad |
Both the Keyword and Ad branches sit under Ad Group. You can pivot reports either by Keyword or by Ad (with Creative and Custom Product Page breakdowns) depending on what you want to analyse.
Dimensions
Dimension | Level | Description |
Adam ID | Campaign | The ID of the app being advertised |
Total Budget | Campaign | Lifetime campaign budget |
Daily Budget | Campaign | Daily spend cap |
Ad Group Bid | Ad Group | Default bid for the ad group |
Unique Keyword | Keyword | Super dimension. Strips match type so you can see aggregate performance for a keyword across multiple ad groups and match types. Not available natively in Apple Search Ads. |
Keyword Match Type | Keyword | Broad, Exact, or Search Match |
Ad Name | Ad | The name of the ad |
Ad ID | Ad | Unique identifier for the ad |
Configured Status | Ad | Status set by the advertiser (e.g., ENABLED, PAUSED) |
Serving Status | Ad | Current serving status of the ad |
Serving State Reasons | Ad | Reasons for the current serving state, when applicable |
Creative Name | Ad | Name of the creative associated with the ad |
Creative Type | Ad | Type of creative (e.g., custom product page) |
Creative State | Ad | Current state of the creative |
Product Page Name | Ad | Name of the custom product page linked to the ad |
Product Page State | Ad | Current state of the product page |
Product Page Deep Link | Ad | Deep link URL for the product page |
Italicised dimensions are Clarisights super dimensions — derived in Clarisights and not directly available in the Apple Search Ads UI.
Note on "default ad": ad groups that serve without an explicit ad object will show a default ad entry in reports. This is Apple's standard behaviour for ad groups using the default App Store listing.
Metrics
Core performance
Metric | Description |
ASA: Impressions | The number of times your ad appears in App Store search results within the reporting period. |
ASA: Taps | The number of times users tap your ad within the reporting period. |
ASA: Cost | The total spend within the reporting period. |
ASA: Conversions | The total number of conversions. |
Derived rates
Metric | Description |
ASA: Tap Through Rate | Taps divided by impressions in the same window. |
ASA: Conversion Rate | Conversions divided by taps in the same window. |
ASA: Avg CPT | Average cost-per-tap (spend / taps). |
ASA: Avg CPA | Average cost-per-acquisition (spend / installs). |
Installs
Metric | Description |
ASA: Installs | Total new downloads or re-downloads attributed to an ad. Apple uses a 30-day tap-through window. |
ASA: Installs (LAT Disabled) | Installs from users who do not have Limit Ad Tracking enabled. |
ASA: Installs (LAT Enabled) | Installs from users who do have Limit Ad Tracking enabled. |
ASA: New Downloads | Downloads from users who never previously installed your app. |
ASA: Re-Downloads | Re-installs from users who previously had your app. |
Pre-orders (added Q1 2026)
Metric | Description |
ASA: Pre-Orders Placed (Tap) | Pre-orders placed via tap-through conversions. |
ASA: Pre-Orders Placed (View) | Pre-orders placed via view-through conversions. |
Can't find a dimension or metric you need? Email support@clarisights.com.
Limitations & known constraints
Permission scope: the API user must have API Account Read Only or API Account Manager. Account Admin without an explicit API role is rejected by Apple's API.
Public key rotation: Apple Search Ads API keys are valid for up to 180 days. Clarisights regenerates the JWT automatically within that window, but if the key itself is revoked or rotated on Apple's side you'll need to repeat steps 2–4.
Default ad rows: ad groups that don't have an explicit ad object surface as default ad in ad-level reports. This is by design from Apple.
2021 OAuth migration: Apple deprecated the older certificate-based authentication in May 2021. New connections must use the public/private key + JWT flow described above. Pre-existing Clarisights connections that used the legacy certificate flow have all been migrated; no data was lost in that migration. See Apple's OAuth for the Apple Search Ads API reference for background.
Reporting delay: most metrics are available within an hour but some attribution metrics can take up to 24 hours to fully reconcile.
Operating notes
Refresh schedule: data is pulled hourly. Account-list refresh runs once a day to detect new orgs the API user has been granted access to.
Multi-account behaviour: a single API user can authorise multiple orgs. Each org gets its own access token in Clarisights, so a single expiring token can never block other accounts.
Currency conversion: amounts are pulled in the org's native currency and converted to your reporting currency by Clarisights.
Credential rotation: the JWT is rotated automatically every ~180 days. The underlying public/private key pair only needs to be regenerated if the keypair is revoked on Apple's side or you reset credentials in Clarisights.
Adding a new org later: grant the existing API user access in Apple Search Ads, then re-open the integration in Clarisights — the new org will appear in the account-selection list at the next account refresh.
Need help?
When contacting support from the in-app messenger, please include:
The API user's email and the affected org name / ID (Integrations → Apple Search Ads)
The exact error message or a screenshot
The step where the issue occurred
When the issue started, and whether it was working previously