Business Management APIs

Sharing Meta Pixel Between Businesses

There may be multiple use cases for businesses to access a pixel dataset of one business in another business (typically an agency), such as to manage ads, analyze performance or upload events.

Following are the API integrations needed to establish a relationship between the pixel and agency business. If the recipient (agency) business also manages ads for the client and needs to use that pixel for ad accounts, see step 3.

Prerequisites: App Requirements

Apps should have the Ads Management Standard Access (advanced access) feature. Apps should also have the following permissions:

  • business_management
  • ads_management or ads_read and manage_pages

Step 1: Initiate Pixel Sharing with Agency Business

This requires a user access token with the above app permissions from a business admin that owns the pixel.

POST <ads_pixel>/agencies?business=<agency_business_id>&permitted_tasks=[<permitted_tasks_for_agency_business>]

Options and parameters for this request include:

Name Description

business

type: numeric

Required.

The agency business ID receiving access to the pixel

permitted_tasks

type: list:string

Required.

Example: ['ANALYZE', 'UPLOAD', 'ADVERTISE']

Permitted tasks for agency on the pixel

Possible Values: ANALYZE, UPLOAD, ADVERTISE, EDIT

ANALYZE: View, analyze and advertise.

UPLOAD: Upload website conversion data to this dataset.

ADVERTISE: Connect ad accounts to this Facebook dataset. Use this dataset for advertising.

EDIT: Manage dataset, edit settings, analyze and advertise. (EDIT access is currently restricted, contact your Meta representative to allowlist your app)

We handle a request based on the relationship status with the other business:

  • Businesses that have an existing approved relationship. We share the pixel directly with them.
  • Businesses that have an existing in-progress relationship. We add the pixel to the request so that when the recipient business approves this request, we then share the pixel.
  • Businesses that do not have any relationship. We create a sharing agreement with the pixel attached to it so that when the recipient business approves this request, the pixel will be shared with the business.

If the pixel is successfully shared with the business, the following response is returned:

{  
    success: true,
}

If the request is pending sharing agreement acceptance, the API request returns the following response with pending_request_id. When the recipient business accepts the request, the pixel will be automatically shared with the recipient business. See step 2 to accept/decline the request.


{
  "success": true,
  "pending_request_id": "{request_id}"
}

Note that there is a limit on how many businesses a pixel can be shared with.

Step 2: Accept Pending Request (if required)

After initiating the pixel sharing request, the agency business may receive a pending shared agreement request, if the agency does not already have a relationship with the business owning the pixel. Recipient business admins can see and accept this request on their Business Manager.

To approve or decline the relationship request using the API, get the request_id from the error response in Step 1.

The API requires a user access token from the recipient business admin with business_mangement or ads_management permission for the app.

POST <request_id>?request_status="approve"

On success, the API returns this response:

{  
    success: bool
}

Options and parameters for this request include:

Name Description

request_status

type: string

Required.

Whether the business receiving a pixel-sharing request approves or rejects the request.


Possible Values: APPROVE, DECLINE

Step 3: Share the Pixel with Agency Business Ad Accounts

If an agency is managing ads for a client and needs to permit the client's dedicated ad accounts to use the pixel dataset, use this API.

Once the pixel is shared into a business with advertise/analyze permissions, the business can permit ad accounts within the business to use the pixel dataset for advertising.

The API requires a user access token with business_management, ads_management or ads_read permissions from the business admin.

Post <ads_pixel>/shared_accounts?business=<business_id>&ad_account=<ad_account_id>
Name Description

business_id

type: numeric

Required.

Business that manages ads and has access to pixel and ad accounts. The user whose access token was used should have admin permissions on this business.

ad_account_id

type: numeric

Required.

Ad account to be permitted on pixel.

Step 4: Delete Pixel-Sharing Connection

If the connection between pixel and agency business is no longer needed, use the following API to delete the connection.

Delete <adspixel>/agencies?business=<agency_business_id>

The API requires an admin user access token from the pixel-owning business.

On success, the API returns this response:

{  
    success: true
}

Learn More