Skip to content

Developer Platform

Search docs & API
Log in
Sign up

Best practices

Each app will require a different set of endpoints to be successful. Before you get to implementing the Pinterest API in your app, we recommend reviewing these additional guidelines to set your app up for long term success.

App security

It is critical that you keep authentication information, such as your app secret, certificate key, and access tokens out of code. We recommend keeping them in an untracked file and loaded into your shell environment.
When using a file to store an access token, make sure your token is Read/Write for the Owner only (e.g. 600 (rw-----)).
When specifying credentials in environment variables, export it from a script file instead of on the shell command line. See our example in the Pinterest API quickstart on Github. Commands, along with the clear text credentials, are often stored in history and log files. An attacker may obtain access to those files, so having credentials recorded in them is a serious risk for your application.
We recommend that any files you use to store your credentials and access tokens be listed in a source code configuration file (e.g. .gitignore in git) to help avoid checking this material into a source code repository. Pinterest participates in the Github Secret Scanner Program for leaked tokens.

Relying on ID fields

Product decisions around usernames, IDs, and other PII-related fields via the Pinterest API continue to evolve to better protect and address the needs of our Pinners. We make these decisions with the full appreciation and understanding that even small changes to API behavior can have a large impact on how our partners operate and use the API. Where possible, we recommend planning for and building application logic that is robust and not solely dependent on specific user identification fields returned by our API.
  • username
    is globally unique on Pinterest but it can be changed at any time.
  • Some example of IDs globally unique across Pinterest are:
    1. Board ID
    2. Pin ID
    3. Ad account ID

Recommendations

  • Usernames are unlikely to change on a daily, or even weekly/monthly basis: We recommend you check the value of the field on initial authorization and on some ongoing/regular basis.
  • Please don't build any app functionality that shares data or access based solely on the value of the
    username
    field: It's possible that once a username is changed, a new or different user account may take the username previously associated with a different account.
  • If an end user of your application is authorizing access to a new Pinterest user account: Ask if this is a new account or the same as one that they had previously authorized.
  • You may use ownership or access to other resources and their IDs, such as boards, pins, ad accounts, in combination with username: A way to gauge continuity with a new authorization - but as boards/pins/etc may be deleted over time - this is not a 100% reliable method.

Scheduled content publishing

  • Board identification: Boards do not require a username or user ID to be created. They will default to the authenticated user associated with the access token.
  • Pins only require a board ID to be created: Board IDs are fixed and globally unique.
  • If a user of your application loses access before scheduled content goes out: When they re-authorize, you can both assess if the new token has access to the previously scheduled resources and ask the user "Would you like to keep this schedule you previously created for account X?"

Historical analytics and performance data

  • Tracking performance: Where possible you can track performance at a granular, resource level, as in ad account ID, board ID, pin ID. These IDs are fixed and unique.
  • If a user of your application loses access or re-authorizes with a new token: You can both check what resources they have access to with the new token and ask the user "Would you like to merge this previous historical data associated with account X?"
  • If you have multiple users authorizing or accessing the same account ad data: You may want to consider building sharing mechanisms based on user accounts within your platform, not based strictly on IDs or usernames returned through the Pinterest API.

Monitoring spam and abuse

We work hard to detect and remove spam from our platform. We monitor the amount of spam created or spread via 3rd applications. As we state in our Developer Guidelines "apps that contribute to spam on Pinterest may be removed".

Developer strikes and deactivations

If our system detects spam content created via your app, we will issue your app a strike and you will be notified by email. You should investigate your app's activity and implement measures to prevent your users from abusing your app.
If you believe you've received a strike in error submit an appeal in our Help Center:
  1. Select Appeals by clicking the down-arrow ⌄ to expand it
  2. Click the radio button to select App strike/suspension
  3. Click Continue and complete the required information
  4. Click Submit to submit your appeal
If your app receives three strikes, it will be banned from Pinterest and notified by email.
If your app has been banned, you won't be able to activate new apps on Pinterest. All other apps owned by the same account will be suspended.

Preventing spam

Preventing your app from being used to distribute spam is in the best interest of your users, your app, and Pinterest. Here are some approaches to preventing spam:
  • Require email verification: Requiring email verification provides one more hurdle for spammers, while creating a minimal challenge to legitimate users. It can even give legitimate users a sense of security
  • Track the time it takes a user to begin creating content: Monitor the time it takes for a new user to go from creating an account to creating content: if that time is only a few seconds, the odds are good that the user is in fact a bot, and a risk for spam.
  • Limit the number of Pins a free account can create: Limiting the number of Pins that free accounts can create to a reasonable but small daily or weekly number means that spammers will have to do more work to take advantage of your application. Using a freemium model to control which accounts can create more Pins also decreases the odds that spammers will try to misuse your application.
  • Implement rate limits for Pin creation: Not many users will create hundreds of Pins in a few minutes.
  • Limit the creation of duplicate content: Is the content being submitted for creation by your users identical? Check descriptions, titles, and urls for duplicate content. If a user is submitting significant amounts of duplicate content, they should be considered a spam risk.
  • Check user accounts for similar email addresses: Look for common patterns in email addresses like
    {randomwords}{randomnumbers}@{website}
    . Those patterns often indicate a user is a spam risk.
  • Check users' IP addresses for duplicates: If you find that a number of profiles are coming from a single IP address, consider adding that IP address to a ban list.
  • Check for bots.
  • Secure your Pinterest app secret key: Ensure that your Pinterest app secret key is kept secure and don't share it with anyone unnecessarily. It is used for your app to interact with the Pinterest API. If you suspect that your app secret key leaked, reach out to us via the Help Center immediately. We will regenerate your app secret key so that you can re-authorize your existing customers.
  • Secure your users' access tokens: Ensure that the access tokens issued to your application's users are secured. The access token will permit the user to perform the tasks they request using your application. These tokens should never be sent using the insecure http protocol. Comply with best practices for session time-out and session closure, and avoid using access tokens in any context in which they could be captured by malicious users or third parties.

Helpful resources

  • M3AAWG: Best Practices for Mitigating Abuse of Web Messaging Systems
  • Rate Limits:
    • Leaky Bucket
    • Token Bucket
    • Stack Overflow: What's a good rate limiting algorithm?
  • Checking IP Addresses
    • CleanTalk will let you check IP addresses for duplicates
  • Checking for bots
    • reCAPTCHA helps detect bots
Was this page helpful?