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

lead_forms

Create lead forms

This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager.

Create lead forms. Lead forms are used in lead ads and allow you to control what text appears on the lead form's description, questions and confirmation sections.

For more, see Lead ads.

post/ad_accounts/{ad_account_id}/lead_forms

Path parameters

ad_account_idstring required

Unique identifier of an ad account.

Request body

completion_messagestring nullable required

A message for people who complete the form to let them know what happens next.

disclosure_languagestring nullable

Additional disclosure language to be included in the lead form.

has_accepted_termsboolean required

Whether the advertiser has accepted Pinterest's terms of service for creating a lead ad.

By sending us TRUE for this parameter, you agree that (i) you will use any personal information received in compliance with the privacy policy you share with Pinterest, and (ii) you will comply with Pinterest's Lead Ad Terms. As a reminder, all advertising on Pinterest is subject to the Pinterest Advertising Services Agreement or an equivalent agreement as set forth on an IO

namestring nullable required

Internal name of the lead form.

privacy_policy_linkstring nullable required

A link to the advertiser's privacy policy. This will be included in the lead form's disclosure language.

status'DRAFT' | 'ACTIVE'

Status of the lead form

Example request

[
  {
    "completion_message": "Thank you for submitting. We will contact you soon.",
    "disclosure_language": "By entering your personal information, you agree that your data will be collected and used.",
    "name": "Lead Form 3/14/2023",
    "policy_links": [
      {
        "label": "Copyright",
        "link": "https://policy.pinterest.com/en/copyright"
      }
    ],
    "privacy_policy_link": "https://www.advertisername.com/privacy-policy",
    "questions": [
      {
        "question_type": "CUSTOM",
        "custom_question_field_type": "CHECKBOX",
        "custom_question_label": "What is your favorite animal?",
        "custom_question_options": [
          "Dog",
          "Cat",
          "Bird",
          "Turtle"
        ]
      }
    ],
    "status": "DRAFT"
  }
]

Response

The request has succeeded.

Example response

{
  "items": [
    {
      "data": {
        "completion_message": "Thank you for submitting. We will contact you soon.",
        "disclosure_language": "By entering your personal information, you agree that your data will be collected and used.",
        "name": "Lead Form 3/14/2023",
        "policy_links": [
          {
            "label": "Copyright",
            "link": "https://policy.pinterest.com/en/copyright"
          }
        ],
        "privacy_policy_link": "https://www.advertisername.com/privacy-policy",
        "questions": [
          {
            "question_type": "CUSTOM",
            "custom_question_field_type": "CHECKBOX",
            "custom_question_label": "What is your favorite animal?",
            "custom_question_options": [
              "Dog",
              "Cat",
              "Bird",
              "Turtle"
            ]
          }
        ],
        "status": "DRAFT"
      },
      "exceptions": [
        {
          "code": 2,
          "message": "Advertiser not found."
        }
      ]
    }
  ]
}

Changes

Changed in 2 of the 29 revisions of this API.5123

Jun 4, 2026v5b698c180678a5122See the full diff
- ▲
  added the new required request property /
  new-required-request-property
- ▲
  added the new required request property /
  new-required-request-property
- ▲
  added the new required request property /
  new-required-request-property
- ▲
  added the new required request property /
  new-required-request-property
- ▲
  added the new required request property /
  new-required-request-property
- ●
  removed subschema #2 from the request property allOf list
  request-property-all-of-removed
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the non-success response with the status
  response-non-success-status-added
- ○
  added the non-success response with the status
  response-non-success-status-added
- ○
  added the non-success response with the status
  response-non-success-status-added
- ○
  added the non-success response with the status
  response-non-success-status-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  removed subschema #2 from the // response property allOf list for the response status
  response-property-all-of-removed
- ○
  the response property became required for the status
  response-property-became-required
- ○
  the response property //// became required for the status
  response-property-became-required
- ○
  added the required property /// to the response with the status
  response-required-property-added
- ○
  added the required property /// to the response with the status
  response-required-property-added
- ○
  added the required property /// to the response with the status
  response-required-property-added
- ○
  added the required property /// to the response with the status
  response-required-property-added
- ○
  added the required property /// to the response with the status
  response-required-property-added
- ○
  added the required property /// to the response with the status
  response-required-property-added
This revision also has 182 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 14, 2024v589c27ed39cfd1See the full diff
- ○
  endpoint added
  endpoint-added
This revision also has 4 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history