Skip to content

Developer Platform

Search docs & API
Log in
Sign up

The Pinterest API for Lead ads

Pinterest developed Lead Ads so partners can find qualified prospects on the platform. Pinners actively looking for your services can share their information with a few taps on a native lead form.
The Pinterest API for Lead ads lets you seamlessly transfer lead data from Ads Manager to integrate your CRM system with the following features.
  • Lead data subscription
  • Encrypted data transfer
  • Testing API

Prerequisites

To get started with The Pinterest API for Lead ads, you need:
  1. An ad account that the business account is an admin or owner of.
    • See Business access for more information.
  2. A Pinterest App.
    • If you don't have one, follow the Connect app guide.
  3. Request access for your ad account to the Pinterest Lead ads beta.
    • This request should be sent via your Pinterest account team. This step is necessary for end-to-end testing.

Subscribe to leads

Create a subscription

  1. To create a subscription, make a request to the
    POST
    Create lead ads subscription
    endpoint using your access token.
    • Specify the callback URL via the webhook_url field, and include the lead_form_id if you want to specify the form.
    • A successful subscription creation response will contain the subscription_id, as well as its related metadata cryptographic_key and cryptographic_algorithm.

Get subscription details

  1. To retrieve a subscription, make a request to the
    GET
    Get lead ads subscription by ID
    endpoint using your access token.
  2. To retrieve all the subscriptions for your ad_account, make a request to the
    GET
    Get lead ads subscriptions
    endpoint using your access token.

Cancel a subscription

  • To delete a subscription, make a request to the
    DELETE
    Delete lead ads subscription
    endpoint using your access token.

How Pinterest sends lead data

Pinterest delivers lead data to subscribers, whether through a specific lead form or at the ad account level. Important considerations include:
  1. Encryption: For data security, Pinterest encrypts lead data with AES-256-GCM.
  2. Webhook URL: The webhook_url should follow the HTTPS protocol and adhere to standard webhook behavior without authentication or authorization.
  3. Retry mechanism: Pinterest retries for failures with 429 and 5XX statuses but not for other 4XX statuses.
  4. Deduplication: The lead_id field is an internal identifier and can be used for deduplication, although it's not necessary for integration purposes.

Sample code

Sample egress lead data:
[
  {
    "advertiser_id": "111764359001",
    "lead_form_id": "65300871001",
    "ad_id": "222254831001",
    "campaign_id": "333749306001",
    "ad_group_id": "4440076819001",
    "lead_id": "5554397289529204001",
    "user_id": "666644187436941001",
    "lead_form_name": "Lead form name",
    "campaign_name": "Campaign name",
    "ad_group_name": "Ad group",
    "ad_name": "Ad name",
    "created_at": "1698380898000",
    "answers": {
      "cipher_msg": "JlDv7IxKzysAulMzG8eNu8fFq5eQAtpXEGYaJFUAADxk76PPWO...",
      "nonce": "1veT0xnuZVfMqlMK+BieVg==",
      "tag": "r+WV1zkKRPqq/x/ehVetbw=="
    },
    "version": "v5"
  }
]
Sample egress lead data decrypted
[
  {
    "advertiser_id": "111764359001",
    "lead_form_id": "65300871001",
    "ad_id": "222254831001",
    "campaign_id": "333749306001",
    "ad_group_id": "4440076819001",
    "lead_id": "5554397289529204001",
    "user_id": "666644187436941001",
    "lead_form_name": "Lead form name",
    "campaign_name": "Campaign name",
    "ad_group_name": "Ad group",
    "ad_name": "Ad name",
    "created_at": "1698380898000",
    "answers": {
      "EMAIL": "abc@email.com",
      "FULL_NAME": "John Doe",
      "FIRST_NAME": "John",
      "LAST_NAME": "Doe",
      "PHONE_NUMBER": "987654321",
      "ZIP_CODE": "1234567",
      "AGE": "28",
      "GENDER": "Male",
      "COUNTRY": "US",
      "CITY": "Orlando",
      "STATE_PROVINCE": "Florida",
      "ADDRESS": "742 Evergreen",
      "DATE_OF_BIRTH": "12 January",
      "Custom question": "Custom question answer"
    },
    "version": "v5"
  }
]

Testing API

The Test API replicates the functionality of the Production API, including the encryption and retry mechanism. Test lead data will be dispatched to a subscribed webhook_url, corresponding with the ad_account and lead_form_id. To differentiate, test lead data messages can be recognized by a unique identifier - the lead_id value as
TEST_API
.

Test the subscription

  1. After creating the subscription, you can make a request to the
    POST
    Create lead form test data
    test endpoint to create a test.
  2. Note that you need to have a valid lead ads campaign created and associated with ad_account_id and lead_form_id.
    • If your response contains subscription_id, it means that you have created the subscription test successfully.

Additional resources

Get lead form data

  1. To retrieve lead form data, make a request to the
    GET
    List lead forms
    endpoint.
  2. Alternatively you can use
    GET
    Get lead form by id
    to fetch by ID.

Decrypt egress lead data

To decrypt lead data, you should follow the AES-256-GCM standard algorithm, similar to the following sample JS code.
const crypto = require('crypto');

const rawKey = 'u4+XFme7mKn9p6zkKBsx+H9DAwCZ/l9XqrnOHxQ46h4=';
const ENCODING_BASE64 = 'base64';
const ALGORITHM = 'aes-256-gcm';
const ENCODING_UTF8 = 'utf8';

const decrypt = (leadData) => {
  const { cipher_msg, nonce, tag } = leadData.answers;
  const tagBuffer = Buffer.from(tag, ENCODING_BASE64);
  const nonceBuffer = Buffer.from(nonce, ENCODING_BASE64);
  const keyBuffer = Buffer.from(rawKey, ENCODING_BASE64);
  const decipher = crypto.createDecipheriv(ALGORITHM, keyBuffer, nonceBuffer);
  decipher.setAuthTag(tagBuffer);
  let decryptedPlainText = decipher.update(cipher_msg, ENCODING_BASE64, ENCODING_UTF8);
  decryptedPlainText += decipher.final(ENCODING_UTF8);
  return JSON.parse(decryptedPlainText);
};
Was this page helpful?