Pinterest API SDK

0.2.6 · active · verified Thu Apr 16

The Pinterest API SDK is a Python library designed to simplify interaction with the Pinterest API v5. It provides functionalities for campaign management, streamlines authentication, and handles error reporting. The SDK is actively developed, with its current version being 0.2.6, and aims to expand its capabilities to cover organic Pins, shopping, analytics, and more over time.

Common errors

```
pinterest.client.PinterestSDKClient.create_default_client() could not be instantiated
```
cause The SDK client could not find required authentication credentials (APP_ID, APP_SECRET, ACCESS_TOKEN/REFRESH_TOKEN) in environment variables or a `config.json` file.

fix Set `PINTEREST_APP_ID`, `PINTEREST_APP_SECRET`, and either `PINTEREST_ACCESS_TOKEN` or `PINTEREST_REFRESH_ACCESS_TOKEN` in your environment or a `.env` file. Alternatively, create a `config.json` file with these credentials.
```
requests.exceptions.HTTPError: 401 Client Error: Unauthorized for url: ...
```
cause The provided access token is invalid, expired, or does not have the necessary scopes for the requested API operation.

fix Verify that your access token is current and has the correct permissions (scopes) for the API endpoint you are calling. If using a refresh token, ensure it's valid to obtain a new access token. Regenerate tokens if necessary.
```
AttributeError: module 'pinterest' has no attribute 'client'
```
cause Attempting to import `PinterestSDKClient` incorrectly, for example, `import pinterest.client.PinterestSDKClient` or `from pinterest import PinterestSDKClient`.

fix The correct import path for the main client is `from pinterest.client import PinterestSDKClient`.

Warnings

breaking Older versions (prior to v0.2.6) used `yaml.load`, which is insecure. This was updated to `yaml.safe_load` in v0.2.6. Applications parsing untrusted YAML with older versions may be vulnerable to arbitrary code execution.
Fix: Upgrade to pinterest-api-sdk v0.2.6 or newer: `pip install --upgrade pinterest-api-sdk`.
gotcha When creating multiple `PinterestSDKClient` instances or not relying on the globally configured default client, you must explicitly pass the `client` object to model methods (e.g., `AdAccount.get_all(client=my_custom_client)`). Forgetting this can lead to methods attempting to use an incorrect or uninitialized default client.
Fix: Always pass the `client` parameter to model methods if you are not exclusively using `PinterestSDKClient.create_default_client()` and expect its scope. This behavior was clarified and fixed in v0.2.2 regarding classmethod `create`.
deprecated Pinterest API v5 requires Transport Layer Security (TLS) version 1.2 or later. Older TLS protocols (1.0 and 1.1) are deprecated and will not work.
Fix: Ensure your Python environment and underlying OS libraries support and default to TLS 1.2+ for HTTPS connections. Most modern Python installations should handle this automatically, but older systems might require updates.
gotcha Using the `android_deep_link` field when creating an Ad via the SDK will currently generate an error as it is not yet available through the API.
Fix: Avoid setting the `android_deep_link` parameter when creating or updating Ads through the SDK until Pinterest's API documentation indicates its availability.

Install

pip install pinterest-api-sdk Install latest version

Imports

PinterestSDKClient
wrong:
```
import pinterest_api_sdk
```
correct:
```
from pinterest.client import PinterestSDKClient
```
The primary client class is located within the 'pinterest.client' submodule, not directly under the top-level package.
AdAccount
wrong:
```
from pinterest.models import AdAccount
```
correct:
```
from pinterest.ads.ad_accounts import AdAccount
```
Entity models are organized under specific API domains (e.g., `pinterest.ads`).

Quickstart

This quickstart demonstrates how to initialize the Pinterest SDK client using environment variables and retrieve a list of accessible ad accounts. Ensure your Pinterest App ID, Secret, and an Access Token (or Refresh Token) are configured as environment variables or in a `.env` file for the `create_default_client()` method to function.

import os
from pinterest.client import PinterestSDKClient
from pinterest.ads.ad_accounts import AdAccount

# Set environment variables or create a .env file with PINTEREST_APP_ID, PINTEREST_APP_SECRET,
# PINTEREST_ACCESS_TOKEN (or PINTEREST_REFRESH_ACCESS_TOKEN if using refresh token flow).
# Example environment variables:
# os.environ['PINTEREST_APP_ID'] = 'YOUR_APP_ID'
# os.environ['PINTEREST_APP_SECRET'] = 'YOUR_APP_SECRET'
# os.environ['PINTEREST_ACCESS_TOKEN'] = 'YOUR_ACCESS_TOKEN'

# Create a default client (uses environment variables or config.json)
# For production, consider using create_client_with_refresh_token for long-lived access
try:
    client = PinterestSDKClient.create_default_client()
    
    # Example: List ad accounts
    ad_accounts = AdAccount.get_all(client=client) # Pass client explicitly if not using default behavior
    
    if ad_accounts:
        print(f"Found {len(ad_accounts)} ad account(s).")
        for account in ad_accounts:
            print(f"  Ad Account ID: {account.id}, Name: {account.name}")
    else:
        print("No ad accounts found or accessible.")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure your Pinterest API credentials (APP_ID, APP_SECRET, ACCESS_TOKEN) are correctly set as environment variables or in a .env file.")

view raw JSON →