Apple Ads (formerly Apple Search Ads) is Apple's advertising platform for promoting iOS, iPadOS, macOS, and tvOS apps across the App Store. The Apple Ads Campaign Management API lets developers, agencies, and third-party platforms programmatically create and manage campaigns, ad groups, ads, targeting keywords, negative keywords, and creative sets, and retrieve performance reports at the campaign, ad group, keyword, and ad levels.
Power end-to-end data operations for your Apple Ads API with Nexla. Our bi-directional Apple Ads connector is purpose-built for Apple Ads, making it simple to ingest data, sync it across systems, and deliver it anywhere — all with no coding required. Nexla turns API-sourced data into ready-to-use, reusable data products and makes it easy to send data to Apple Ads or any other destination. With comprehensive monitoring, lineage tracking, and access controls, Nexla keeps your Apple Ads workflows fast, secure, and fully governed.
Features
Type: API
SourceDestination
Seamless API Integration: Connect to any endpoint as source or destination without coding, with automatic data product creation
Visual Composition & Chaining: Build complex integrations using visual templates, chain API calls, and compose workflows with data validation and filtering
API Proxy: Expose curated slices of your data securely with a secure and customizable API proxy that validates and transforms data on the fly
Request optimization with intelligent batching, retry, and caching to minimize API calls and costs
The Apple Ads Campaign Management API uses OAuth 2.0 with a server-to-server (two-legged) client credentials flow. Each authenticated request is signed with an access token issued by Apple's identity service at https://appleid.apple.com/auth/oauth2/token. To obtain an access token, you must register an API client in your Apple Ads account, generate a private/public key pair, upload the public key to Apple Ads, and use the private key to mint a signed JWT that serves as the OAuth2 client secret.
The credential in Nexla requires the following four values:
Client ID — Issued by Apple Ads when you upload your public key.
Client Secret (JWT) — A JWT signed with your private key (ES256). This value replaces the static client secret used in traditional OAuth2 flows.
Apple Ads OAuth2 uses an asymmetric key pair. The private key stays on your systems and is used to sign the client secret JWT. The public key is uploaded to Apple Ads.
On a machine with OpenSSL installed, generate an Elliptic Curve (P-256) private key in PEM format. For example:
Store the private key (private-key.pem) in a secure secret manager. It will be used to sign the client secret JWT and cannot be regenerated from the public key.
Apple recommends ECC with the P-256 curve (algorithm ES256). Other curves or RSA keys are not accepted by the Apple Ads OAuth2 token endpoint.
After the API user is set up and the key pair is generated, the API user uploads the public key to Apple Ads to receive a Client ID, Team ID, and Key ID.
Sign in to your Apple Ads account as the API user designated in the previous section.
Navigate to Account Settings, and select the API tab.
On the API screen, click Create to register a new API client.
Paste the contents of public-key.pem (generated in the previous section) into the Public Key field.
Submit the form. Apple Ads displays a code block containing the following values, which are required to mint the client secret JWT:
Client ID — The clientId value (used as the JWT sub claim and as the OAuth2 client ID).
Team ID — The teamId value (used as the JWT iss claim).
Key ID — The keyId value (used in the JWT header).
Copy and store all three values. The Client ID is also entered directly into the Nexla credential.
The client secret used for the OAuth2 token request is a JWT signed with your private key. The JWT must be regenerated periodically because Apple enforces a maximum lifetime of 180 days.
Construct the JWT with the following header and payload:
Header
alg: ES256
kid: Your Key ID (from the previous section)
Payload
sub: Your Client ID
aud: https://appleid.apple.com
iss: Your Team ID
iat: Current Unix timestamp (issued-at time)
exp: Unix timestamp at which the JWT should expire (must be no more than 180 days after iat)
Sign the JWT using the private key (private-key.pem) and the ES256 algorithm. The resulting compact JWT string is the value that Nexla uses as the Client Secret (JWT).
Store the JWT in a secure secret manager, and schedule a rotation before the exp value is reached. Once the JWT expires, Apple's token endpoint returns invalid_client, and Nexla will be unable to obtain a new access token until a fresh JWT is supplied.
The Apple Ads orgId identifies the organization for which API calls are scoped. Every Campaign Management API request must include the header X-AP-Context: orgId=<your-orgId>,…. Nexla constructs this header automatically using the value supplied on the credential.
Sign in to your Apple Ads account.
Click your account avatar in the top-right corner of the screen. The organization name and orgId are listed in the account switcher.
Copy the orgId value for use when configuring the Nexla credential.
Important
The Client Secret (JWT) and private key grant access to your Apple Ads account. Store them in a secure secret manager, never commit them to source control, and rotate them immediately if you suspect they have been exposed.
After selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.
Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.
Apple Ads uses a server-to-server OAuth2 client credentials flow. Nexla exchanges your Client ID and signed client secret JWT for an access token, and includes the organization ID on every API call.
Enter the Client ID issued by Apple Ads when the public key was uploaded in the Client ID field. This value identifies your registered API client.
Enter the signed JWT produced in the Generate the Client Secret JWT section in the Client Secret (JWT) field. This value is treated as a secret and must be regenerated before its exp claim is reached.
The JWT must be signed with the ES256 algorithm using the private key that corresponds to the public key uploaded to Apple Ads. Apple enforces a maximum lifetime of 180 days on the JWT.
Enter the Apple identity token endpoint in the Access Token URL field. The default value https://appleid.apple.com/auth/oauth2/token is correct for production Apple Ads accounts and should be left unchanged unless directed otherwise by Apple.
Enter your Apple Ads organization ID in the Organization ID (orgId) field. Nexla automatically supplies this value in the X-AP-Context header on every API call.
Click the Save button at the bottom of the overlay to save the configured credential. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation and can be selected for use with a new data source or destination.
To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Select the Apple Ads connector tile, then select the credential that will be used to connect to the Apple Ads instance, and click Next; or, create a new Apple Ads credential for use in this flow.
Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Apple Ads endpoints. Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.
Find Campaigns
This endpoint fetches campaigns in the authenticated organization using a selector-based POST /api/v5/campaigns/find request. In Apple Ads, a campaign is the top-level container that holds ad groups, keywords, ads, and budget settings. Use this endpoint to sync your campaign catalog into a warehouse or to obtain campaign IDs for use with the other endpoints below.
No additional parameters are required to use this endpoint. The Apple Ads API returns campaigns scoped to the organization identified by the X-AP-Context header, which Nexla supplies automatically from your credential.
To filter results, send a Selector object in the request body (for example, to limit results to campaigns with a specific status or storefront).
Campaign IDs returned here are used to configure every other endpoint in this list. For the full Selector grammar and supported campaign fields, see the Apple Ads Campaign Management API reference.
Fetch a Single Campaign by ID
This endpoint retrieves the full details of a single campaign by ID via GET /api/v5/campaigns/{campaignId}. Use it to enrich an existing dataset of campaign IDs with the latest configuration, budget, and status.
Enter the campaign ID in the Campaign ID field. This field is required. Campaign IDs can be obtained from the Find Campaigns endpoint or from upstream Nexla data flows.
List Ad Groups
This endpoint retrieves all ad groups within a specified campaign via GET /api/v5/campaigns/{campaignId}/adgroups, with automatic offset-based pagination. In Apple Ads, an ad group sits inside a campaign and groups together keywords, ads, and targeting settings.
Enter the campaign ID in the Campaign ID field. This field is required and identifies the campaign whose ad groups should be retrieved.
Nexla automatically paginates through all ad groups for the specified campaign using the offset and limit query parameters.
Two variants of this endpoint are exposed (List Ad Groups and List Ad Groups (alt)). Both call the same underlying Apple Ads endpoint and behave identically; either can be used.
Get Daily Ad Group Reports
This endpoint retrieves daily performance reports for ad groups in a campaign via POST /api/v5/reports/campaigns/{campaignId}/adgroups. Apple Ads ad group-level reports return performance metrics — impressions, taps, conversions, spend, and computed rates — for each ad group across the requested date range.
Enter the campaign ID in the Campaign ID field. This field is required and identifies the campaign whose ad groups will be reported on.
Each upstream record is sent as the JSON body of the POST call. Use the Nexla request body to supply the Apple Ads reporting Selector — including startTime, endTime, granularity (set to DAILY), and any group-by or filter conditions.
Records are read from the $.data.reportingDataResponse.row[*] path of the response. For the full reporting payload schema and supported metrics, see the Get Ad Group-Level Reports reference.
Get Ad Group Reports
This endpoint generates ad group performance reports using the same POST /api/v5/reports/campaigns/{campaignId}/adgroups endpoint as Get Daily Ad Group Reports, but exposes the campaign ID as optional rather than required. Use it when the campaign ID is supplied as part of the upstream request body or when constructing a custom reporting pipeline.
If a specific campaign should be reported on, enter its ID in the Campaign ID field. Otherwise, leave the field blank and supply the campaign ID through the request body or upstream data.
Provide the reporting Selector — startTime, endTime, granularity, and any group-by or filter conditions — as the JSON body of the call.
List Ads in Ad Group
This endpoint fetches all ads assigned to a specific ad group via GET /api/v5/campaigns/{campaignId}/adgroups/{adgroupId}/ads, with automatic offset-based pagination. In Apple Ads, ads include Creative Set ads and Custom Product Page ads.
Enter the campaign ID in the Campaign ID field. This field is required and identifies the campaign that contains the target ad group.
Enter the ad group ID in the Ad Group ID field. This field is required. Ad group IDs can be obtained from the List Ad Groups endpoint.
Two variants of this endpoint are exposed (List Ads and List Ads in Ad Group). Both call the same underlying Apple Ads endpoint and behave identically.
Get Daily Ad Reports
This endpoint retrieves daily performance reports for ads in a campaign via POST /api/v5/reports/campaigns/{campaignId}/ads. Use it to track per-ad performance metrics such as impressions, taps, conversions, and spend.
Enter the campaign ID in the Campaign ID field. This field is required and identifies the Apple Ads campaign whose ads will be reported on.
Provide the reporting Selector — startTime, endTime, granularity (set to DAILY), and any filter conditions — as the JSON body of the call.
List Targeting Keywords
This endpoint retrieves all targeting keywords assigned to an ad group via GET /api/v5/campaigns/{campaignId}/adgroups/{adgroupId}/targetingkeywords, with automatic offset-based pagination. Targeting keywords drive when ads appear in App Store search results.
Enter the campaign ID in the Campaign ID field. This field is required and identifies the campaign that contains the target ad group.
Enter the ad group ID in the Ad Group ID field. This field is required. Ad group IDs can be obtained from the List Ad Groups endpoint.
Two variants of this endpoint are exposed (List Targeting Keywords with required parameters and a second variant with optional parameters). Both call the same underlying Apple Ads endpoint.
Find Targeting Keywords
This endpoint fetches targeting keywords across all ad groups in a campaign via POST /api/v5/campaigns/{campaignId}/adgroups/targetingkeywords/find, using a selector-based request body for filtering and sorting. Use it when you need server-side filtering rather than pagination through every ad group's keywords.
Enter the campaign ID in the Campaign ID field. This field is optional — if blank, the campaign ID must be supplied through the request body or upstream data.
Send the Selector object — including conditions, orderBy, and pagination — as the JSON body of the call.
Create Targeting Keywords
This endpoint creates new targeting keywords in a specific ad group via POST /api/v5/campaigns/{campaignId}/adgroups/{adgroupId}/targetingkeywords. The response includes the newly created keyword records, which is why this endpoint is exposed as a source — it can be used to ingest the API's response data into Nexla.
Enter the campaign ID in the Campaign ID field, and the ad group ID in the Ad Group ID field. Both fields are optional and can also be supplied via the request body or upstream data.
Send the array of keyword objects (each containing text, matchType, bidAmount, and other supported fields) as the JSON body of the call.
This endpoint is most commonly used as a destination. To send upstream Nexla records into Apple Ads as targeting keywords, see Apple Ads Destination.
Get Daily Keyword Reports
This endpoint retrieves daily keyword performance reports via POST /api/v5/reports/campaigns/{campaignId}/keywords. Use it to monitor metrics for each keyword — impressions, taps, conversions, spend, average CPT, and average CPA — by day.
Enter the campaign ID in the Campaign ID field. This field is required and identifies the campaign whose keywords will be reported on.
Provide the reporting Selector — startTime, endTime, granularity (set to DAILY), and any filter conditions — as the JSON body of the call.
List Ad Group Negative Keywords
This endpoint fetches all negative keywords assigned to a specific ad group via GET /api/v5/campaigns/{campaignId}/adgroups/{adgroupId}/negativekeywords, with automatic offset-based pagination. Negative keywords prevent ads from showing on specified search terms.
Enter the campaign ID in the Campaign ID field. This field is optional but recommended.
Enter the ad group ID in the Ad Group ID field. This field is optional but recommended and identifies the ad group whose negative keywords should be retrieved.
Find Ad Group Negative Keywords
This endpoint fetches negative keywords across all ad groups in a campaign via POST /api/v5/campaigns/{campaignId}/adgroups/negativekeywords/find, using a selector-based request body for filtering. Use it when you need server-side filtering rather than paginating through every ad group's negative keywords.
Enter the campaign ID in the Campaign ID field. This field is optional — if blank, the campaign ID must be supplied through the request body or upstream data.
Send the Selector object — including conditions, orderBy, and pagination — as the JSON body of the call.
List Campaign Negative Keywords
This endpoint fetches all negative keywords assigned at the campaign level via GET /api/v5/campaigns/{campaignId}/negativekeywords, with automatic offset-based pagination. Campaign-level negative keywords apply across every ad group in the campaign.
Enter the campaign ID in the Campaign ID field. This field is optional but recommended.
Search Apps
This endpoint searches for iOS apps available to promote in a campaign via GET /api/v5/search/apps, with automatic offset-based pagination. Use it to look up the adamId of an app before creating a new campaign for it.
Optionally, enter an app name or bundle identifier in the Search Query field to filter the search results.
Optionally, set the Owned Apps Only field to true to return only apps owned by the organization referenced by the credential, or leave it blank or false to search the entire App Store catalog.
Create Custom Report
This endpoint creates an asynchronous impression-share (Share-of-Voice) custom report via POST /api/v5/custom-reports. Custom reports run asynchronously on Apple's side and produce a downloadable file once complete.
No parameters are required in the URL. Provide the custom report request body — including name, startTime, endTime, granularity, selector, and report metric fields — as the JSON body of the call.
The response includes a custom report ID that can be used to poll the custom-reports endpoints for status and to retrieve the resulting report data once it is ready.
Custom reports are subject to Apple Ads usage limits. For details on payload schema and limits, see the Apple Ads Reports reference.
Once the selected endpoint template has been configured, click the Test button to the right of the endpoint selection menu to retrieve a sample of the data that will be fetched. Sample data will be displayed in the Endpoint Test Result panel on the right, allowing you to verify that the source is configured correctly before saving.
Apple Ads data sources can also be manually configured to ingest data from any valid Apple Ads Campaign Management API endpoint, including endpoints not covered by the pre-built templates, chained API calls, or custom Selector request bodies. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, endpoint URL, date/time and lookup macros, path to data, metadata, and request headers.
Apple Ads endpoints follow the format https://api.searchads.apple.com/api/v5/<resource> — for example, https://api.searchads.apple.com/api/v5/campaigns/find. Reporting endpoints expect dates formatted as yyyy-MM-dd. List endpoints (campaigns, ad groups, keywords, ads) return records inside the top-level data array (path $.data[*]), while reporting endpoints nest records under $.data.reportingDataResponse.row[*]. The credential's organization ID (orgId) is automatically supplied in the X-AP-Context header on every request, and the Authorization header is handled automatically — you do not need to add either.
Once all of the relevant settings have been configured, click the Create button in the upper right corner of the screen to save and create the new Apple Ads data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.
Click the + icon on the Nexset that will be sent to the Apple Ads destination, and select the Send to Destination option from the menu. Select the Apple Ads connector from the list of available destination connectors, then select the credential that will be used to connect to the Apple Ads organization, and click Next; or, create a new Apple Ads credential for use in this flow.
Nexla provides pre-built templates that can be used to rapidly configure destinations to send data to common Apple Ads endpoints. Select the endpoint to which data will be sent from the Endpoint pulldown menu. Then, click on the template in the list below to expand it, and follow the instructions to configure additional endpoint settings.
Create a Campaign
This endpoint creates a new Apple Ads campaign via POST /api/v5/campaigns. Use it to programmatically launch campaigns from an upstream system — for example, turning planned campaign briefs from a marketing tool into live Apple Ads campaigns.
No path parameters are required for this endpoint.
Each upstream record is sent as the JSON body of the POST call. Use the Nexla transform layer to shape upstream attributes into the campaign fields expected by Apple Ads — including name, orgId, adamId, budgetAmount, dailyBudgetAmount, countriesOrRegions, and supplySources.
This endpoint updates an existing campaign via PUT /api/v5/campaigns/{campaignId}. Use it to sync changes from a downstream system of record — for example, status, budget, daily budget, or name updates — back into Apple Ads.
Enter the campaign ID in the Campaign ID field. This field is required and identifies the campaign to update. To drive the destination from an upstream source, map the upstream record's campaign identifier into this field.
The body of each PUT call is the upstream record (as JSON). The Apple Ads API expects a wrapper object of the form { "campaign": { ... } }; use the Nexla transform layer to produce that shape.
Delete a Campaign
This endpoint deletes an Apple Ads campaign via DELETE /api/v5/campaigns/{campaignId}. Deleting a campaign also deletes its ad groups, ads, and keywords.
Enter the campaign ID in the Campaign ID field. This field is required and identifies the campaign to delete. To drive the destination from an upstream source, map the upstream record's campaign identifier into this field.
Campaign deletion is permanent and cascades to all child ad groups, keywords, and ads. Consider pausing the campaign instead if the data may be needed later.
Create an Ad Group
This endpoint creates a new ad group within a specific campaign via POST /api/v5/campaigns/{campaignId}/adgroups. Use it to programmatically populate campaigns with ad groups from an upstream planning system.
Enter the campaign ID in the Campaign ID field. This field is required and identifies the campaign that the new ad group will be created in.
Each upstream record is sent as the JSON body of the POST call. Map upstream attributes to the ad group fields expected by Apple Ads — including name, defaultBidAmount, cpaGoal, startTime, endTime, automatedKeywordsOptIn, and targetingDimensions.
Update an Ad Group
This endpoint updates an existing ad group via PUT /api/v5/campaigns/{campaignId}/adgroups/{adgroupId}. Use it to sync bid, status, targeting, or schedule changes back into Apple Ads.
Enter the campaign ID in the Campaign ID field, and the ad group ID in the Ad Group ID field. Both fields are required.
The body of each PUT call is the upstream record (as JSON). Include only the fields that should be changed.
Delete an Ad Group
This endpoint deletes an existing ad group via DELETE /api/v5/campaigns/{campaignId}/adgroups/{adgroupId}. Deleting an ad group also deletes its keywords and ads.
Enter the campaign ID in the Campaign ID field, and the ad group ID in the Ad Group ID field. Both fields are required.
Create an Ad
This endpoint creates a new Creative Set or custom product page ad within an ad group via POST /api/v5/campaigns/{campaignId}/adgroups/{adgroupId}/ads. Use it to push new ad creatives from upstream systems into Apple Ads.
Enter the campaign ID in the Campaign ID field, and the ad group ID in the Ad Group ID field. Both fields are required.
Each upstream record is sent as the JSON body of the POST call. Map upstream attributes to the ad fields expected by Apple Ads — including name, creativeId, and the custom product page configuration.
Update an Ad
This endpoint updates an existing ad's status or creative set via PUT /api/v5/campaigns/{campaignId}/adgroups/{adgroupId}/ads/{adId}. Use it to pause, resume, or rotate creatives based on performance data from a downstream system.
Enter the campaign ID in the Campaign ID field, the ad group ID in the Ad Group ID field, and the ad ID in the Ad ID field. All three fields are required.
The body of each PUT call is the upstream record (as JSON). Include only the fields that should be changed.
Create Ad-Group-Level Negative Keywords
This endpoint bulk-creates negative keywords at the ad group level via POST /api/v5/campaigns/{campaignId}/adgroups/{adgroupId}/negativekeywords. Negative keywords prevent ads from showing on specified search terms within the target ad group.
Enter the campaign ID in the Campaign ID field, and the ad group ID in the Ad Group ID field. Both fields are required.
Each upstream record is sent as the JSON body of the POST call. The body is an array of negative keyword objects, each with text and matchType fields.
Create Campaign-Level Negative Keywords
This endpoint bulk-creates negative keywords at the campaign level via POST /api/v5/campaigns/{campaignId}/negativekeywords. Campaign-level negative keywords apply across every ad group in the campaign.
Enter the campaign ID in the Campaign ID field. This field is required and identifies the campaign that the negative keywords will be added to.
Each upstream record is sent as the JSON body of the POST call. The body is an array of negative keyword objects, each with text and matchType fields.
Delete an Ad-Group-Level Negative Keyword
This endpoint deletes a single ad-group-level negative keyword via DELETE /api/v5/campaigns/{campaignId}/adgroups/{adgroupId}/negativekeywords/{keywordId}. Use it to clean up negative keywords that are no longer needed.
Enter the campaign ID in the Campaign ID field, the ad group ID in the Ad Group ID field, and the negative keyword ID in the Keyword ID field. All three fields are required.
Apple Ads destinations can also be manually configured to send data to any valid Apple Ads Campaign Management API endpoint. Using manual configuration, you can also configure Nexla to automatically send the response received from the Apple Ads API after each call to a new Nexla webhook data source — useful for tracking the IDs of newly created resources or surfacing error responses for downstream monitoring. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, data format, endpoint URL, request headers, attribute exclusions, record batching, and response webhooks.
Apple Ads accepts JSON request bodies (application/json), and endpoints follow the format https://api.searchads.apple.com/api/v5/<resource> — for update or delete operations, include the ID of the object at the end of the URL. The Authorization and base X-AP-Context (organization) headers are handled automatically. Endpoints such as POST /negativekeywords accept arrays of objects per call, so batching is the most efficient way to populate large keyword lists; the Apple Ads API enforces per-endpoint maximums (for example, 1,000 negative keywords per request).
Once all endpoint settings have been configured, click the Done button in the upper right corner of the screen to save and create the destination. To send the data to the configured Apple Ads endpoint, open the destination resource menu, and select Activate.
The Nexset data will not be sent to the Apple Ads API until the destination is activated. Destinations can be activated immediately or at a later time, providing full control over data movement.
