Skip to content

Developer Platform

Search docs & API
Log in
Sign up

FAQs

We continually update and expand these FAQs.

App FAQs

Get answers to questions about managing your app.

Is a "client ID" different from an "app ID"?

The following three names refer to the same type of ID even though they appear in different contexts:
  • Client ID
  • App ID
  • Consumer ID

How do I find a client ID (or app ID)?

If you have created a developer account and have connected your app to the Pinterest API, take the following steps to find your client ID, also called "app ID":
  1. Go to My apps.
  2. In the My apps section of the page, see the listed apps.
  3. Note the App id under the app name. The app ID and client ID are identical.
App ID location

How do I find my redirect URI?

To find your redirect URI:
  1. Go to My apps.
  2. Select Manage for the relevant app.
  3. Select the Configure tab on the app page.
  4. Find the Redirect URIs section on that page, where the URI is listed.
Redirect URI location

Can I delete an app?

If you need to delete an app because, for example, you have reached your five-app limit and need to remove one, file a Support ticket :
  1. Go to Get more help in Help Center.
  2. Select Pinterest API and Developer Tools.
  3. Select Developer site and click Continue.
  4. Select App management support and click Continue.
  5. Enter or provide requested information in each form, clicking Continue to advance to the next form. Then click Submit on the last form.

How do I find my app's secret key?

  1. Go to My apps.
  2. Select Manage for the relevant app.
  3. Select the Configure tab on the app's page.
  4. Find the App secret key field in the Api keys section.
  5. Click the View icon to view the key or the Copy icon to copy it.

How do I share my app with other Pinterest users?

You can share access to your app with employees in your organization once you add them in to your business account in Business Manager.
To collaborate on your app with these employees:
  1. Go to My apps.
  2. Select Manage for the relevant app.
  3. Select the Collaborators tab on the app's page.
  4. In the Collaborators field of the displayed page, select the email addresses of employees you want as collaborators from the drop-down list.

Why am I unable to generate or see my app secret?

If your app is pending Pinterest approval, you cannot see your app secret. Approvals typically take one to three business days. If you do not receive a response regarding your submitted app, file a Support ticket:
  1. Go to Get more help in Help Center.
  2. Select Pinterest API and Developer Tools.
  3. Select Developer site and click Continue.
  4. Select API access and click Continue.
  5. Enter or provide requested information in each form, clicking Continue to advance to the next form. Then click Submit on the last form.

API FAQs

Get answers to questions about using the Pinterest API.

What should I do when I see the error "Your token does not have sufficient permissions to perform this operation."?

Each API endpoint has associated scopes, which define its required user permissions. Your token may not have the appropriate scopes for the endpoint you want to contact.
If you are not certain what scopes your token provides, use the Token Debugger tool to find out.
To add scopes, you will need to generate a brand new token with those scopes through the Authorization Code or Client Credentials grant type.
Learn more about selecting scopes for your token. Also, see any endpoint in the API reference to determine its required scopes.

My access or refresh token is not working. What should I do?

Take the following actions to address problems with a token.

Check and address token-specific issues

Use the Token Debugger tool to see why your refresh token is not working. Common issues include:
  • Token is expired or invalid.
  • User session is expired or invalid. For example, your user may be logged out of their token session because of a changed password.
  • Token has insufficient scopes. See the FAQ about insufficient scopes.
For these common issues, do the following:
  • Generate a brand-new access token with the Authorization Code grant.
  • Generate a continuous refresh token based on the access token.
If generating new tokens does not correct the problem, file a support ticket:
  1. Go to Get more help in Help Center.
  2. Select Pinterest API and Developer Tools.
  3. Select Developer site and click Continue.
  4. Select API Technical Support and click Continue.
  5. Enter requested information in the forms.

Check your app status or account status

Check with your Pinterest representative to see if your app has been deactivated or your account has been revoked. Or file a support ticket in inquire.
  1. Go to Get more help in Help Center.
  2. Select Pinterest API and Developer Tools.
  3. Select Developer site and click Continue.
  4. Select API Technical Support and click Continue.
  5. Enter requested information in the forms.

What should I do if I see a data discrepancy between an API response and Ads Manager?

Take the following actions to address the main reasons for data discrepancies between the API and Ads Manager:

Match conversion settings

Make sure you are using the same conversion settings in Ads Manager as when you fetch data from an API endpoint, such as
GET
Get targeting analytics for ad groups
.
Note how the following enums in the
conversion_report_time
parameter correspond to Conversion date settings in Ads Manager:
Conversion date enums mapping
EnumsCorresponding Ads Manager conversion date settings
TIME_OF_AD_ACTION

(Default. Point in time when the user interacts with the ad.)
Date of ad event
TIME_OF_CONVERSION

(Point in time when conversion event occurs.)
Date of conversion event
Note how the following parameters and enums correspond to three sets of numeric values in Conversion window settings:
Conversion window enums mapping
ParameterDescriptionDefault enumCorresponding Conversion window value
click_window_days
Number of days to use as the conversion attribution window for a Pin click action.
30"click" (First set of numerals: 30/30/1)
engagement_window_days
Number of days to use as the conversion attribution window for an engagement action, such as save, closeup, link click, or carousel card swipe.
30"engagement" (Second set of numerals: 30/30/1)
engagement_window_days
Number of days to use as the conversion attribution window for a view action.
1"view" (Third set of numerals: 30/30/1)
Conversion settings

Check date range

Make sure the
start_date
and
end_date
values in your analytics endpoints match the date range filter settings in Ads reporting.
Conversion settings

Check for "zero" values

If you do not see certain values returned by an analytics endpoint, check whether the corresponding Ads Manager report contains values of 0.
Analytics endpoints only return arrays with data. If a specific campaign has only values of 0 returned for all requested data, it will not be included in the response.

Get help

If you still see discrepancies after taking these actions, file a Support ticket:
  1. Go to Get more help in Help Center.
  2. Select Pinterest API and Developer Tools.
  3. Select Developer site and click Continue.
  4. Select API Technical Support and click Continue.
  5. Enter requested information in the forms.

Some data is missing in the response from an analytics endpoint. What should I do?

If you do not see certain data returned by an analytics endpoint, check whether the corresponding Ads Manager report contains values of 0.
Analytics endpoints only return arrays with data. If a specific campaign has only values of 0 returned for all requested data, it will not be included in the response.

How do I access the multiple Pin analytics?

The endpoint is a closed beta feature. See Using beta and restricted features for guidance on requesting access.

How can I check whether I am close to exceeding a rate limit?

To monitor your request tally against your rate limit, set up verbose output with your API requests, so that you can view rate limit information in the response header. See Manage rate limits.

How do I transition from a testing API environment to a production environment?

When you are ready to move on from Sandbox to a production environment, take the following actions, as detailed in the Sandbox guide:
  • Modify API endpoint URLs by removing the substring
    -sandbox
    .
  • Start using a production token instead of a Sandbox token.
  • Request standard access if you do not have it yet.

I expect the Get Pin endpoint to return a video URL, but it returns "null". What should I do?

First, make sure your app has access to the video URL by verifying the following:
  • Your organization has access to the
    video_url
    feature, which is restricted. Ask your Pinterest representative if you are not sure.
  • Your access token includes the
    pins:read
    scope. Use Token Debugger to check your scopes. If necessary, generate a new token with the
    pins:read
    scope.
  • Your app has been granted access to the video URL. If the asset belongs to a partner, use the API to see if you have access and request it if necessary.
If
GET
Get Pin
keeps returning
null
for
video_url
after you have taken the preceding actions, contact your Pinterest representitive or reach out to Support for help:
  1. Go to Get more help in Help Center.
  2. Select Pinterest API and Developer Tools.
  3. Select API Technical Support and click Continue.
  4. Select Pinterest API v5 and click Continue.
  5. Enter or provide requested information in each form, clicking Continue to advance to the next form. Then click Submit on the last form.

How do I access metro zone/code information through the API?

To see your campaign, ad group, or ads analytics by country or metro zone or code, set the
targeting_type
parameter to
LOCATION
when calling an analytics endpoint. A successful request returns the code and the associated analytics. Learn more about seeing zone and code information.

How do I publish ad-only Pins?

To publish ad-only Pins, do the following:
  1. Create an ad using the
    POST
    Create ads
    endpoint.
  2. Specify the appropriate
    pin_id
    values for the Pins you want to publish.
  3. Set the
    is_removable
    parameter to
    true
    .

What should I do to debug persistent internal server errors?

If your API requests return internal server errors, file a Support ticket to have them addressed and resolved:
  1. Go to Get more help in Help Center.
  2. Select Pinterest API and Developer Tools.
  3. Select Developer site and click Continue.
  4. Select App management support and click Continue.
  5. Enter or provide requested information in each form, clicking Continue to advance to the next form. Then click Submit on the last form.

What are the available dimensions for pulling geographic data via Pinterest API?

To find out what geographical information you can fetch from the API, see Set up targets for your ads.

What do integer values mean for entity statuses in reports?

The
CAMPAIGN_ENTITY_STATUS
and
AD_GROUP_ENTITY_STATUS
reporting columns return integer values that map to statuses:
Entity integer mapping
IntegerStatusDefinition
1
Active
The entity is enabled and may deliver when other delivery requirements are satisfied.
2
PausedThe entity is disabled and cannot deliver until reactivated.
3
Archived
The entity is permanently retired. Archiving cannot be undone, but historical reporting remains available.
Note that campaign management endpoints
GET
Get campaign
,
GET
Get ad group
, and
GET
Get ad
return equivalent string enum values
ACTIVE
,
PAUSED
, and
ARCHIVED
for the
status
response field.
Entity status is different from the
summary_status
field returned by the campaign management endpoints. Entity status represents the state explicitly assigned to an entity:
ACTIVE
,
PAUSED
, or
ARCHIVED
. It corresponds to the
status
field returned by campaign management endpoints. The separate
summary_status
field represents the entity's computed delivery state, considering its entity status together with factors such as scheduling, budget, parent-entity status, and review status. Possible
summary_status
fields are
RUNNING
,
PAUSED
,
NOT_STARTED
,
COMPLETED
, and
ADVERTISER_DISABLED
.
Entity status is different from the
summary_status
field returned by the campaign management endpoints. Entity status represents the state explicitly assigned to an entity:
ACTIVE
,
PAUSED
, or
ARCHIVED
. It corresponds to the
status
field returned by campaign management endpoints. The separate
summary_status
field represents the entity's computed delivery state, considering its entity status together with factors such as scheduling, budget, parent-entity status, and review status. Possible
summary_status
fields are
RUNNING
,
PAUSED
,
NOT_STARTED
,
COMPLETED
, and
ADVERTISER_DISABLED
.

Endpoints that expose CAMPAIGN_ENTITY_STATUS

GET
Get campaign analytics
GET
Get ad group analytics
GET
Get ad analytics
GET
Get Pin analytics
POST
Create async request for an account analytics report
at the
CAMPAIGN
,
AD_GROUP
, and
PIN_PROMOTION
report levels

Endpoints that expose AD_GROUP_ENTITY_STATUS

GET
Get ad group analytics
GET
Get ad analytics
GET
Get Pin analytics
POST
Create async request for an account analytics report
at the
AD_GROUP
and
PIN_PROMOTION
report levels

Miscellaneous FAQs

Get answers to questions about other topic categories.

It looks like users are not requesting images directly from my site. Why?

When a Pinner requests an image from your website to use for a Pin, the Pinterest platform proxies the image request for security and performance reasons. Users still see their requested images as intended, but the requests originate from our servers instead of their browsers. Learn more about image proxy requests.

How can I verify if an image request is proxied from the Pinterest platform?

Check the User-Agent header in your server logs. Our requests include a platform-specific identifier, as in the following example:
Mozilla/5.0 (Pinterest Image Proxy/1.0; +https://www.pinterest.com/image-proxy.html)
Learn more about image proxy requests.

Where do I find my business ID?

To find your business ID, which you need for several API requests, do the following:
  1. Go to pinterest.com and log in to your account.
  2. Next to your name, click the down arrow, which then points up.
  3. Under Businesses/Assets, click the left arrow next to your name.
  4. Note the 18-digit business ID, which appears under your name in the black rectangle.
Locate Business ID step 1
Locate Business ID step 2

Where do I find my ad account IDs?

To find your ad account IDs, do the following:
  1. Go to pinterest.com and log in to your account.
  2. Next to your name, click the down arrow, which then points up.
  3. Under Businesses/Assets, select Ad accounts below your name.
  4. Under All ad accounts, click the down arrow, which then points up.
  5. If you have multiple ad accounts, find the account with the relevant user name or email address.
    • You also can search for your email address or account name.
  6. Note the multiple-digit identifier, which appears next to the ID: label.
Ad account ID location

How do I request a video URL?

To request a video URL, file a Support ticket. The Support team will review your request and let you know if they can provide the URL.
  1. Go to Get more help in Help Center.
  2. Select Pinterest API and Developer Tools.
  3. Select Request Access to Beta or Advanced Features and click Continue.
  4. Enter or provide requested information in each form, clicking Continue to advance to the next form. Then click Submit on the last form.
Was this page helpful?