Sandbox documentation

Pinterest's API Sandbox allows you to test your integration with Pinterest API (v5) in a safe way, without affecting your production data. Once you have tested your integration and are ready to flip the switch to production, you can update your code to point your API calls to the production environment.

Getting started

The set up process for Sandbox is very similar to the process in production.

1. Set up your application

Set up an app as outlined here

2. Generate a Sandbox access token

Go to the app management page to generate a Sandbox access token, which will be tied to your Pinterest user account. You will need to use this token for all your API calls to the Sandbox environment.

To generate a Sandbox access token take the following steps:

Visit the My Apps page
Select Manage on the app for which you’d like to create a Sandbox access token
On the Configure tab scroll down to the Generate Access Token section
Select Sandbox as the environment, then click the red Generate token button

3. Begin making Sandbox requests

Use the Sandbox access token to make requests to the endpoints at api-sandbox.pinterest.com.

About Sandbox

Out of the box, your Sandbox environment does not contain any data or entities.
Sandbox is available in all access tiers – Trial, Standard or Advanced. You can make successful API calls to the Sandbox environment regardless of which access tier your app is in.
In Sandbox, ads are not reviewed. When you create an ad in production, the ad goes through an internal ad review process, and the response you receive from the API will include review_status with a value of approved, rejected, or pending. In Sandbox, this process is bypassed. The "create ads" API call in Sandbox will always return review_status: approved. You will also see review_status in the response for "list ads", "update ads", and "get ad".
Metrics for Pins created in Sandbox. Pins created in Sandbox will not be production Pins. They will not receive distribution within Pinterest and will not be seen by any Pinners other than the owner of the Pin, whether in the Pinterest mobile apps or on the web. As the owner of the Pin, you will see the Pins you create in Sandbox in the Pinterest mobile apps or on Pinterest.com. As you view the Pins in Sandbox and interact with them, the Pins will collect views and other metrics-based events. If you want to test the metrics endpoints, you can use the production metrics endpoints on your Sandbox Pins.

Making calls to Sandbox

The base URL for the Sandbox environment is https://api-sandbox.pinterest.com/v5/. Use this base in the request path when you are trying to call the Sandbox API. Everything else about the call will be the same – the request header, the request body if any, and the response body. The only element of the request path that will change is that instead of “api.pinterest” it will read “api-sandbox.pinterest”.

Note:

Calls made to the Sandbox environment will only return Sandbox entities.

Examples -- Production vs Sandbox

Action	In Production	In Sandbox
Get a list of boards the user can access	GET https://api.pinterest.com/v5/boards --header 'Content-Type: application/json' --header 'Authorization: Bearer <PRODUCTION TOKEN>'	GET https://api-sandbox.pinterest.com/v5/boards --header 'Content-Type: application/json' --header 'Authorization: Bearer <SANDBOX TOKEN>'
Create a board section	POST https://api.pinterest.com/v5/boards/{board_id}/sections --header 'Content-Type: application/json' --header 'Authorization: Bearer <PRODUCTION TOKEN>'	POST https://api-sandbox.pinterest.com/v5/boards/{board_id}/sections --header 'Content-Type: application/json' --header 'Authorization: Bearer <SANDBOX TOKEN>'
Delete a board	DELETE https://api.pinterest.com/v5/boards/{board_id} --header 'Content-Type: application/json' --header 'Authorization: Bearer <PRODUCTION TOKEN>'	DELETE https://api-sandbox.pinterest.com/v5/boards/{board_id} --header 'Content-Type: application/json' --header 'Authorization: Bearer <SANDBOX TOKEN>'

Endpoints supported in Sandbox

Only the endpoints below are supported in Sandbox at this time. Over time, we will add support for all Pinterest API (v5) endpoints to Sandbox.

Boards and Pins

Get board
Create board
Delete board
Get Pin
Create Pin -- for static image Pins only. Video Pin creation isn’t currently supported in Sandbox.
Delete Pin

Ads

Create ad preview -- You can see the ad preview you created in Sandbox on ads.pinterest.com, but it won’t be live or be shown to Pinterest users.
Create ads
Update ads
Get ad

Ad groups

Campaigns

Ad account

Terms

Get related terms (logically related)
Get suggested terms (terms often searched for together)

Terms of Service

Get terms of service

Entities in Sandbox vs. production

Entities created in Sandbox will be not visible to anyone on Pinterest other than the owner of the entities. As the owner, you will be able to view the boards and Pins you create in Sandbox when you visit your own Pinterest user profile in the Pinterest mobile apps or on Pinterest.com.

Entities in the Sandbox environment are separate from entities in the production environment. For example, you cannot use a Pin in Sandbox to create an ad in production.

Sandbox-only endpoints

Currently, the only Sandbox-specific endpoint is the DELETE ad_accounts/{ad_account_id} endpoint.

Delete ad account (Sandbox only)

Delete the ad account in Sandbox, along with all the entities associated with it in Sandbox, including ads, ad groups and campaigns. This endpoint is only available in the Sandbox environment. The response will include a string indicating the status of the delete operation.

ratelimit-category: ads_write

AUTHORIZATIONS: pinterest_oauth2: (ads:write)

PATH PARAMETERS

ad_account_id (Required)Type: String Unique identifier of an ad account

Example Request

DELETE https://api-sandbox.pinterest.com/v5/ad_accounts/{ad_account_id}

Example Response (success)

204 -- Successfully deleted ad account

Example Response (failure)

403 -- not authorized to access ad_account

404 -- ad account not found

How to switch from Sandbox to production

When you are done testing your integration, switch from Sandbox to production with these steps:

Update your URLs from using https://api-sandbox.pinterest.com – the Sandbox environment – to using the production environment at https://api.pinterest.com/v5/.
Clear out your Sandbox. If you wish to clear out your Sandbox, you can:

Delete any ad accounts you created in Sandbox. The Sandbox-specific `DELETE ad_account` endpoint will delete the ad account and all its child entities (including campaigns, ad groups, and ads) from Sandbox. This endpoint and the ability to delete an ad account only exists in Sandbox.
Delete Pins or boards you created in Sandbox with delete Pin and delete board.

Current limitations

Account interoperability. You can only provision a Sandbox account for a business account you own.
Creation of video Pins. Creation of video Pins is not supported in Sandbox yet.
Interoperability with the rest of ads or organic delivery. The Sandbox environment does not simulate the ads auction, feed status checks, conversion upload, or bulk editing.
No support for Business Access. No support for testing Business Access in Sandbox. You should use Sandbox with the assumption that you are the owner of the ad account, the associated entities, and the Pins/Boards.
No support for Catalogs or Shopping Ads. We currently do not support catalog and item metadata endpoints in the sandbox, so you cannot create or manage either catalogs or Shopping Ads in Sandbox.
Cannot use production entities with Sandbox entities. Entities in the Sandbox environment are separate from entities in the production environment. For example, you cannot use a Pin in Sandbox to create an ad in production.