Apple Ads Data Source

Apple Ads is Apple's advertising platform for promoting apps across the App Store, with a Campaign Management API for programmatic access to campaigns, ad groups, ads, keywords, and performance reports. Follow the instructions below to create a new data flow that ingests data from an Apple Ads source in Nexla.

Apple Ads

Create a New Data Flow

1. To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Then, select the desired flow type from the list, and click the Create button.

2. Select the Apple Ads connector tile from the list of available connectors. 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.

3. In Nexla, Apple Ads data sources can be created using pre-built endpoint templates, which expedite source setup for common Apple Ads endpoints. Each template is designed specifically for the corresponding Apple Ads endpoint, making source configuration easy and efficient.
   • To configure this source using a template, follow the instructions in Configure Using a Template.

   Apple Ads sources can also be configured manually, allowing you to ingest data from Apple Ads endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
   • To configure this source manually, follow the instructions in Configure Manually.

Configure Using a Template

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Apple Ads endpoints. Each template is designed specifically for the corresponding Apple Ads endpoint, making data source setup easy and efficient.

Endpoint Settings

• 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.

Endpoint Testing

Once the selected endpoint template has been configured, Nexla can retrieve a sample of the data that will be fetched according to the current settings. This allows users to verify that the source is configured correctly before saving.

• To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

• If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Configure Manually

Apple Ads data sources can be manually configured to ingest data from any valid Apple Ads Campaign Management API endpoint. Manual configuration provides maximum flexibility for accessing endpoints not covered by pre-built templates or when you need custom API configurations — for example, calling the custom-reports/{id} polling endpoint or constructing Selector bodies that span multiple campaigns.

With manual configuration, you can also create more complex Apple Ads sources, such as sources that use chained API calls to fetch data from multiple endpoints or sources that require custom Selector bodies and request parameters.

API Method

1. To manually configure this source, select the Advanced tab at the top of the configuration screen.

2. Select the API method that will be used for calls to the Apple Ads API from the Method pulldown menu. The most common methods are:

   • GET: For retrieving campaigns, ad groups, ads, keywords, and other list endpoints
   • POST: For Selector-based find endpoints, reporting endpoints, and custom report creation
   • PUT: For updating existing campaigns, ad groups, and ads
   • DELETE: For removing campaigns, ad groups, keywords, and negative keywords

API Endpoint URL

3. Enter the URL of the Apple Ads API endpoint from which this source will fetch data in the Set API URL field. This should be the complete URL including the protocol (https://) and any required path parameters. 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.

Ensure the API endpoint URL is correct and accessible with your current credentials. The credential's organization ID (orgId) is automatically supplied in the X-AP-Context header on every request. You can test the endpoint using the Test button after configuring the URL.

Date/Time Macros (API URL)

Optional

Optionally, the API URL or request body can be customized using macros—all macros are converted into values when Nexla executes the API call. Macros are dynamic placeholders that allow you to create flexible API endpoints that adapt to different time periods. This is particularly useful for Apple Ads reporting endpoints, which require a startTime and endTime in the request body and are typically driven by macros so each scheduled run retrieves the latest available data.

Macros are particularly useful for reporting endpoints that require date ranges that change between data ingestion runs.

1. To add a macro, type { at the appropriate position in the API URL (within the Set API URL field), and select the desired macro from the dropdown list.

   • {now} – The current datetime
   • {now-1} – The datetime one time unit before the current datetime
   • {now+1} – The datetime one time unit after the current datetime
   • custom – Datetime macros can reference any number of time units before or after the current datetime—for example, enter (now-4) to indicate the datetime four time units before the current datetime

2. Select the format that will be applied to datetime macros from the Date Format for Date/Time Macro pulldown menu. Apple Ads reporting endpoints expect dates formatted as yyyy-MM-dd. This format will be applied to the base datetime value of the macro—i.e., the value of {now} in {now-1}.

3. Select the datetime unit that will be used to perform mathematical operations in the included macro(s) from the Time Unit for Operations pulldown menu—for example, for the macro {now-1}, when Day is selected, {now-1} will be converted to the datetime one day before the current datetime.

Lookup-Based Macros (API URL)

Optional

Column values from existing lookups can also be included as macros in the API URL. Lookup-based macros allow you to reference data from previously configured data sources or lookups, enabling dynamic API endpoints that can adapt based on existing data. For Apple Ads, this is useful for driving record-level endpoints — for example, referencing a list of campaign IDs to fetch ad groups, ads, or reports for each one.

Lookup-based macros are useful when you need to create API endpoints that reference specific IDs, values, or parameters from other data sources in your Nexla environment.

1. To include a lookup column value macro, select the relevant lookup from the Add Lookups to Supported Macros pulldown menu.

2. Type { at the appropriate position in the API URL, and select the lookup column-based macro from the dropdown list. Lookup-based macros are automatically populated into the macro list when a lookup is selected in the Add Lookups to Supported Macros pulldown menu.

Path to Data

Optional

If only a subset of the data that will be returned by the API endpoint is needed, you can designate the part(s) of the response that should be included in the Nexset(s) produced from this source by specifying the path to the relevant data within the response. This is particularly useful because Apple Ads responses wrap the records in a data envelope alongside pagination and error objects.

For example, when a request call is used to fetch a list of campaigns or ad groups, the Apple Ads API returns the records inside a top-level data array. By entering the path to the relevant data, you can configure Nexla to treat each element of the returned array as a record.

Path to Data is essential when API responses have nested structures. Without specifying the correct path, Nexla might not be able to properly parse and organize your data into usable records.

• To specify which data should be treated as relevant in responses from this source, enter the path to the relevant data in the Set Path to Data in Response field.

  • For responses in JSON format enter the JSON path that points to the object or array that should be treated as relevant data. JSON paths use dot notation (e.g., $.data.items[*] to access an array of items within a data object).

  • For responses in XML format, enter the XPath that points to the object/array containing relevant data. XPath uses slash notation (e.g., /response/data/item to access item elements within a data element).

  Path to Data Example:

  For Apple Ads list endpoints (campaigns, ad groups, keywords, ads), records are returned inside the top-level data array, so the path would be entered as $.data[*]. For reporting endpoints, records are nested under data.reportingDataResponse.row, so the path would be entered as $.data.reportingDataResponse.row[*].

Autogenerate Path Suggestions

Nexla can also autogenerate data path suggestions based on the response from the API endpoint. These suggested paths can be used as-is or modified to exactly suit your needs.

• To use this feature, click the Test button next to the Set API URL field to fetch a sample response from the API endpoint. Suggested data paths generated based on the content & format of the response will be displayed in the Suggestions box below the Set Path to Data in Response field.

• Click on a suggestion to automatically populate the Set Path to Data in Response field with the corresponding path. The populated path can be modified directly within the field if further customization is needed.

  

Metadata

If metadata is included in the response but is located outside of the defined path to relevant data, you can configure Nexla to include this data as common metadata in each record. This is useful when you want to preserve important contextual information that applies to all records but isn't part of the main data array.

For example, Apple Ads list responses include a pagination object alongside the records array. If you have specified the path to the records but want to retain pagination details such as the total record count, you can specify a path to this metadata to include it with each record in the generated Nexset(s).

Metadata paths are particularly useful for preserving API response context like request IDs, timestamps, or summary statistics that apply to all records in the response.

• To specify the location of metadata that should be included with each record, enter the path to the relevant metadata in the Path to Metadata in Response field.

  • For responses in JSON format, enter the JSON path to the object or array that contains the metadata, and for responses in XML format, enter the XPath.

Request Headers

Optional

• If Nexla should include any additional request headers in API calls to this source, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (e.g., header1:value1,header2:value2). Additional headers are sometimes useful for delegated access — for example, supplying an X-AP-Context value that includes a campaign group ID alongside the organization ID.

  You do not need to include any headers already present in the credentials. The Authorization and base X-AP-Context (organization) headers are handled automatically by Nexla based on your credential configuration.

Endpoint Testing

After configuring all settings for the selected endpoint, Nexla can retrieve a sample of the data that will be fetched according to the current configuration. This allows users to verify that the source is configured correctly before saving.

• To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

• If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Save & Activate the Source

1. Once all of the relevant steps in the above sections have been completed, 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.