Skip to main content

Apple Ads Destination

Nexla's bi-directional connectors allow data to flow both to and from any location, making it simple to create a FlexFlow data flow that sends data to an Apple Ads location.
apple_ads_api.png

Apple Ads

Create an Apple Ads Destination​

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

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

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

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

Configure Using a Template​

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

  • To configure this destination using a template, 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.

    For the full set of supported campaign attributes, see the Apple Ads Campaign Management API reference.

    Update a Campaign

    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.

Configure Manually​

Apple Ads destinations can 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.

API Method​

  1. To manually configure this destination, 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. Apple Ads uses POST for create operations, PUT for updates, DELETE for removals, and GET for retrieval-style endpoints.

Data Format​

  1. Select the format in which the Nexset data will be sent to the Apple Ads API from the Content Format pulldown menu. Apple Ads accepts JSON request bodies (application/json); Nexla will automatically convert the data to the selected format for each API call.

API Endpoint URL​

  1. Enter the URL of the Apple Ads API endpoint to which you want to send the Nexset data in the URL field. Apple Ads endpoints follow the format https://api.searchads.apple.com/api/v5/<resource> — for example, https://api.searchads.apple.com/api/v5/campaigns. For update or delete operations, include the ID of the object to be updated or deleted at the end of the URL.

Request Headers​

Optional

  • If Nexla should include any additional request headers in API calls to this destination, 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 header and the base X-AP-Context (organization) header are handled automatically by Nexla.

Exclude Attributes from the Call​

Optional

  • If any record attributes in the Nexset should be omitted when sending data to this Apple Ads destination, select the attributes from the Exclude Attributes pulldown menu. This is useful for stripping internal identifiers or fields that the Apple Ads API does not accept.

  • Any number of attributes can be selected for exclusion, and all excluded attributes will be shown in the field. To remove an attribute from the list, click the X icon next to the attribute name.

Record Batching​

Optional

  1. If records should be sent to this destination in batched API calls, check the box next to Would you like to batch your records together? to enable record batching. Apple Ads endpoints such as POST /negativekeywords accept arrays of objects per call, making batching the most efficient way to populate large keyword lists.

  2. Enter the maximum number of records that should be batched together in a single API call in the Batch Size field. By default, this value is set to 100. The Apple Ads API enforces per-endpoint maximums (for example, 1,000 negative keywords per request) — set this value accordingly.

  3. Select the algorithm that will be used to group records into batches from the Grouping Algorithm pulldown menu. The sample request shown in the panel on the right will be updated to reflect the current batching settings. Some algorithms require additional settings—click on an algorithm listed below to view instructions for configuring these settings.

Response Webhook​

Optional

Nexla can automatically send the response received from the Apple Ads API after each call to a new Nexla webhook data source. This option allows you to keep track of newly created resource IDs, surface Apple Ads error messages for monitoring, or chain follow-up calls (such as adding ads to a newly created ad group).

  • To enable this option, check the box next to Would you like to process the API response as a Nexla Webhook source?.

Sample Request Payload​

Sample request payloads containing a portion of the Nexset data that will be sent to the Apple Ads API endpoint based on the current settings are shown in the Sample Payload panel on the right. These samples can be referenced to ensure that the destination and request settings are correctly configured.

  • Click on a sample request payload to expand it and view the complete payload content.
  • Sample payloads are automatically updated with each setting change, making it easy to verify that changes achieve the desired effect.

Endpoint Testing (Manual Configuration)​

After all endpoint settings have been configured, Nexla can send a test payload to the Apple Ads API to ensure that the destination is configured correctly.

  1. To send a test payload, select the Test button at the top of the Sample Payload panel, and click on a listed sample payload to expand it.

  2. If any modifications to the sample payload are needed, make the necessary changes directly within the sample window.

  3. Click the Send Test Data button at the top of a sample payload to send the test payload to the Apple Ads API using the current settings.

Save & Activate the Destination​

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