Advanced Analytica Advanced Analytica: IBOM
← All connectors
Apple Ads logo

Source connector

Apple Ads

Set up Apple Ads as a source and move its data into your chosen destination.

Version 1.1.24 community alpha

Apple Ads (Apple Search Ads)

Use this page to set up the Apple Ads source connector and find reference information.

:::warning Apple has deprecated the Apple Ads Campaign Management API used by this connector. Apple plans to sunset it on January 26, 2027.

Apple recommends the Apple Ads Platform API as its replacement. This connector still calls Campaign Management API v5. :::

Prerequisites

  • An Apple Ads account with an administrator who can invite users with API permissions.
  • Your Apple Ads organization id (orgId), shown in the Apple Ads UI. Each Airbyte source syncs data for one orgId.
  • An Apple Ads API user with an OAuth client ID and client secret. See Step 1 below.
  • OpenSSL and a script or library that can sign an ES256 JSON Web Token (JWT). Apple’s OAuth guide includes a Python example.

Set up the connector

Step 1: Create the API user and credentials

The connector authenticates to the Apple Ads Campaign Management API using the OAuth 2 client credentials grant.

Apple gives you a client ID when you upload a public key. You create the client secret and sign it with the matching private key.

Apple’s full guide is at Implementing OAuth for the Apple Ads API. Follow these steps:

  1. Sign in to Apple Ads as an account administrator. Select the account from the Users menu, then go to Account Settings → User Management.

  2. Click Invite Users. In User Access and Role, select an API role, such as API Account Manager or API Account Read Only, then send the invite. The invited user activates the account from the invitation email.

  3. As the API user, generate a private key and extract its public key:

    openssl ecparam -genkey -name prime256v1 -noout -out private-key.pem
    openssl ec -in private-key.pem -pubout -out public-key.pem
  4. In Apple Ads, go to Account Settings → API. Paste the contents of public-key.pem into Public Key, then click Save. Apple then shows your clientId, teamId and keyId.

  5. Create the client secret. This JWT must use the ES256 algorithm and be signed with private-key.pem. Use these values:

    • Header: Set alg to ES256 and kid to your keyId.
    • Payload: Set sub to your clientId and iss to your teamId. Set aud to https://appleid.apple.com and iat to the current UNIX timestamp. Set exp to a UNIX timestamp less than 180 days after iat.

    The encoded JWT is the value for Client Secret in Airbyte. Keep the private key secure. You need it whenever you create a new client secret.

:::note Apple accepts a client secret for up to 180 days. Before it expires, create a new one and update the source’s Client Secret field.

Otherwise, syncs fail with a 401 error. :::

Step 2: Set up the source in Airbyte

  1. In Airbyte, click Sources, then click + New source.
  2. Select Apple Ads from the Source type dropdown, then enter a source name.
  3. For Org Id, enter your Apple Ads organization’s orgId. You can find it in the Apple Ads UI.
  4. For Client Id, enter the clientId from Step 1. For Client Secret, enter the signed JWT you created in Step 1.
  5. For Start Date and End Date, enter dates in YYYY-MM-DD format. Start Date is required. If End Date is blank, Airbyte syncs through today. Apple serves daily reports for the last 90 days only (ReportingRequest). Set Start Date within that window. If Start Date is earlier, the report streams fail with a configuration error.
  6. For Time Zone, select UTC (Coordinated Universal Time) or ORTZ (Organization Time Zone). The default is UTC.
  7. For Lookback Window, enter a value from 1 to 30. Apple Ads applies a 30-day attribution window. The default of 30 captures late-attributed conversions during each incremental sync. Lower values shorten incremental syncs but may miss late attributions.
  8. (Optional) For Number of Workers, enter a value from 1 to 20. The default is 2. This value controls how many partitions, either campaigns or ad groups, the connector fetches in parallel. For accounts with many campaigns or ad groups, increase it to shorten sync time. This increases API request volume.
  9. Click Set up source.

The Exponential Backoff Factor and Token Refresh Endpoint fields are hidden in the UI. If needed, set them through the API. See backoff_factor and token_refresh_endpoint in the parameter table below.

Supported sync modes

The Apple Ads source connector supports these sync modes:

The object streams (campaigns, adgroups, keywords and ads) support full refresh only. Daily report streams also support incremental syncs, using date as the cursor.

Supported streams

The Apple Ads source connector provides the following streams. See the Apple Ads API reference for complete schema and field details.

Object streams

  • campaigns: all campaigns in the organization.
  • adgroups: ad groups across all campaigns.
  • keywords: targeting keywords across all ad groups.
  • ads: ads across all ad groups.

Daily report streams

The connector requests daily reports from Apple’s Reports API, grouped by countryOrRegion. Apple supports hourly, daily, weekly and monthly granularity. This connector requests daily granularity only.

:::note Report streams use date as the cursor field and don’t declare a primary key. Each row is separated by countryOrRegion, which the connector provides as countryorregion.

To deduplicate in the destination, use the entity ID (campaignId, adGroupId, keywordId or adId), date and countryorregion. :::

If Apple reports that a campaign doesn’t contain keywords, keywords_report_daily skips it instead of failing the sync.

Performance

  • Apple access tokens last one hour. When Apple returns 401 Unauthorized, the connector requests a new access token and retries.
  • Apple’s API enforces rate limits and recommends exponential retry. The connector retries 429 rate-limit responses with exponential backoff. It also retries 500, 502, 503 and 504 server errors with exponential backoff. The API-only backoff_factor sets the delay multiplier for report streams.
  • For accounts with many campaigns or ad groups, increase Number of Workers. This fetches partitions in parallel and reduces sync time.
  • Apple Ads applies a 30-day attribution window. Reducing Lookback Window below 30 days shortens incremental syncs but may miss late conversions.

Troubleshooting

  • Apple Ads rejected the credentials (401) even after refreshing the access token: The client secret has expired, or the API user has lost access. Create a new client secret as described in Step 1. Then update the Client Secret field.
  • Apple Ads denied access (403) for org ...: The API user doesn’t have an API role for the organization in Org Id. Ask an account administrator to assign the user an API role for that organization. For example, assign API Account Manager or API Account Read Only.
  • Apple Ads rejected the report request (400): A report stream requested a date that Apple no longer serves. Apple only serves daily reports from the last 90 days. Set Start Date within the last 90 days. A stream’s saved cursor also falls outside this window if it hasn’t synced for longer. In that case, refresh the stream.
  • Apple Ads returned 404 for ...: A campaign or ad group was probably deleted during the sync. Run the sync again.

IP allow list

If you use Airbyte Cloud and restrict access to specific IPs, add the Airbyte Cloud IP addresses to your organization’s allow list.

Reference

This connector uses the Apple Ads Campaign Management API v5. Airbyte calls https://api.searchads.apple.com/api/v5. It sends the selected Apple Ads organization in the X-AP-Context header as orgId={orgId}.

For programmatic configuration, use these parameter names:

FieldRequiredDescription
org_idYesApple Ads organization ID to sync.
client_idYesOAuth client ID for the Apple Ads API user.
client_secretYesOAuth client secret for the Apple Ads API user.
start_dateYesEarliest report date to sync, in YYYY-MM-DD format.
end_dateNoLatest report date to sync, in YYYY-MM-DD format. If omitted, Airbyte syncs through the current date.
timezoneNoReporting time zone. Valid values are UTC and ORTZ; defaults to UTC.
lookback_windowNoNumber of days to sync again on incremental report streams. Valid values are 1 through 30. Defaults to 30.
backoff_factorNoExponential retry delay factor for temporary Apple Ads API errors on the report streams. Valid values are 1 through 20. Defaults to 5. Hidden in the UI.
token_refresh_endpointNoOAuth token endpoint. Defaults to Apple’s token endpoint with the client_credentials grant and searchadsorg scope. Hidden in the UI.
num_workersNoNumber of concurrent workers for partitioned streams. Valid values are 1 through 20. Defaults to 2.

Changelog

Expand to review
VersionDatePull RequestSubject
1.1.242026-11-1091348Update dependencies
1.1.232026-11-0390483Update dependencies
1.1.222026-10-2689712Report expired client secrets and rejected report dates as configuration errors, explain missing API roles, show Apple’s message on other API errors, add biddingStrategy, targetCpa and automatedKeywordsRequired, make Time Zone and Token Refresh Endpoint optional, hide Exponential Backoff Factor and Token Refresh Endpoint in the UI, and update the base image
1.1.212026-10-2089117Update dependencies
1.1.202026-10-1388507Update dependencies
1.1.192026-10-0687754Update dependencies
1.1.182026-09-2987075Update dependencies
1.1.172026-09-2286540Update dependencies
1.1.162026-09-1585951Update dependencies
1.1.152026-09-0884472Update dependencies
1.1.142026-08-1183830Update dependencies
1.1.132026-08-0483353Update dependencies
1.1.122026-07-2882825Update dependencies
1.1.112026-07-2182340Update dependencies
1.1.102026-07-1481722Update dependencies
1.1.92026-06-3080968Update dependencies
1.1.82026-06-2380356Update dependencies
1.1.72026-06-1679764Update dependencies
1.1.62026-06-0979235Update dependencies
1.1.52026-06-0278565Update dependencies
1.1.42026-05-1278029Refresh expired OAuth access tokens before retrying failed Apple Ads API requests
1.1.32026-05-0576973Fix ads_report_daily broken incremental sync, remove incorrect keyword error predicate, and enable concurrent partition processing to reduce heartbeat timeouts
1.1.22026-04-2877141Update dependencies
1.1.12026-04-2176507Update dependencies
1.1.02026-04-1469218Add two new streams - ads & ads_report_daily
1.0.112026-03-3175879Update dependencies
1.0.102026-03-2475015Update dependencies
1.0.92026-03-1074512Update dependencies
1.0.82026-03-0374180Update dependencies
1.0.72026-02-0672690Update dependencies
1.0.62026-01-2071888Update dependencies
1.0.52026-01-1471435Update dependencies
1.0.42025-12-1870810Update dependencies
1.0.32025-11-2569891Update dependencies
1.0.22025-11-1869577Update dependencies
1.0.12025-10-2968392Update dependencies
1.0.02025-10-2166557Update adgroups_report_daily and keywords_report_daily to use global state cursor
0.8.102025-10-1467979Update dependencies
0.8.92025-10-0767173Update dependencies
0.8.82025-09-3066272Update dependencies
0.8.72025-09-1566197Update to CDK v7
0.8.62025-08-2365312Update dependencies
0.8.52025-08-0964663Update dependencies
0.8.42025-07-1963453Update dependencies
0.8.32025-07-1263087Update dependencies
0.8.22025-06-1661626Update dependencies
0.8.12025-05-2960627Update dependencies
0.8.02025-05-1360241Add token refresh endpoint override configuration override
0.7.92025-05-1059888Update dependencies
0.7.82025-05-0359308Update dependencies
0.7.72025-04-2658712Update dependencies
0.7.62025-04-1958275Update dependencies
0.7.52025-04-1257658Update dependencies
0.7.42025-04-0557158Update dependencies
0.7.32025-03-2956573Update dependencies
0.7.22025-03-2556383add countryorregion to report schemas
0.7.12025-03-2256109Update dependencies
0.7.02025-03-2055839countryOrRegion metadata info included
0.6.02025-03-2055785Add timezone config parameter
0.5.12025-03-0855366Update dependencies
0.5.02025-03-0755210Remove primary keys
0.4.32025-03-0154873Update dependencies
0.4.22025-02-2554646Fix paginator settings for incremental report streams
0.4.12025-02-2254284Update dependencies
0.4.02025-02-2154170Externalize backoff factor and lookback window configurations
0.3.32025-02-1853920Update dependencies
0.3.22025-02-1453685Fix granularity to daily
0.3.12025-02-0853422Update dependencies
0.3.02025-02-0553136Update API version to V5
0.2.92025-02-0152899Update dependencies
0.2.82025-01-2552197Update dependencies
0.2.72025-01-1851745Update dependencies
0.2.62025-01-1151249Update dependencies
0.2.52024-12-2850469Update dependencies
0.2.42024-12-2150155Update dependencies
0.2.32024-12-1449561Update dependencies
0.2.22024-12-1247751Update dependencies
0.2.12024-11-1248440Set authentication grant_type to client_credentials
0.2.02024-10-0546288Migrate to Manifest-only
0.1.202024-09-2946153Update dependencies
0.1.192024-09-2245803Update dependencies
0.1.182024-09-1545474Update dependencies
0.1.172024-09-0845326Update dependencies
0.1.162024-09-0145013Update dependencies
0.1.152024-08-2544654Update dependencies
0.1.142024-08-1844322Update dependencies
0.1.132024-08-1343912Update dependencies
0.1.122024-08-1143514Update dependencies
0.1.112024-08-0443195Update dependencies
0.1.102024-07-2842660Update dependencies
0.1.92024-07-2142225Update dependencies
0.1.82024-07-1441722Update dependencies
0.1.72024-07-1141546Update dependencies
0.1.62024-07-1040832Update dependencies
0.1.52024-06-2640364Update dependencies
0.1.42024-06-2340186Update dependencies
0.1.32024-06-0538967[autopull] Upgrade base image to v1.2.1
0.1.22024-05-3038502[autopull] base image + poetry + up_to_date
0.1.12023-07-1128153Fix manifest duplicate key (no change in behavior for the syncs)
0.1.02023-04-1819557Initial release with campaigns, adgroups & keywords streams (base and daily reports)
Advanced Analytica

Most businesses are sitting on information they can’t use at speed. The people who hold it are busy, and when they leave, the knowledge goes with them. The documents are static, and the processes around them weren’t designed for AI.

Advanced Analytica works with these businesses to turn that information into structured data assets. Once they're integrated, AI systems can govern it, and the business can use it. We bring in the strategy, the specification and the AI skills to rework how the business operates.

MOVE FAST. STAY SAFE.