Create a Negative Keyword
Create a negative keyword at the campaign or ad group level to prevent ads from showing for unwanted search terms.
URL
POST https://api.ads.apple.com/v1/negative-keywordsHeader Parameters
| Name | Type | Description |
|---|---|---|
X-Ap-Context Required | string |
Response Codes
| Status | Reason | Type | Description |
|---|---|---|---|
| 200 | OK Content-Type: application/json | NegativeKeywordResponse | |
| 400 | Bad Request Content-Type: application/json | ErrorResponse | |
| 401 | Unauthorized Content-Type: application/json | ErrorResponse | |
| 403 | Forbidden Content-Type: application/json | ErrorResponse | |
| 404 | Not Found Content-Type: application/json | ErrorResponse | |
| 429 | Too Many Requests Content-Type: application/json | ErrorResponse | |
| 500 | Internal Server Error Content-Type: application/json | ErrorResponse |
Discussion
This endpoint creates one negative keyword per request. To create many negative keywords in a single call, use Bulk Create Negative Keywords.
Negative keywords prevent your ads from showing when a user’s search query contains a term you want to exclude. They block traffic rather than compete for it. Negative keywords can be created at two levels, campaign or ad group, each with distinct field requirements and scope.
Use Campaign-Level Negative Keywords
Campaign-level negative keywords block ads from appearing for excluded search terms across all ad groups in the campaign. Use campaign-level negatives when you want broad exclusions that apply uniformly throughout an entire campaign.
A campaign-level negative keyword requires campaignId and leaves adGroupId unset.
Field | Requirement |
|---|---|
| Required |
| Must not be set |
Use Ad-Group-Level Negative Keywords
Ad group-level negative keywords are scoped to a single ad group. Use ad group-level negatives when you need finer control over exclusions for a specific ad group within a campaign.
An ad-group-level negative keyword requires adGroupId and leaves campaignId unset.
Field | Requirement |
|---|---|
| Must not be set |
| Required |