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_ads

Create lead ads subscription

Changed on Jul 16, 2025

Create a lead ads webhook subscription. Subscriptions allow Pinterest to deliver lead data from Ads Manager directly to the subscriber. Subscriptions can exist for a specific lead form or at ad account level.

Only requests for the OWNER or ADMIN of the ad_account will be allowed.
Advertisers can set up multiple integrations using ad_account_id + lead_form_id but only one integration per unique records.
For data security, egress lead data is encrypted with AES-256-GCM.

post/ad_accounts/{ad_account_id}/leads/subscriptions

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/leads/subscriptions/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

lead_form_idstring

Lead form ID.

webhook_urlstring required

Standard HTTPS webhook URL.

Response

The request has succeeded.

ad_account_idstring

The Ad Account ID that this lead form belongs to.

api_versionstring

API version.

created_timeinteger

Subscription creation time. Unix timestamp in milliseconds.

cryptographic_algorithmstring nullable

Lead data encryption algorithm.

cryptographic_keystring nullable

Base64 encoded key for client to decrypt lead data.

idstring

Subscription ID.

lead_form_idstring nullable

Lead form ID.

user_account_idstring

User account used to subscribe lead data.

webhook_urlstring