Skip to content

Developer Platform

Search docs & API
Log in
Sign up

Share business access

Pinterest enables the sharing of access to ad accounts and assets—within and between businesses—to help you build and scale campaigns more efficiently and improve security and collaboration.
Use this guide to learn how sharing works through the API with the following activities, depending on your business needs:
  • Gain access to ad accounts and assets that others are sharing with you.
  • Share your ad accounts and control what people do with them.
  • Manage sharing relationships within your own, and other, businesses.
  • Manage advertising assets and who can access them.
You can also perform these operations manually with the Business Manager user interface. See the Help Center articles listed in the Learn more section below.
You can also perform these operations manually with the Business Manager user interface. See the Help Center articles listed in the Learn more section below.

How account sharing works

A business account is the top organizational level for account sharing. It includes a profile, which enables you to promote your products or services organically on Pinterest with Pins and boards.
A business account may also include one or more ad accounts, which control segments of advertising activity, such as campaign and ad creation.
After establishing business and ad accounts, a business invites people to perform designated activities within the ad accounts or the business profile.
Once the invitees accept, the inviting business assigns them specific permissions that define what they can do.

The sharing flow at a high level

In the following diagram, user ABC owns a business account 1234 with the child ad account 1000.
Using either Business Manager or the API, they invite user XYZ from business account 5678 to access the ad account (1).
User XYZ accepts the invitation (2).
User ABC grants user XYZ permissions to do the following through the app on which the latter is authenticated:
  • Work with ad account 1000.
  • Fetch Pin 01 and its board for ad creation from user ABC's business profile.
Business access sharing diagram

How roles and permissions work

It is important to understand what business roles and permissions control and allow, whether:
  • You have been invited to work in a shared ad account.
  • You want to invite people to work in your ad accounts and control what they do.

Business roles

The initial invitation to work in a shared account includes a business role assignment:
Business role table
Business roleAbilities/accessYour business or another?
Employee
Accesses ad accounts and profiles to which you grant them access. An employee cannot add other employees or grant them access.
Your business
Manager
(
BIZ_ADMIN
in the API)
Has full control of roles and can add employees or business partners, as well as grant access to ad accounts, profiles.
Your business
Partner
Can access campaigns, ad groups, and assets in the account that is shared with them.
In the context of the API:
  • An internal partner is someone with whom you share accounts that you own.
  • An external partner is someone who shares accounts that they own with you.
Another business
In the API reference, employees and managers are collectively referred to as
members
.
In the API reference, employees and managers are collectively referred to as
members
.

Asset permissions

When an invitee accepts a request, the person who invited them then assigns them permissions, which define what they can do.
In the following table the first six permissions are related to ad account activity. The final permission, Publisher, is related to the business profile as organic activity is at the profile level.
business permission types table
Permission
Admin
Analyst
Audience
Finance
Campaign
Catalogs
Publisher
Create and edit campaigns, ad groups and ads
✔
 
 
 
✔
 
 
View billing and business settings
✔
 
 
✔
✔
 
 
Edit billing and business settings
✔
 
 
✔
 
 
 
View reporting
✔
✔
 
 
✔
 
 
View conversion tags
✔
✔
✔
 
✔
 
 
Create and edit conversion tags
✔
 
 
 
✔
 
 
View audiences
✔
✔
✔
 
✔
 
 
Create and edit audiences
✔
 
✔
 
 
 
 
View analytics
✔
✔
 
 
 
 
 
Create and edit data sources and product groups
✔
 
 
 
 
✔
 
Upload conversion files in Ads Manager
✔
✔
✔
 
✔
 
 
Create, edit, delete, and view public and secret boards
 
 
 
 
 
 
✔
Archive and merge boards
 
 
 
 
 
 
✔
Collaborate on group boards
 
 
 
 
 
 
✔
Create organic Pins, idea ads, standard image ads, carousel ads, shopping ads, and collection ads
 
 
 
 
 
 
✔
Edit and delete Pin formats
 
 
 
 
 
 
✔
Take actions on the Pin details page, like move to another board, tag products, add note to self, add comments
 
 
 
 
 
 
✔
Schedule Pins to publish in the future
 
 
 
 
 
 
✔
View individual Pin stats
 
 
 
 
 
 
✔
Edit profile cover photo
 
 
 
 
 
 
✔

Using this guide for sharing access through the API

Note the following when using the following tables in this guide:
  • In this guide, we have organized the relevant API endpoints according to use case categories.
  • Several endpoints in this guide have multiple use cases. For example,
    POST
    Create invites or requests
    is used for sharing assets that your business owns or asking a business to share their owned assets with you.
  • In the tables, we provide tips for using parameters that help with each use case. We do not fully list the parameters for endpoints. Always see any endpoint in the API reference page for a full list of parameters.
  • Certain parameters for those endpoints also have multiple use cases. The description for each parameter and endpoint is specific to the stated use case.
  • Your
    business_id
    is a required parameter for these requests. Find your business ID.

Gain, or request access to, accounts

Gaining access to shared business accounts involves accepting invitations. You also can request access to accounts that you want to work in.

Request access to a business account

If you have not been invited yet to share a account that you want to work in, you can request access.
POST
Create invites or requests
Tips for using request parameters
See the endpoint for a full list of parameters.
create invites requests table
Parameter
How to use it
business_role

string
required
Specify
PARTNER
to indicate that you want to gain access as a partner.
invite_type

string
required
Specify
PARTNER_REQUEST
to indicate that you want to gain access as a partner.
partners

string
Enter the business ID of the business you are requesting access from.
Tips for using response data
The endpoint returns an access request ID for a successful API request. If the request is unsuccessful, it also returns or it returns information about why the request failed.
See the endpoint for a full list of response data fields.
create invites response table
Field
How to use it
invite_id

string
Confirm that your access request was sent successfully.
Reference this ID if you want to cancel the request later.
exception.invite_or_request_id

string
required
Reference this ID (different from
invite.id
) for troubleshooting a failed API request.
exception.code

integer
Reference this code for troubleshooting a failed API request.
exception.message

string
Find out why the API request failed.
exception.user_or_partner_ids

string
For troubleshooting, contact listed people who were responsible for the error.

See pending invites sent to you or requests you sent

This is helpful to keep track of which assets you can get access to as well as to delete outgoing requests that are pending, if necessary.
GET
Get invites/requests
Tips for using request parameters
See the endpoint for a full list of parameters.
get invites requests table
Parameter
How to use it
is_member

boolean
For filtering, see only member invites and requests within your own business (
true
) or those for a partner with another agency.
invite_status

array
See
PENDING
or
EXPIRED
invites or requests.
You can only cancel pending access requests.
Tips for using response data
For a successful request the endpoint returns important information about the ad accounts and business profiles that you have been invited to access.
See the endpoint for a full list of returned fields.
get invites response table
Field
How to use it
items.assets_summary.ad_accounts.id

string
See which ad accounts you are being invited to access or are requesting to access.
Get more details about a particular ad account by calling
GET
Get ad account
.
items.assets_summary.ad_accounts.permissions

array of strings
See which permissions you are being granted or are requesting, so that you know what you can do in those ad accounts.
For invitations, the inviter may not include permissions in the initial invite but may include them in an updated invite.
items.assets_summary.profiles.id

string
See which business account profiles you are being invited to access or are requesting to access.
items.assets_summary.profiles.permissions

array of strings
See which permissions you are being granted or are requesting.
The inviter may send you permissions separately.
items.business_roles

array of strings
See which business roles you are being granted or are requesting.
items.invite_data.invite_expiration

integer
For invites, keep track of when the invite expires, so that you can respond in time.
items.created_by_business

object
Get metadata about this business that is sending the invite or request. inviting you or that you are requesting access from.
items.created_by_user

object
Get metadata about the person who is sending the invite or request.

Accept or decline an invite

Respond to new invites or invites that have been updated with added permissions.
PATCH
Accept or decline an invite/request
Tips for using request parameters
See the endpoint for a full list of parameters.
accept decline invites requests table
ParameterHow to use it
action.accept_invite

boolean
required
Accept (
true
) or decline (
false
) the invite.
action.asset_id_to_permissions

object
Map asset IDs to lists of business permissions.
This field currently is only for accepting or declining requests from people to access your assets.
invite_id

string
required
Identify the invite you are responding to (from the list of pending invites you requested).
Tips for using response data
For a successful request the endpoint returns important information about the ad accounts and business profiles that you have been invited to access.
See the endpoint for a full list of returned fields.
accept decline invites response table
Field
How to use it
invite_id

string
Confirm that your access request was sent successfully.
invite.user_id

string
Retain this unique member ID for reference in other business access requests.
exception.invite_or_request_id

string
Reference this ID (different from
invite.id
) for troubleshooting a failed API request.
exception.code

integer
Reference this code for troubleshooting a failed API request.
exception.message

string
Find out why the API request failed.
exception.user_or_partner_ids

string
For troubleshooting, contact listed people who were responsible for the error.

Request permissions for specific assets on a business account

Respond to new invites or invites that have been updated with added permissions.
POST
Update invite/request with an asset permission
Tips for using request parameters
See the endpoint for a full list of parameters.
request permissions for assets requests table
ParameterHow to use it
invite_id

string
required
Reference the unique identifier for the request you sent.
invite_type

string
required
Indicate whether the invite was for a member of your own business (
MEMBER_INVITE
) or an outside agency (
PARTNER_REQUEST
).
asset_to_id_permissions

object
required
Request specific permissions for the IDs of specific accounts to which you were invited.
Tips for using response data
The endpoint returns an access request ID for a successful API request. If the request is unsuccessful, it also returns or it returns information about why the request failed.
See the endpoint for a full list of returned fields.
request permissions for assets response table
Field
How to use it
invite_id

string
Confirm that your invite update was sent successfully.
exception.invite_or_request_id

string
Reference this ID (different from
invite.id
) for troubleshooting a failed API request.
exception.code

integer
Reference this code for troubleshooting a failed API request.
exception.message

string
Find out why the API request failed.
exception.user_or_partner_ids

string
For troubleshooting, contact listed people who were responsible for the error.

Cancel an access request

Cancel a request that is pending. You cannot cancel a request that has been accepted or declined. Check the statuses of your access requests.
DELETE
Cancel invites/requests
Tips for using request parameters
See the endpoint for a full list of parameters.
cancel request requests table
ParameterHow to use it
invite_ids

array
required
Identify the requests you want to cancel.
Tips for using response data
See the endpoint for a full list of returned fields.
cancel request response table
Field
How to use it
invite_id

string
Confirm that your invite update was sent successfully.
exception.invite_or_request_id

string
Reference this ID (different from
invite.id
) for troubleshooting a failed API request.
exception.code

integer
Reference this code for troubleshooting a failed API request.
exception.message

string
Find out why the API request failed.
exception.user_or_partner_ids

string
For troubleshooting, contact listed people who were responsible for the error.

Share your accounts

Using the API is particularly useful for automating account sharing at scale if you have a large business with many employees and partners.
If your business shares accounts less frequently or with fewer parties, consider using Business Manager user interface as an alternative.

Prerequisites

Make sure you do the following before starting to grant business access:
  • Create a free business account or convert your personal account to a business account.
  • Verify that anyone you want to invite has a business account.

Invite employees, managers, and partners

The first step sharing account access is sending invites with business roles.
POST
Create invites or requests
Tips for using request parameters
See the endpoint for a full list of parameters.
create invites request table
ParameterHow to use it
business_role

string
required
Specify
EMPLOYEE
or
BIZ_ADMIN
(manager) to invite someone from your business. See the scope of each role.
Specify
PARTNER
to invite a partner in a different business.
invite_type

string
required
Specify
MEMBER_INVITE
for someone in your business.
Specify
PARTNER_INVITE
for a partner in a different business.
members

array of strings
Specify the business IDs of members in your business whom you want to invite.
partners

array of strings
Specify the business IDs of partners in other businesses whom you want to invite. The partner agencies would have provided these IDs to you.
Tips for using response data
The endpoint returns an invite ID for a successful API request. If the request is unsuccessful, it also returns or it returns information about why the request failed.
See the endpoint for a full list of returned fields.
create invites response table
Field
How to use it
invite_id

string
Confirm that your invite update was sent successfully.
exception.invite_or_request_id

string
Reference this ID (different from
invite.id
) for troubleshooting a failed API request.
exception.code

integer
Reference this code for troubleshooting a failed API request.
exception.message

string
Find out why the API request failed.
exception.user_or_partner_ids

string
For troubleshooting, contact listed people who were responsible for the error.

See pending invites that you sent out or requests sent to you

This is helpful to keep track of which assets you can get access to as well as to delete outgoing requests that are pending if necessary.
GET
Get invites/requests
Tips for using request parameters
See the endpoint for a full list of parameters.
get invites requests table
Parameter
How to use it
is_member

boolean
For filtering, see only member invites and requests within your own business (
true
) or another businesss (
false
).
invite_status

array
See
PENDING
or
EXPIRED
invites or requests.
You can only cancel pending access requests.
Tips for using response data
For a successful request the endpoint returns important information about the ad accounts and business profiles that you have been invited to access.
See the endpoint for a full list of returned fields.
get invites response table
Field
How to use it
items.assets_summary.ad_accounts.id

string
See which ad accounts you are being invited to access or are requesting to access.
Get more details about a particular ad account by calling
GET
Get ad account
.
items.assets_summary.ad_accounts.permissions

array of strings
See which permissions you are offering to grant or are being asked to grant.
You may not have included permissions in the initial invite but may include them in an updated invite.
For invitations, the inviter may not include permissions in the initial invite but may include them in an updated invite.
items.assets_summary.profiles.id

string
See which business account profiles you are inviting people to access or for which you got access requests.
items.assets_summary.profiles.permissions

array of strings
See which permissions you are being granted or are requesting.
The inviter may send you permissions separately.
items.business_roles

array of strings
See which business roles you are offering to grant or are being asked to grant.
If the role is in your business, it may either be
EMPLOYEE
or
BIZ_ADMIN
(manager).
For a business other than yours, the role is
PARTNER
.
items.invite_data.invite_expiration

integer
For invites, keep track of when the invite expires.
items.created_by_business

object
Get metadata about this business that is sending the invite.
items.created_by_user

object
Get metadata about the person who is sending the invite.

Accept or decline an access request

PATCH
Accept or decline an invite/request
Tips for using request parameters
See the endpoint for a full list of parameters.
accept decline request requests table
ParameterHow to use it
action.accept_invite

boolean
required
Accept (
true
) or decline (
false
) the request.
action.asset_id_to_permissions

object
Indicate how requested assets map to requested permissions.
invite_id

string
required
Identify the request you are responding to from the list of pending requests you received.
Tips for using response data
For a successful request the endpoint returns important information about the ad accounts and business profiles that you have been invited to access.
See the endpoint for a full list of returned fields.
accept decline request response table
Field
How to use it
invite_id

string
Confirm that your response to the access request was sent successfully.
exception.invite_or_request_id

string
Retain this ID (different from
invite.id
) for troubleshooting a failed API request.
exception.code

integer
Reference this code for troubleshooting a failed API request.
exception.message

string
Find out why the API request failed.
exception.user_or_partner_ids

string
For troubleshooting, contact listed people who were responsible for the error.

Cancel an invite

Cancel a request that is pending. You cannot cancel a request that has been accepted or declined. Check the statuses of your access requests.
DELETE
Cancel invites/requests
Tips for using request parameters
See the endpoint for a full list of parameters.
cancel invite requests table
ParameterHow to use it
invite_ids

array
required
Identify the invites you want to cancel.
Tips for using response data
See the endpoint for a full list of returned fields.
cancel invite response table
Field
How to use it
invite_id

string
Confirm that your cancellation API request was sent successfully.
exception.invite_or_request_id

string
Reference this ID (different from
invite.id
) for troubleshooting a failed API request.
exception.code

integer
Reference this code for troubleshooting a failed API request.
exception.message

string
Find out why the API request failed.
exception.user_or_partner_ids

string
For troubleshooting, contact listed people who were responsible for the error.

Change a member's role

Change the business role of a person within your own business.
PATCH
Update member's business role
Tips for using request parameters
See the endpoint for a full list of parameters.
change role requests table
ParameterHow to use it
business_role

array
required
Change the person's role to either
EMPLOYEE
or
BIZ_ADMIN
(manager).
member_id

string
required
Identify the member whose role you want to change.
Tips for using response data
See the endpoint for a full list of returned fields.
change role response table
Field
How to use it
business_role

array
required
Confirm that the new role has been assigned to the person.
member_id

string
required
Confirm that the correct person has been assigned the new role.

Assign permissions for specific assets

After sending an initial invite, you can update it with permission assignments before the invitee responds, or wait for the invitee to accept the invite and then assign them permissions.
POST
Update invite/request with an asset permission
Tips for using request parameters
See the endpoint for a full list of parameters.
assign permissions for assets requests table
ParameterHow to use it
invite_id

string
required
Reference the unique identifier returned in the initial invite.
invite_type
string
required
Indicate whether the invite was for a member of your own business (
MEMBER_INVITE
) or an different business (
PARTNER_REQUEST
).
asset_to_id_permissions

object
required
Assign permissions to the IDs of specific assets.
Tips for using response data
The endpoint returns an access request ID for a successful API request. If the request is unsuccessful, it also returns or it returns information about why the request failed.
See the endpoint for a full list of returned fields.
assign permissions for assets response table
Field
How to use it
invite_id

string
Confirm that your invite update was sent successfully.
exception.invite_or_request_id

string
Reference this ID (different from
invite.id
) for troubleshooting a failed API request.
exception.code

integer
Reference this code for troubleshooting a failed API request.
exception.message

string
Find out why the API request failed.
exception.user_or_partner_ids

string
For troubleshooting, contact listed people who were responsible for the error.

Revoke access to an asset for a member

You also can stop sharing all assets completely with a member.
DELETE
Delete member access to asset
Tips for using request parameters
See the endpoint for a full list of parameters.
delete member access requests table
ParameterHow to use it
asset_id

string
required
Identify the asset that you want to revoke access to.
member_id

string
required
Identify the member whose access you want to revoke.
Tips for using response data
See the endpoint for a full list of returned fields.
delete member access response table
Field
How to use it
items

array
Confirm that the members you indicated in your request (
member_id
) no longer have access to the assets (
asset_id
) you indicated.

Revoke access to an asset for a partner

You also can stop sharing all assets completely with a member.
DELETE
Delete partner access to asset
Tips for using request parameters
See the endpoint for a full list of parameters.
delete partner access requests table
ParameterHow to use it
asset_id

string
required
Identify the asset that you want to revoke access to.
partner_id

string
required
Identify the partner whose access you want to revoke.
Tips for using response data
See the endpoint for a full list of returned fields.
delete partner access response table
Field
How to use it
items

array
Confirm that the members you indicated in your request (
partner_id
) no longer have access to the assets (
asset_id
) you indicated.

Manage employees and partners

Keep track of all the people you have given access, change their roles or permissions, and remove their access as needed.

See all members with access to your assets

This is helpful to keep track of which assets you can get access to as well as to delete outgoing requests that are pending if necessary.
GET
Get business members
Tips for using request parameters
See the endpoint for a full list of parameters.
get business members requests table
ParameterHow to use it
fetch_system_members

boolean
Include system members (
true
), who are not individuals, but rather collective account-holding entities that your business may use to interact with the API.
assets_summary

boolean
Include assets in the returned information (
true
), so that you see the assets that people are assigned to.
business_roles

array
Filter your returned information to only see only people within your business–those in
EMPLOYEE
or
BIZ_ADMIN
(manager) roles.
member_ids

string
Filter the request by specific member IDs, separated by commas.
To get member IDs, see all members with access to specific asset.
Tips for using response data
For a successful request the endpoint returns important information about the ad accounts and business profiles that you have been invited to access.
See the endpoint for a full list of returned fields.
get business members response table
FieldHow to use it
items.assets_summary

object
(
items
array is required)
Track the permissions of all ad accounts and business profiles that the endpoint returns.
items.business_roles

array
Track all the business roles roles assigned to
EMPLOYEE
or managers (
BIZ_ADMIN
).
items.is_shared_partner

boolean
For returned records with the business role
PARTNER
see whether you can access their assets (
true
) or whether they can access yours (
false
).
items.id

string
See the unique employee, manager, or partner ID for the returned record.
items.created_by_user

object
See information about the person in the partner business, who invited the employee .
items.created_by_partner

object
For invites, keep track of when the invite expires, so that you can respond in time.
items.created_by_business

object
See information about the business that invited you.
items.created_by_user

object
Get metadata about the person who is sending the invite or request.
items.user

object
See information about the employee who invited you.

See all members with access to a specific asset

GET
Get members with access to asset
Request parameters
See the endpoint for a full list of parameters.
Tips for using response data
See the endpoint for a full list of returned fields.
get members with asset access response table
FieldHow to use it
items.permissions

array of strings
(
items
is required)
Track the permissions of all ad accounts and business profiles that the endpoint returns.
items.user

object
(
items
is required)
See metadata about members who have access to the asset.

See all partners with access to a specific asset

GET
Get partners with access to asset
Tips for using request parameters
See the endpoint for a full list of parameters.
get partners with asset access requests table
ParameterHow to use it
asset_id

string
required
Indicate the asset for which you want to track access.
Tips for using response data
See the endpoint for a full list of returned fields.
get partners with asset access response table
FieldHow to use it
items.permissions

array of strings
(
items
is required)
Track the permissions of all ad accounts and business profiles that the endpoint returns.
items.user

object
(
items
is required)
See metadata about partners who have access to the asset.

See all of your employers

GET
List business employers for user
Tips for using request parameters
See the endpoint for a full list of parameters.
Tips for using response data
For a successful request the endpoint returns important information about the ad accounts and business profiles that you have been invited to access.
See the endpoint for a full list of returned fields.
list employers response table
FieldHow to use it
items.assets_summary

object
required
Track the permission levels of all ad accounts and business profiles that the endpoint returns.
items.business_roles

array
Track all the business roles assigned to people sharing access.
items.is_shared_partner

boolean
For returned records with the business role
PARTNER
see whether you can access their assets (
true
) or whether they can access yours (
false
).
items.created_by_user

object
See information about the person in the partner business, who invited the employee.
items.created_by_partner

object
See information about the business that invited you.
items.user

object
See information about the employee who was invited to access the assets.

See all of your partners

GET
Get business partners
Tips for using request parameters
See the endpoint for a full list of parameters.
get partners requests table
ParameterHow to use it
assets_summary

boolean
Include shared assets in the returned information (
true
), so that you see which assets partners are sharing with you or which assets you are sharing with them.
partner_type

string
If you set
assets_summary
to
true
, filter your returned information to only see assets you own and are sharing with a partner (
INTERNAL
) or assets that a partner owns and is sharing with you (
EXTERNAL
).
partner_ids

string
Filter the request by specific partner IDs, separated by commas.
Tips for using response data
See the endpoint for a full list of returned fields.
list partners response table
FieldHow to use it
items.assets_summary

object
required
Track the permission levels of all ad accounts and business profiles that the endpoint returns.
items.business_roles

array
Track all the business roles assigned to people sharing access.
items.is_shared_partner

boolean
For returned records with the business role
PARTNER
, see whether you can access their assets (
true
) or whether they can access yours (
false
).
items.created_by_user

object
See information about the person in the partner business, who invited you.
items.created_by_partner

object
See information about the business that invited you.
items.user

object
See information about the employee who was invited to access the assets.

Stop sharing access with members

Revoke access to your assets for people in your business and remove their employment relationship.
You also can revoke a member's access to specific assets.
DELETE
Terminate business memberships
Tips for using request parameters
See the endpoint for a full list of parameters.
delete membership requests table
ParameterHow to use it
member_id

string
required
Identify the members for whom you remove access. Get the IDs of members.
business_role
string
required
Identify the business roles of people for whom you want to remove access.
Tips for using response data
See the endpoint for a full list of returned fields.
delete membership response table
FieldHow to use it
deleted_members

array
Confirm that the people you wanted to remove no longer have access to your assets.

Stop sharing access with partners

Revoke access to your assets for people in other businesses.
You also can revoke a partner's access to specific assets.
DELETE
Terminate business partnerships
Tips for using request parameters
See the endpoint for a full list of parameters.
delete partnerships requests table
ParameterHow to use it
partner_ids

array of strings
required
Identify the partners for whom you remove access. Get the IDs of partners.
partner_type

string
Specify only
INTERNAL
or
EXTERNAL
partners.
Tips for using response data
See the endpoint for a full list of returned fields.
delete partnerships response table
FieldHow to use it
deleted_partners

array
Confirm that the people you wanted to remove no longer have access to your assets.

Manage assets and asset groups

Keeping track of your assets and grouping them for different purposes are helpful for sharing them.

See all the assets you have access to

See all the assets your business owns and has access to, including any asset groups they belong to. This useful for actions such as:
  • Managing members and their access
  • Sharing access
  • Setting permissions
  • Creating asset groups
  • Deciding whether to delete an asset group.
GET
List business assets
Tips for using request parameters
See the endpoint for a full list of parameters.
list assets requests table
ParameterHow to use it
permissions

array of strings
Filter assets according to the permissions of those who have access to them.
child_asset_id

string
Filter assets with this unique identifier that associates it with a particular asset groups that include it.
asset_group_id

string
Filter assets according to which asset groups they are included in.
asset_type

string
Filter assets according type.
Specify
AD_ACCOUNT
to get see asset IDs for ad accounts that are being shared with you so that you can pass those IDs when requesting shared assets.
Tips for using response data
See the endpoint for a full list of returned fields.
list assets response table
FieldHow to use it
items

array of objects
required
See information for each returned asset, including unique identifier, asset type, permissions that your business has and any asset groups that include the asset.
If you specified
AD_ACCOUNT
as the
asset_type
in the request, use the returned
item.asset_id
value to pass as the
ad_account_id
parameter when requesting shared assets.
For any returned assets with the type
CATALOG
, the endpoint returns the
catalog_info
fields, includes information about that catalog.

Create an asset group

You can group assets according to various criteria for efficient management across geography, brand, and vertical. When you initially create an asset group, it contains no assets. Afterward, you can assign assets to it.
POST
Create a new asset group.
Tips for using request parameters
See the endpoint for a full list of parameters.
create asset group request table
ParameterHow to use it
asset_group_name

string
required
Name your new asset group.
asset_group_description

string
required
Describe your new asset group to help others in your organization understand its intended use.
asset_group_types
array
required
Specify a category for grouping your assets. These categories are for your own reference and have no functional impact on the request.
Tips for using response data
See the endpoint for a full list of returned fields.
create asset group response table
FieldHow to use it
items

array of objects
required
See information for each returned asset, including unique identifier, asset type, permissions that your business has and any asset groups that include the asset.
For any returned assets with the type
CATALOG
, the endpoint returns the
catalog_info
fields, includes information about that catalog.

Add assets to an asset group or remove assets from it

PATCH
Update asset groups.
Tips for using request parameters
See the endpoint for a full list of parameters.
add remove assets to group request table
ParameterHow to use it
asset_groups_to_update.asset_group_id

string
required
Specify the asset group you want to update.
asset_groups_to_update.asset_group_name

string
Change your asset group name if you want to.
asset_groups_to_update.asset_group_description

string
Change your asset group description if you want to.
asset_groups_to_update.asset_group_types

array of strings
Change the category for grouping your assets for grouping your assets if you want.
Making this change does not affect the functionality of the asset group.
asset_groups_to_update.assets_to_add

array of strings
Using asset IDs, which you see by getting assets, list any assets you want to add to the group.
asset_groups_to_update.assets_to_remove

array of strings
Using asset IDs, which you see by getting assets, list any assets you want to remove from the group.
Tips for using response data
See the endpoint for a full list of returned fields.
add remove assets to group response table
FieldHow to use it
updated_asset_groups

array of objects
Reference the asset group's returned id string when you need to grant access and permissions to the group through an invite.
Reference the returned asset metadata, such as
ad_accounts_ids
profiles_ids
and
catalogs_ids
to keep track of what assets are included in the group when you share it.
exceptions

array of objects
Troubleshoot any errors that occurred in the request, referencing affected assets by
asset_group_id
.

Delete an asset group

Deleting an asset group affects anyone who has access to its contained assets.
  • See the assets within an asset group.
  • See assets assigned to a member.
  • See assets shared with, or shared by a partner.
DELETE
Delete asset groups.
Tips for using request parameters
See the endpoint for a full list of parameters.
Delete asset group request table
ParameterHow to use it
asset_groups_to_delete

array for string
required
Specify asset groups you want to delete.
Tips for using response data
See the endpoint for a full list of returned fields.
delete asset group response table
FieldHow to use it
deleted_asset_groups

array of objects
Verify that your specified asset groups have been deleted.
exceptions

array of objects
If any deletions fail, see why (
exceptions.message
) and which asset groups are affected (
exceptions.asset_group_id
).

See assets shared with, or shared by a member

This endpoint is especially useful as you prepare to change access for members or remove assets from asset groups.
Tips for using request parameters
See the endpoint for a full list of parameters.
Get assets assigned to member request table
ParameterHow to use it
member_id

string
required
Indicate the member you want to know about.
partner_type

string
Ignore this parameter if you are fetching assets for a member.
asset_type

string
Filter assets according to specific types:
AD_ACCOUNT
PROFILE
ASSET_GROUP
CATALOG
Tips for using response data
See the endpoint for a full list of returned fields.
Get assets assigned to member response table
FieldHow to use it
items

array of objects
See all your assets and asset groups—and associated permissions—that you are sharing with the member or they are sharing with you.

See assets shared with, or shared by a partner

This endpoint is especially useful as you prepare to change access for partners or remove assets from asset groups.
GET
Get assets assigned to a member
Tips for using request parameters
See the endpoint for a full list of parameters.
Get assets assigned to partner request table
ParameterHow to use it
partner_id

string
required
Indicate the partner you want to know about.
partner_type

string
Indicate whether the partner is sharing assets with you (
EXTERNAL
) or you hare sharing assets with them (
INTERNAL
).
asset_type

string
Filter assets according to specific types:
AD_ACCOUNT
PROFILE
ASSET_GROUP
CATALOG
Tips for using response data
See the endpoint for a full list of returned fields.
Get assets assigned to partner response table
FieldHow to use it
items

array of objects
See all your assets and asset groups—and associated permissions—that you are sharing with the partner or they are sharing with you.

Request shared assets in the API

After you accept an invite and are assigned permissions, you can start working with the assets that the inviter shared with you. The structure of the API calls is the same as with assets that you own, except that you need to specify the shared ad account ID (
ad_account_id
).
To get the
ad_account_id
:
  1. Call
    GET
    List business assets
    to see your assets, specifying
    AD_ACCOUNT
    as the
    asset_type
    .
  2. From the response, use the returned
    item.asset_id
    value to pass as the
    ad_account_id
    when requesting a shared asset.
The following example shows a request for a Pin
GET
Get Pin
with the shared ad account in the query string:
curl --location --request GET 'https://api.pinterest.com/v5/pins/<insert_pin_id>?ad_account_id=<insert_ad_account_id>'
--header 'Authorization: Bearer <Add your token here>'
--header 'Content-Type: application/json'
If you have the appropriate role and permission to get the Pin, and if you specify the shared ad account ID in the request, the endpoint returns the Pin. Otherwise, the endpoint returns an error message such as the following:
Example response to unauthorized request:
{ "code": 403, "message": "Not authorized to access board or Pin." }

Learn more

Use the following Help Center guides to help you set up business access in the Business Manager:
  • Get a business account
  • Create an advertiser account
  • Business Manager overview
  • Share and manage access to your ad accounts
Was this page helpful?