ad_accounts14

ad_groups13

ads10

advanced_auction2

audience_insights2

audience_sharing7

audiences4

billing11

boards11

bulk3

business_access_assets12

business_access_invite6

business_access_relationships9

campaigns8

catalog_feeds8

catalog_items3

catalog_product_groups10

catalog_reports3

catalog_supplemental7

catalogs3

conversion_deletion_requests4

conversion_eqs1

conversion_events1

conversion_tags5

conversions4

customer_list_uploads3

customer_lists4

customer_segment3

integrations7

keywords5

labels5

lead_ads4

lead_forms5

leads_export2

media3

msot_events1

notification1

oauth3

order_lines2

pins8

product_group_promotions5

product_tags3

promotions5

resources6

schedules3

search3

targeting_template3

terms2

terms_of_service1

trends4

user_account14

keywords

Create keywords

Changed on Jun 4, 2026

Create keywords for the following entity types (advertiser, campaign, ad group, or ad). For more information, see Keyword targeting.

Notes:

Advertisers and campaigns can only be assigned keywords with excluding (_NEGATIVE).
All keyword match types are available for ad groups.

For more information on match types, see match type enums.

Returns:

A successful call returns an object containing an array of new keyword objects and an empty errors object array.

An unsuccessful call returns an empty keywords array, and instead, inserts the entire object with nulled/negated properties into the errors object array:

{
  "keywords": [],
  "errors": [
    {
      "data": {
        "archived": null,
        "match_type": "EXACT",
        "parent_type": null,
        "value": "foobar",
        "parent_id": null,
        "type": "keyword",
        "id": null
      },
      "error_messages": [
        "Advertisers and Campaigns only accept excluded targeting attributes."
      ]
    }
  ]
}

post/ad_accounts/{ad_account_id}/keywords

Request

Base URL
https://api.pinterest.com/v5
Auth
OAuth 2
Authorization codehttps://www.pinterest.com/oauth/
Token URLhttps://api.pinterest.com/v5/oauth/token
Scopesads:write
TypeScript
https://skmtc.dev/pinterest/apis/pinterest-rest-api/docs/ad_accounts/:ad_account_id/keywords/post.ts
A function with typed inputs. Its response is checked against the schema.

Path parameters

ad_account_idstring required

Unique identifier of an ad account.

Request body

parent_idstring required

Keyword data

Example request

{
  "keywords": [
    {
      "match_type": "BROAD"
    }
  ]
}

Response

The request has succeeded.

Example response

{
  "errors": [
    {
      "data": {
        "id": "383791336903426391",
        "match_type": "BROAD",
        "parent_id": "383791336903426391",
        "parent_type": "campaign",
        "type": "keyword"
      }
    }
  ],
  "keywords": [
    {
      "id": "383791336903426391",
      "match_type": "BROAD",
      "parent_id": "383791336903426391",
      "parent_type": "campaign",
      "type": "keyword"
    }
  ]
}

Changes

Jun 4, 2026v5b698c180678a Revision changes
- breaking
  added to the // request property allOf list
- breaking
  removed the enum value BROAD of the request property //
- breaking
  removed the enum value EXACT of the request property //
- breaking
  removed the enum value EXACT_NEGATIVE of the request property //
- breaking
  removed the enum value PHRASE of the request property //
- breaking
  removed the enum value PHRASE_NEGATIVE of the request property //
- breaking
  removed the enum value undefined of the request property //
- breaking
  the // request property type changed from string to no type
- info
  removed the pattern ^((AG)|C)?\d+$ from the request property
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  the response optional property became read-only for the status
- info
  removed subschema #2 from the // response property allOf list for the response status
- info
  removed subschema #2 from the / response property allOf list for the response status
- info
  the response property became required for the status
- info
  the response property became required for the status
- info
  added the required property /// to the response with the status
- info
  added the required property /// to the response with the status
- info
  added the required property /// to the response with the status
- info
  added the required property /// to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the success response with the status
Apr 23, 2024v5f9321315766f Revision changes
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status

Operation history (5 revisions)