Skip to content

Developer Platform

Search docs & API
Log in
Sign up

Sandbox

Use Sandbox to test your integration with Pinterest API v5 without affecting your production data. After successful testing, you can update your code to point your API calls to the production environment.

What you can do in Sandbox

You can make API calls in Sandbox to the following endpoints with a Trial or Standard access tier.
You can view boards and Pins you create in Sandbox when you visit your own Pinterest user profile in the Pinterest mobile apps or on Pinterest.com.
Endpoints that appear in the following lists are available in Sandbox.
About this list:
  • We structured this list to reflect the left-panel navigation of the API reference.
  • We check for updates on a quarterly basis (Most recent update: September 8, 2026).

Pins and boards

Pins

  • GET
    List Pins
  • POST
    Create Pin
  • GET
    Get Pin
  • DELETE
    Delete Pin
  • PATCH
    Update Pin
  • POST
    Save Pin

Boards

  • GET
    List boards
    In Sandbox, this endpoint can return an empty items array with a bookmark even when Sandbox boards exist. Keep requesting the next page with the bookmark until Sandbox boards appear, or the bookmark is exhausted. A larger
    page_size
    (maximum 250) can reduce how many empty pages you walk. Production boards are filtered out of each page after it is fetched.
  • POST
    Create board
  • GET
    Get board
  • PATCH
    Update board
  • DELETE
    Delete board
  • GET
    List Pins on board
  • GET
    List board sections
  • POST
    Create board section
  • PATCH
    Update board section
  • DELETE
    Delete board section
  • GET
    List Pins on board section
Do not create a Sandbox Pin with a group board. Although the Pin would only be only visible to you, the board owner may receive a notification that a Pin was created, resulting in confusion. Learn more about boards.
Do not create a Sandbox Pin with a group board. Although the Pin would only be only visible to you, the board owner may receive a notification that a Pin was created, resulting in confusion. Learn more about boards.
Media
  • GET
    List media uploads
  • POST
    Register media upload
  • GET
    Get media upload details

User accounts

  • GET
    Get user account
  • GET
    List linked businesses
  • GET
    List followers
  • GET
    List following boards
  • POST
    Follow user
  • GET
    List following interests

Campaign management

Ad accounts

  • GET
    List ad accounts
  • POST
    Create ad account
  • GET
    Get ad account
  • GET
    Get ad account analytics
  • DELETE
    Delete ads data for ad account in API Sandbox
    Only available in Sandbox.
  • GET
    Get targeting analytics for an ad account
  • GET
    List templates

Campaigns

  • GET
    List campaigns
  • POST
    Create campaigns
  • PATCH
    Update campaigns
  • GET
    Get campaign analytics
  • GET
    Get targeting analytics for campaigns
  • GET
    Get campaign

Ad groups

  • GET
    List ad groups
  • POST
    Create ad groups
  • PATCH
    Update ad groups
  • GET
    Get ad group analytics
  • GET
    Get targeting analytics for ad groups
  • POST
    Get audience sizing
  • GET
    Get ad group
  • POST
    Get bid floors

Ads

  • POST
    Create ad preview with pin or image
    Visible to you in Sandbox but not live or visible to Pinterest users.
  • POST
    Create ad preview records for one or more ad groups
  • GET
    Fetch ad preview records for one or more ad groups
  • DELETE
    Delete ad preview records for one or more ad groups
  • GET
    List ads
  • POST
    Create ads
  • PATCH
    Update ads
  • GET
    Get ad analytics
  • GET
    Get targeting analytics for ads
  • GET
    Get ad

Labels

  • POST
    Create labels
  • GET
    List labels
  • PATCH
    Update labels

Targeting

Keywords

  • GET
    Get keywords
  • POST
    Create keywords
  • PATCH
    Update keywords
  • GET
    Get country's keyword metrics
  • GET
    List trending keywords

Targeting templates

  • PATCH
    Update targeting templates

Customer segments

  • PATCH
    Update customer segments

Ad formats

Lead forms

  • GET
    List lead forms
  • GET
    Get lead form by id

Lead ads

  • POST
    Create lead ads subscription

Leads export

  • POST
    Create a request to export leads collected from a lead ad
    Closed beta

Billing

Billing

  • GET
    Get Salesforce account details including bill-to information.
  • POST
    Create insertion order through SSIO.
  • PATCH
    Edit insertion order through SSIO.
  • GET
    Get insertion order status by ad account id.
  • GET
    Get insertion order status by pin order id.
  • GET
    Get Salesforce order lines by ad account id.

Order lines

  • GET
    Get order lines.
  • GET
    Get order line

Terms of service

  • GET
    Get terms of service

Business access

Business access invite

  • PATCH
    Accept or decline an invite/request

Business access relationships

  • GET
    List business employers for user
  • DELETE
    Terminate business memberships

Others

Advanced auction

  • POST
    Get item bid options (POST)
  • POST
    Operate on item level bid options

Integrations

  • POST
    Receives batched logs from integration applications.

Notifications

  • POST
    Receive notifications from external partners.

OAuth

  • POST
    Generate OAuth access token
  • POST
    Generate OAuth access token for conversion API
  • POST
    Revoke a token

Resources

  • GET
    Get ad accounts countries
  • GET
    Get available metrics' definitions
  • GET
    Get lead form questions
  • GET
    Get metrics ready state
  • GET
    Get interest details
  • GET
    Get targeting options

Terms

  • GET
    List related terms
    Logically related terms.
  • GET
    List suggested terms
    Search terms often entered together.

Shopping

Catalogs

  • GET
    List catalogs
  • POST
    Create catalog
  • GET
    List available filter values
  • POST
    Create collaborative catalog
    Closed beta

Auto-localization

  • POST
    Create auto-localization config
  • GET
    Get auto-localization config
  • PUT
    Update auto-localization config
  • GET
    List translations
  • POST
    Review translations

Feeds

  • GET
    List feeds
  • POST
    Create feed
  • GET
    Get feed
  • PATCH
    Update feed
  • DELETE
    Delete feed
  • POST
    Ingest feed items
  • GET
    List feed processing results
  • GET
    List item issues

Product groups

  • DELETE
    Delete product groups
  • POST
    Create product groups
  • GET
    List product groups
  • POST
    Create product group
  • GET
    Get product group
  • DELETE
    Delete product group
  • PATCH
    Update single product group
  • GET
    Get product counts
  • GET
    List products by product group
  • POST
    List products by filter

Items

  • POST
    Get catalogs items (POST)
  • POST
    Operate on item batch
  • GET
    Get item batch status

Sandbox limitations

Use Sandbox only for your own ad account, associated entities, Pins and boards.
Also, note that entities in your Sandbox environment are separate from entities in your production environment. For example, you cannot use a Pin in Sandbox to create an ad in production.
You cannot do the following in Sandbox, although some of these capabilities may be supported in the future:
  • Create video Pins.
  • Create or manage shopping ads.
  • Test business access.
  • Simulate the ads auction, feed status checks, conversion upload, or bulk editing.

Start using Sandbox

Step 1. Set up your app

If you have not yet set up your app to work with Pinterest, follow the instructions on the app setup page to connect and configure an app.

Step 2. Generate a Sandbox access token

To use Sandbox, you need a specific token, which is tied to your Pinterest user account. You cannot use the Sandbox token in your production environment, nor can you use a production token for Sandbox.

Generate a token on your app management page

You can generate a Sandbox token quickly and easily on your app management page. The token lasts 30 days, after which, you could generate a new one if necessary.
  1. Go to the My Apps page.
  2. Select Manage for the app you want to give Sandbox access.
  3. In the Configure tab, scroll down to the Generate Access Token section.
  4. Select Sandbox as the environment.
  5. Click Generate token.
  6. Copy the generated token, to use in Sandbox API calls.

Generate a token using the OAuth flow

You can also generate a Sandbox token using the OAuth flow. This could be useful if you want to continuously refresh the token for long-term testing in Sandbox. Also, with an OAuth token, you can select specific scopes.
When calling
POST
Generate OAuth access token
you would insert
-sandbox
in the URL request path as in the following example:
curl -X POST https://api-sandbox.pinterest.com/v5/oauth/token \
See the full guide for generating an access token using the OAuth flow.

Step 3 (If necessary): Generate a Sandbox advertiser ID

If you need to call any endpoints in Sandbox that require an
advertiser_id
, create one specifically for Sandbox, because your production ID will not be recognized in that environment.

Endpoint

POST
Create ad account
Any parameters and code examples that appear in this section support this use case, but may not represent the full endpoint specification. See the endpoint reference page for the comprehensive spec.
Any parameters and code examples that appear in this section support this use case, but may not represent the full endpoint specification. See the endpoint reference page for the comprehensive spec.

Example request

Note that the request URL includes
-sandbox
.
curl --request POST \
  --url https://api-sandbox.pinterest.com/v5/ad_accounts \
  --header 'authorization: Bearer pina_ABCD1234...' \
  --header 'content-type: application/json' \
  --data '{
  "name": "Sandbox ad account"
}'

Example response

The endpoint returns an advertiser ID for Sandbox in the
id
field.
{
  "id": "549768356618",
  "name": "Sandbox ad account",
  "owner": {
    "username": "my-name",
    "id": "878976189681867089"
  },
  "country": "US",
  "currency": "USD",
  "permissions": [],
  "created_time": 1778860038,
  "updated_time": 1778860038
}

Step 4. Start making Sandbox requests

Making API calls in Sandbox is identical to making calls in production, except that the subdomain in the endpoint path is
api-sandbox.
.

Example

GET https://api-sandbox.pinterest.com/v5/boards --header 'Content-Type: application/json' --header 'Authorization: Bearer [SANDBOX-TOKEN]'

Switch to production

When you finish testing your integration, switch from Sandbox to the production environment.
Two of the following actions, deleting Sandbox ad accounts and removing Sandbox Pins and boards, are optional and may be useful if you want stop testing in Sandbox or want to clean up leftover data. You can, however, retain Sandbox data if you need to.

Make sure you have standard access

If you have been using the API with trial access, you will need to switch to standard for production-level rate limits. Also, any Pins and Boards you create with trial access are visible only to you in Sandbox.
Learn how to get standard access.

Switch to a production advertiser ID

For any endpoints that require the
advertiser_id
parameter, make sure you have an ID for a production environment. If you need to generate one, follow Step 3, but remove
-sandbox
from the request URL.
Example:
--url https://api.pinterest.com/v5/ad_accounts \

Switch to a production token

Use a production token in your API calls. Learn how to generate an access token for all the endpoints you will need to use in production.

Remove "-sandbox" from your requests

  • Remove
    -sandbox
    from your endpoint URLs, so that the subdomain is
    api.
    .
Example:
GET https://api.pinterest.com/v5/boards --header 'Content-Type: application/json' --header 'Authorization: Bearer [PRODUCTION-TOKEN]'

Optional: Delete Sandbox ad accounts

Delete any ad accounts you created in Sandbox.

Endpoint

DELETE
Delete ads data for ad account in API Sandbox
(Only available for Sandbox IDs)
Calling this endpoint deletes the ad account and any child entities, including campaigns, ad groups, and ads.

Example request

curl --request DELETE \
  --url https://api-sandbox.pinterest.com/v5/ad_accounts/549768356618/sandbox \
  --header 'authorization: Bearer pina_ABCD1234...'

Example success response

204 -- Successfully deleted ad account

Example failure responses

403 -- not authorized to access ad_account

404 -- ad account not found

Optional: Delete Sandbox Pins and boards

Endpoints

DELETE
Delete Pin
DELETE
Delete board
Was this page helpful?