# Managing Keywords and Negative Keywords Create and manage keywords and negative keywords for ad groups and campaigns. ## Overview Keywords define which user searches trigger your ad. Negative keywords prevent your ad from appearing for searches you want to exclude. ## Explore the Endpoints The following endpoints create, retrieve, update, and delete keywords and negative keywords: |Method |Path |Description | |--------|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------| |`POST` |`/v1/keywords` | creates a keyword. | |`POST` |`/v1/keywords/query` | retrieves keywords matching the specified filters. | |`GET` |`/v1/keywords/{id}` | retrieves a single keyword by its ID. | |`PUT` |`/v1/keywords/{id}` | updates an existing keyword. | |`DELETE`|`/v1/keywords/{id}` | soft-deletes a keyword by its ID. | |`POST` |`/v1/negative-keywords` | creates a negative keyword. | |`POST` |`/v1/negative-keywords/query`| retrieves negative keywords matching the specified filters.| |`GET` |`/v1/negative-keywords/{id}` | retrieves a single negative keyword by its ID. | |`PUT` |`/v1/negative-keywords/{id}` | updates an existing negative keyword. | |`DELETE`|`/v1/negative-keywords/{id}` | soft-deletes a negative keyword by its ID. | ### Configure a Keyword A keyword belongs to an ad group and associates a search term with a bid. When a user’s search query matches a keyword, the ad group becomes eligible to enter the auction for that query. Each keyword requires: - `text`: The keyword term to target. For `CATEGORY` match type on Maps campaigns, this must be a Maps business category identifier (for example, `dining.restaurant`). - `matchType`: How the keyword matches user queries. The `EXACT` and `BROAD` types apply to App Store campaigns using the Search results placement. The `PHRASE` and `CATEGORY` types apply to Apple Maps campaigns. See [`KeywordMatchType`](/documentation/Apple-Ads-Platform-API/KeywordMatchType). - `adGroupId`: The ad group this keyword belongs to. The `bid` field is optional on create. When provided, it overrides the ad group’s [`BidStrategy`](/documentation/Apple-Ads-Platform-API/BidStrategy) `bid` for that specific keyword. Maximize Conversions bid strategy campaigns don’t use the `bid` field. To enable or pause individual keywords without removing them, use [`KeywordStatus`](/documentation/Apple-Ads-Platform-API/KeywordStatus). A paused keyword remains in the ad group but doesn’t participate in auctions. ### Configure a Negative Keyword A negative keyword prevents your ad from serving when a user’s search matches the excluded term. You can scope negative keywords to either a campaign or an ad group: - **Campaign-level**: Applies across all ad groups in the campaign. Set `campaignId` and omit `adGroupId`. - **Ad group-level**: Applies only within a specific ad group. Set `adGroupId` and omit `campaignId`. Negative keywords use the same `text` and `matchType` fields as keywords but don’t have a `bid` field, though `CATEGORY` match type doesn’t apply to negative keywords. ### Choose a Match Type The `matchType` field controls how a keyword’s text matches a user’s search query. See the table below for each type’s placement and behavior: |Match Type|Placement |Behavior | |----------|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |`BROAD` |App Store (Search results)|Matches the keyword and close variants, including misspellings, synonyms, and related terms. Maximizes reach. | |`EXACT` |App Store (Search results)|Matches the keyword term precisely. Gives the most control over which queries trigger the ad. | |`PHRASE` |Maps |Matches the keyword and close variants within Maps search, allowing flexibility while staying focused on the search intent. | |`CATEGORY`|Maps |Matches user searches to a Maps business category (for example, `dining.restaurant`, `shopping.clothing`). Use category identifiers from the endpoint.| Use `BROAD` as the recommended starting point for Search results campaigns on the App Store when you’re building out a keyword list. To control spend on specific high-value terms, use `EXACT`. For Maps campaigns, use `CATEGORY` to reach users searching for a type of business rather than a specific name. ### Perform Bulk Operations For bulk create, update, and delete across keywords and negative keywords, see [Bulk Operations Endpoints](/documentation/Apple-Ads-Platform-API/bulk-operations-endpoints). --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)