# POST / PUT / DELETE /v1/projects/:projectId/ads/apple/adgroups/:adgroupId/keywords (/docs/api/reference/ads/apple-keyword-bulk)



<Endpoint method="POST" path="/v1/projects/:projectId/ads/apple/adgroups/:adgroupId/keywords" scope="ads:write:creative" phase="1" />

<Endpoint method="PUT" path="/v1/projects/:projectId/ads/apple/adgroups/:adgroupId/keywords" scope="ads:write:creative" phase="1" />

<Endpoint method="DELETE" path="/v1/projects/:projectId/ads/apple/adgroups/:adgroupId/keywords" scope="ads:write:creative" phase="1" />

Apple Search Ads is structurally different from Meta / TikTok — its tier-3 entity is the **keyword**, not the ad. Partner contract uses `keywords` directly (D36). Bulk operations only — Apple's API is bulk-native; per-keyword endpoints would multiply rate-limit cost \~10× and force partners to re-implement bulk semantics.

## Body — POST (add keywords) [#body--post-add-keywords]

```json
{
  "keywords": [
    { "text": "cold brew coffee", "matchType": "exact", "bidAmountCents": 200, "status": "active" },
    { "text": "iced coffee delivery", "matchType": "broad", "bidAmountCents": 150, "status": "active" }
  ]
}
```

Max 200 per call. `matchType`: `exact | broad`. `bidAmountCents`: integer, cents.

## Body — PUT (update bids / status) [#body--put-update-bids--status]

```json
{
  "keywords": [
    { "keywordId": "kw_01HZX9...", "bidAmountCents": 250 },
    { "keywordId": "kw_01HZXA...", "status": "paused" }
  ]
}
```

## Body — DELETE (remove keywords) [#body--delete-remove-keywords]

```json
{
  "keywordIds": ["kw_01HZX9...", "kw_01HZXA..."]
}
```

## Response [#response]

`202` with the typical `{jobId, verdictId, status}` envelope. `status: "completed"` reports per-keyword success/fail.

```json
{
  "jobId": "job_01HZX9...",
  "verdictId": "ver_01HZX9...",
  "results": [
    { "keywordId": "kw_01HZX9...", "status": "added" },
    { "keywordId": "kw_01HZXA...", "status": "added" }
  ]
}
```

## Errors [#errors]

| Code                | When                                                                                                |
| ------------------- | --------------------------------------------------------------------------------------------------- |
| `VALIDATION`        | Empty array, > 200 keywords, missing required field.                                                |
| `AUTHORITY_DENIED`  | `creative` axis is `off` on the parent campaign.                                                    |
| `PLATFORM_REJECTED` | Apple refused (duplicate keyword, blacklisted text, etc.). Per-keyword reason in `results[].error`. |

## See also [#see-also]

* [Ads write model](/docs/api/concepts/ads-write-model)
* [Apple campaign-create investigation](/docs/internal/apple-campaign-create-investigation)