Pinterest Members API
The Members API from Pinterest — 4 operation(s) for members.
OpenAPI Specification
openapi: 3.0.3
info:
version: 5.13.0
title: Pinterest Members API
description: This is the description of your API.
contact:
name: Pinterest, Inc.
url: https://developers.pinterest.com/
license:
name: MIT
url: https://spdx.org/licenses/MIT
termsOfService: https://developers.pinterest.com/terms/
servers:
- url: https://api.pinterest.com/v5
tags:
- name: Members
paths:
/businesses/{business_id}/assets/{asset_id}/members:
get:
summary: Get members with access to asset
description: Get all the members the requesting business has granted access to on the given asset.
operationId: business_asset_members/get
security:
- pinterest_oauth2:
- biz_access:read
x-ratelimit-category: ads_read
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_business_user'
- $ref: '#/components/parameters/path_asset_id'
- $ref: '#/components/parameters/query_bookmark'
- $ref: '#/components/parameters/query_page_size'
- $ref: '#/components/parameters/query_business_access_start_index'
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
items:
type: array
description: List of members with permissions to the asset.
items:
$ref: '#/components/schemas/UserSingleAssetBinding'
description: Sucess
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Members
/businesses/{business_id}/members:
get:
summary: Get business members
description: 'Get all members of the specified business.
The return response will include the member''s business_role and assets they have access to if assets_summary=TRUE'
operationId: get/business_members
security:
- pinterest_oauth2:
- biz_access:read
x-ratelimit-category: ads_read
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_business_user'
- $ref: '#/components/parameters/query_assets_summary'
- name: business_roles
in: query
description: A list of business roles to filter the members by. Only members whose roles are in the specified roles will be returned.
required: false
schema:
type: array
items:
$ref: '#/components/schemas/MemberBusinessRole'
- name: member_ids
in: query
description: A list of business members ids separated by comma.
example: 00101010101,2222220101
required: false
schema:
type: string
maxLength: 500
- $ref: '#/components/parameters/query_business_access_start_index'
- $ref: '#/components/parameters/query_bookmark'
- $ref: '#/components/parameters/query_page_size'
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
items:
type: array
description: List of business members.
items:
$ref: '#/components/schemas/UserBusinessRoleBinding'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Members
patch:
description: Update a member's business role within the business.
summary: Update member's business role
operationId: update/business_memberships
security:
- pinterest_oauth2:
- biz_access:write
x-ratelimit-category: ads_write
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_business_id'
requestBody:
content:
application/json:
schema:
type: array
minItems: 1
items:
$ref: '#/components/schemas/UpdateMemberBusinessRoleBody'
description: List of objects with the member id and the business_role.
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateMemberResultsResponseArray'
description: response
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Members
delete:
description: Terminate memberships between the specified members and your business.
summary: Terminate business memberships
operationId: delete_business_membership
security:
- pinterest_oauth2:
- biz_access:read
- biz_access:write
x-ratelimit-category: ads_write
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_business_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MembersToDeleteBody'
description: List of members with role to delete.
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DeletedMembersResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Members
/businesses/{business_id}/members/{member_id}/assets:
get:
summary: Get assets assigned to a member
description: 'Get assets on which you assigned asset permissions to the given member. Can be used to:
- get all assets, regardless of asset type or
- get assets of one asset type by using the asset_type query.
The return response will include the permissions the member has to that asset and the asset type.'
operationId: business_member_assets/get
security:
- pinterest_oauth2:
- biz_access:read
x-ratelimit-category: ads_read
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_business_user'
- $ref: '#/components/parameters/path_business_member_user'
- $ref: '#/components/parameters/query_resource_type'
- $ref: '#/components/parameters/query_business_access_start_index'
- $ref: '#/components/parameters/query_bookmark'
- $ref: '#/components/parameters/query_page_size'
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
items:
type: array
description: List asset permissions the given member was granted.
items:
$ref: '#/components/schemas/AssetIdPermissions'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Members
/businesses/{business_id}/members/assets/access:
patch:
description: 'Grant multiple members access to assets and/or update multiple member''s exisiting permissions to an asset.
Note: Not all listed permissions are applicable to each asset type. For example, PROFILE_PUBLISHER would not be applicable to an asset of type AD_ACCOUNT. The permission level PROFILE_PUBLISHER is only available to an asset of the type PROFILE.
'
summary: Assign/Update member asset permissions
operationId: business_members_asset_access/update
security:
- pinterest_oauth2:
- biz_access:write
x-ratelimit-category: ads_write
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_business_user'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateMemberAssetAccessBody'
description: List of member asset permissions to create or update.
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateMemberAssetsResultsResponseArray'
description: response
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Members
delete:
description: Terminate multiple members' access to an asset.
summary: Delete member access to asset
operationId: business_members_asset_access/delete
security:
- pinterest_oauth2:
- biz_access:write
x-ratelimit-category: ads_write
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_business_user'
requestBody:
content:
application/json:
schema:
type: object
required:
- accesses
properties:
accesses:
type: array
minItems: 1
maxItems: 100
description: List of members asset access to be deleted
items:
type: object
required:
- asset_id
- member_id
properties:
asset_id:
type: string
description: Id of the asset on which to remove member permissions.
example: '549755885175'
maxLength: 25
pattern: ^\d+$
member_id:
type: string
description: Unique identifier of the member on which to perform the asset permission removal
example: '140943737684417'
maxLength: 25
pattern: ^\d+$
description: List member assset permissions to delete.
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteMemberAccessResultsResponseArray'
description: response
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Members
components:
schemas:
BusinessMemberAssetsSummary:
type: object
description: Ad accounts and profiles the business member/partner has access to.
nullable: true
properties:
ad_accounts:
type: array
description: List of ad account IDs and respective permission levels.
items:
type: object
properties:
id:
type: string
description: Unique identifier of a business ad account.
example: '549755885175'
pattern: ^\d+$
minLength: 1
maxLength: 20
permissions:
$ref: '#/components/schemas/PermissionsResponse'
profiles:
type: array
description: List of profile IDs and respective permission levels.
items:
type: object
properties:
id:
type: string
description: Unique identifier of a business profile.
example: '383791336903426391'
pattern: ^\d+$
minLength: 1
maxLength: 20
permissions:
$ref: '#/components/schemas/PermissionsResponse'
DeleteMemberAccessResult:
type: object
description: The terminated asset access.
properties:
asset_id:
type: string
description: Unique identifier of the business asset.
example: '549755885175'
pattern: ^\d+$
member_id:
type: string
description: Unique identifier of the business member.
example: '140943737684417'
pattern: ^\d+$
MembersToDeleteBody:
required:
- members
properties:
members:
items:
required:
- member_id
- business_role
properties:
member_id:
type: string
description: Unique identifier of the member
maxLength: 25
example: '140943737684417'
pattern: ^\d+$
business_role:
$ref: '#/components/schemas/BusinessRoleForMembers'
type: object
type: array
minItems: 1
maxItems: 50
type: object
MemberBusinessRole:
type: string
description: 'The access level a member/partner has to the business. Values are case-sensitive.
<br> - EMPLOYEE: Can only view and access ad accounts you assign to them.
They cannot see details about other employees, external partners or other ad accounts.
<br> - BIZ_ADMIN: Have full control of roles and can add employees, external partners as well as grant ad account access.'
example: BIZ_ADMIN
enum:
- EMPLOYEE
- BIZ_ADMIN
BusinessRoleForMembers:
type: string
description: 'The access level a member has to the business. Values are case-sensitive.
<br> - EMPLOYEE: Can only view and access assets you assign to them.
They cannot see details about other employees, partners, or other assets.
<br> - BIZ_ADMIN: Have full control of roles and can add employees and partners as well as grant asset access.'
example: BIZ_ADMIN
enum:
- EMPLOYEE
- BIZ_ADMIN
UsersForIndividualAssetResponse:
type: object
description: An object containing the permissions a business member has on the asset.
properties:
asset_id:
description: Unique identifier of a business asset.
example: '549755885175'
type: string
pattern: ^\d+$
member_id:
description: Unique identifier of the business member with asset access.
example: '140943737684417'
type: string
pattern: ^\d+$
permissions:
$ref: '#/components/schemas/PermissionsResponse'
Error:
title: Error
type: object
properties:
code:
type: integer
message:
type: string
required:
- code
- message
UpdateMemberAssetAccessBody:
type: object
description: An object with a list of all the new accesses.
required:
- accesses
properties:
accesses:
type: array
minItems: 1
maxItems: 50
items:
type: object
required:
- asset_id
- member_id
- permissions
properties:
asset_id:
type: string
description: Id of the asset to update.
example: '549755885175'
maxLength: 25
pattern: ^\d+$
member_id:
type: string
description: Unique identifier of the member on which to perform the update
example: '140943737684417'
maxLength: 25
pattern: ^\d+$
permissions:
type: array
description: A non-empty array of permissions to assign to the member.
example:
- ANALYST
- ADMIN
minItems: 1
maxItems: 50
items:
$ref: '#/components/schemas/Permissions'
UserBusinessRoleBinding:
type: object
properties:
assets_summary:
type: object
nullable: true
allOf:
- $ref: '#/components/schemas/BusinessMemberAssetsSummary'
business_roles:
description: The access level a user has on the business. This can be EMPLOYEE, BIZ_ADMIN, or PARTNER.
type: array
example:
- BIZ_ADMIN
items:
$ref: '#/components/schemas/BusinessRoleResponse'
created_by_business:
type: object
nullable: true
description: Metadata for the business that created the business relationship.
allOf:
- $ref: '#/components/schemas/BusinessAccessUserSummary'
created_by_user:
type: object
nullable: true
description: Metadata for the user that created the business relationship.
allOf:
- $ref: '#/components/schemas/BusinessAccessUserSummary'
created_time:
type: integer
nullable: true
description: The time the business relationship was created. Returned in milliseconds.
example: 1646767577816
id:
type: string
description: Unique identifier of the business member/business partner/employer.
example: '383791336903426391'
pattern: ^\d+$
is_shared_partner:
type: boolean
description: 'This field is only relevant when business_role="PARTNER".
<br>If is_shared_partner=FALSE, the partner can access your business assets. If assets_summary
is not empty, the assets listed are your business assets the partner has access to.
<br>If is_shared_partner=TRUE, you can access the partner''s business asset. If assets_summary
is not empty, the assets listed are the partner''s business assets you have access to.'
example: false
user:
type: object
nullable: true
description: Metadata for the business member/business partner/employer.
allOf:
- $ref: '#/components/schemas/BusinessAccessUserSummary'
BusinessAccessUserSummary:
type: object
description: Metadata of the member/partner that has access to the asset.
properties:
email:
description: Email of the business member/partner.
example: business0101@business.com
type: string
nullable: true
id:
description: Unique identifier of the business member/partner.
example: '383791336903426391'
type: string
nullable: true
minLength: 1
maxLength: 20
username:
description: Username of the business member/partner.
example: business0101
nullable: true
type: string
UpdateMemberResult:
type: object
properties:
business_role:
type: string
description: 'The access level a member has to the business. Values are case-sensitive.
<br> - EMPLOYEE: Can only view and access assets you assign to them.
They cannot see details about other employees, partners, or other assets.
<br> - BIZ_ADMIN: Have full control of roles and can add employees and partners as well as grant asset access.'
example: EMPLOYEE
member_id:
type: string
description: Unique identifier of the business member.
example: '140943737684417'
pattern: ^\d+$
DeletedMembersResponse:
type: object
description: An object with a list of members that were deleted.
properties:
deleted_members:
type: array
description: List of members whose business membership have been terminated.
example:
- '809944451643622187'
- '383791336903426391'
items:
type: string
pattern: ^\d+$
example: '809944451643622187'
UpdateMemberBusinessRoleBody:
description: Single instance of a business member to have its role updated
properties:
business_role:
$ref: '#/components/schemas/BusinessRoleForMembers'
member_id:
type: string
description: Unique identifier of the member
maxLength: 25
example: '140943737684417'
pattern: ^\d+$
required:
- member_id
- business_role
type: object
UpdateMemberAssetsResultsResponseArray:
type: object
properties:
items:
type: array
description: 'List of assigned/updated member asset access.
If there is an error, an exception object will be returned. If the action was successfully completed, a response object will be returned.'
items:
type: object
properties:
response:
$ref: '#/components/schemas/UsersForIndividualAssetResponse'
Paginated:
type: object
properties:
items:
type: array
items:
type: object
bookmark:
type: string
nullable: true
required:
- items
UpdateMemberResultsResponseArray:
type: object
properties:
items:
type: array
description: List of members with updated business access role.
items:
$ref: '#/components/schemas/UpdateMemberResult'
UserSingleAssetBinding:
type: object
description: An object containing the permissions a business member/partner has on the asset.
properties:
permissions:
$ref: '#/components/schemas/PermissionsResponse'
user:
$ref: '#/components/schemas/BusinessAccessUserSummary'
BusinessRoleResponse:
type: string
description: 'The access level a member/partner has to the business. Values are case-sensitive.
<br> - EMPLOYEE: Can only view and access assets you assign to them.
They cannot see details about other employees, partners, or other assets.
<br> - BIZ_ADMIN: Have full control of roles and can add employees or external partners as well as grant asset access.
<br> - PARTNER: Can only view and access assets you assign them to/or they assign to you.'
example: BIZ_ADMIN
PermissionsResponse:
type: array
description: Permission levels member or partner has on an asset.
example:
- FINANCE_MANAGER
- CATALOGS_MANAGER
- AUDIENCE_MANAGER
items:
type: string
AssetIdPermissions:
type: object
description: An object containing the permissions a business member has on the asset.
properties:
asset_id:
description: Unique identifier of a business asset.
example: '549755885175'
pattern: ^\d+$
type: string
maxLength: 20
minLength: 1
asset_type:
$ref: '#/components/schemas/AssetTypeResponse'
permissions:
$ref: '#/components/schemas/PermissionsResponse'
DeleteMemberAccessResultsResponseArray:
type: object
properties:
items:
type: array
description: List of member asset permissions that were deleted.
items:
$ref: '#/components/schemas/DeleteMemberAccessResult'
Permissions:
type: string
enum:
- ADMIN
- ANALYST
- FINANCE_MANAGER
- AUDIENCE_MANAGER
- CAMPAIGN_MANAGER
- CATALOGS_MANAGER
- PROFILE_PUBLISHER
AssetTypeResponse:
description: Type of asset. Currently we only support AD_ACCOUNT and PROFILE.
example: AD_ACCOUNT
type: string
parameters:
query_resource_type:
name: asset_type
in: query
required: false
description: A resource type to filter the assets by. Only assets of the specified type will be returned.
schema:
type: string
enum:
- AD_ACCOUNT
- PROFILE
default: AD_ACCOUNT
example: AD_ACCOUNT
query_assets_summary:
name: assets_summary
description: 'Include assets summary in the response if this is true.
The assets summary returns a dictionary representing a summary of the assets
for the business user ID, with information like the ad accounts and profiles
the user has permissions for and what those permissions are'
in: query
required: false
schema:
type: boolean
default: false
query_page_size:
name: page_size
description: Maximum number of items to include in a single page of the response. See documentation on <a href='/docs/getting-started/pagination/'>Pagination</a> for more information.
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 250
default: 25
query_bookmark:
name: bookmark
description: Cursor used to fetch the next page of items
in: query
required: false
schema:
type: string
path_business_user:
name: business_id
in: path
description: Unique identifier of the requesting business.
example: '729090764583391194'
required: true
schema:
type: string
pattern: ^\d+$
minLength: 1
maxLength: 20
path_business_id:
name: business_id
in: path
description: Business id
example: '729090764583391194'
required: true
schema:
type: string
pattern: ^\d+$
minLength: 1
maxLength: 20
path_asset_id:
name: asset_id
in: path
description: Unique identifier of a business asset.
example: '729090764583391194'
required: true
schema:
type: string
pattern: ^\d+$
minLength: 1
maxLength: 20
query_business_access_start_index:
name: start_index
in: query
description: An index to start fetching the results from. Only the results starting from this index will be returned.
example: 0
required: false
schema:
type: integer
minimum: 0
default: 0
path_business_member_user:
name: member_id
in: path
description: The member id to fetch assets for.
example: '729090764583391194'
required: true
schema:
type: string
pattern: ^\d+$
minLength: 1
maxLength: 20
securitySchemes:
pinterest_oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://www.pinterest.com/oauth/
tokenUrl: https://api.pinterest.com/v5/oauth/token
scopes:
ads:read: See all of your advertising data, including ads, ad groups, campaigns etc.
ads:write: Create, update, or delete ads, ad groups, campaigns etc.
billing:read: See all of your billing data, billing profile, etc.
billing:write: Create, update, or delete billing data, billing profiles, etc.
biz_access:read: See business access data
biz_access:write: Create, update, or delete business access data
boards:read: See your public boards, including group boards you join
boards:read_secret: See your secret boards
boards:write: Create, update, or delete your public boards
boards:write_secret: Create, update, or delete your secret boards
catalogs:read: See all of your catalogs data
catalogs:write: Create, update, or delete your catalogs data
pins:read: See your public Pins
pins:read_secret: See your secret Pins
pins:write: Create, update, or delete your public Pins
pins:write_secret: Create, update, or delete your secret Pins
user_accounts:read: See your user accounts and followers
user_accounts:write: Update your user accounts and followers
conversion_token:
type: http
scheme: bearer
description: This security scheme only applies to the conversion events endpoint (POST /ad_accounts/{ad_account_id}/events). This endpoint requires a bearer token generated via Ads Manager (ads.pinterest.com).
basic:
type: http
scheme: basic
x-tagGroups:
- name: Pin and Boards
tags:
- pins
- boards
- media
- aggregated_comments
- aggregated_pin_data
- user_account
- name: Campaign Management
tags:
- ad_accounts
- campaigns
- ad_groups
- ads
- product_group_promotions
- bulk
- name: Targeting
tags:
- audiences
- customer_lists
- keywords
- targeting_template
- audience_insights
- audience_sharing
- name: Ad Formats
tags:
- lead_forms
- lead_ads
- leads_export
- name: Billing
tags:
- billing
- order_lines
- terms_of_service
- name: Business Access
tags:
- business_access_assets
- business_access_invite
- business_access_relationships
- name: Conversions
tags:
- conversion_events
- conversion_tags
- name: Others
tags:
- integrations
- oauth
- resources
- search
- terms
- name: Shopping
tags:
- catalogs
- name: Deprecated
tags:
- product_groups