Send query results to Pinterest Ads

Use a query to build an audience that meets the criteria for how your brand wants to advertise on Pinterest. Send the list of email addresses associated with that audience to Pinterest using an orchestration, after which that list of email addresses will be available in Pinterest Ads as a customer list.

A customer list is associated with an audience in Pinterest, after which your brand may use that audience to advertise on Pinterest.

Amperity will create the customer list (if it does not already exist), and then add email addresses to that customer list OR Amperity will update the customer list (if it already exists) so that it matches the list of email addresses that were sent from Amperity.

Note

An existing customer list should be empty the first time Amperity sends a list of email addresses.

When a customer list is not associated with an audience in Pinterest, Amperity will create an audience using the same name as the list name that was used in Amperity, and then attach the customer list that is managed by Amperity to that audience list.

Note

A customer list must contain at least 100 email addresses that are associated with a Pinterest account before it can be associated with an audience.

About Pinterest API endpoints

Amperity uses a combination of endpoints in the Pinterest API:

  • The create audience endpoint to create an audience that can be used to reach specific groups of users in Pinterest. This converts a customer list into the CUSTOMER_LIST audience type.

  • The create customer list endpoint to create a customer list from a list of SHA-256 hashed email addresses sent to Pinterest from Amperity.

  • The update customer list endpoint to manage the list of email addresses in a customer list.

Pinterest applies standard access rate limits ; Amperity can read from existing customer lists at up to 1000 calls per minute and can write to customer lists at up to 400 calls per minute.

Changes to audiences are not immediately available in Pinterest. Allow for up to 48 hours after the point at which Amperity has finished sending audience updates for them to be available.

Build query

Build a query that returns a list of email addresses. Use additional filters in a WHERE clause to scope your audience for your use cases and goals for marketing to your customers within Pinterest.

Tip

Be sure to exclude the following from query results:

  1. Users who have opted out of targeted advertising on Pinterest

  2. User activity from an app and/or website

  3. Additional profile information, such as names, phone numbers, or physical addresses

Example

The following query returns a list of hashed email addresses for customers who are engaged with your brand, have opted in to receiving email communication, have made at least 4 purchases within the previous year, and have spent at least $400.

SELECT
  TO_HEX(
    SHA256(
      TO_UTF8(
        UPPER(
          TRIM(email)
        )
      )
    )
  ) AS email
  FROM Merged_Customers mc
  INNER JOIN Customer_Attributes ca
  ON mc.amperity_id = ca.amperity_id
  INNER JOIN Transaction_Attributes_Extended tae
  ON mc.amperity_id = tae.amperity_id
  WHERE (
    LOWER(mc.email) IS NOT NULL
    AND pin.contactable_pinterest = TRUE
    AND tae.L12M_order_frequency >= 4
    AND tae.L12M_order_revenue >= 400
  )

Add orchestration

An orchestration defines the relationship between query results and a destination, including the location to which those query results will be sent and the frequency at which the orchestration will be run.

To add an orchestration

  1. From the Destinations tab, click Add Orchestration. This opens the Add Orchestration dialog box.

  2. From the Object Type drop-down, select Query.

  3. From the Object drop-down, select the query for which results will be sent to Pinterest.

  4. From the Destination drop-down, select a destination that is configured for sending data to Pinterest.

  5. From the Data Template drop-down, select a data template.

  6. Verify all settings.

  7. Set the workflow to Manual. (You can change this to automatic later, after verifying the end-to-end workflow.)

  8. Click Save.

Run orchestration

Run the orchestration manually to validate that it works.

To run the orchestration

  1. From the Destinations tab, under Orchestrations, open the    menu for the Pinterest orchestration, and then select Run.

  2. The Status column for the orchestration will update to say “Waiting to start…”, after which the notifications pane will update to include a notification that shows the current status.

  3. When the orchestration has run successfully, the status is updated to “Completed”.

Product catalogs

To make your product catalog available as a data source to Pinterest, for the purpose of enabling Pins, configure an SFTP server with the file that contains the product catalog in a location that is accessible as a URL by a user-agent.

Provide that URL to Pinterest. Pinterest will validate the file and create a product Pin for each item in your product catalog that passes validation, up to 20 million rows.

If your product catalog is already accessible from a URL you can configure Pinterest to use that location. Alternately, you can output your product catalog from Amperity, and then send it to an SFTP site that is configured to allow access to Pinterest.

Pinterest will update your product catalog every 24 hours by reloading the file. Update the file that is in the location from which Pinterest pulls your product catalog to refresh your product catalog on Pinterest.