Conversions API Gateway for Multiple Accounts Control Plane API

Partner Integration

Overview

Conversions API Gateway for multiple accounts control plane API is a set of GraphQL APIs exposed from the Gateway instance. It allows developers to programmatically manage accounts, data sources and other configurations of a Gateway instance. Partners can integrate the API to build into their advertiser-facing UI and offer their advertisers a seamless onboarding and management flow.

Potential use cases:

Advertisers onboard to Gateway using the partner’s UI and perform follow-up actions through the Gateway admin settings. This requires partial integration of the control plane API.
Advertisers perform all actions on the partner's UI, including onboarding to Gateway and follow-up actions. It can be a good use case for partners who do not want to expose the Gateway UI but still want to provide Gateway as a service for the advertisers. This requires full integration of the control plane API.

Refer to the section below for more details on integration steps.

Conversions API Gateway for multiple accounts control plane API or Gateway are interchangeably used in this document.

Integration Guide

Depending on the use case, there can be two integration paths (as shown in the diagram below):

Partial integration of control plane API. This does not require authentication from advertisers.
Full integration with control plane API. This requires authentication from advertisers either using Meta Business Extension (MBE) or manual generation of tokens.

Prerequisites

For both integration paths, the partner needs to first complete the steps below:

Step 1: Onboard as a host of Gateway instance

Step 2: Generate API account name and API secret key

Go to:

https://<Conversions API Gateway Endpoint>/hub/

Navigate to the Host settings Tab, select the Manage API accounts Page, and click the Add API account button.

Re-enter your password. Click Continue.

Enter the name of the API account. Click Continue.

The account name can only consist of letters and numbers, and cannot contain spaces. The maximum length is 20.

Copy and save the generated secret key. You will not be able to view it again.

To remove an API account, click Delete API account. Kindly note that the action is not reversible and can potentially cause disruptions to any advertiser’s applications or services using the API.

Partial Integration

A use case based on partial integration:

The advertiser opts in for Gateway service using the partner’s UI.
Partner generates an invitation link which can be used by the advertiser to set up a password and complete Gateway account creation.
The advertiser uses functionalities on Gateway UI to perform actions such as data source management as well as account user, domain and routing management.
Partner retrieves the advertiser’s account usage and bills accordingly.

A high-level user flow may look like below:

To achieve the above, the partner can integrate a subset of control plane API, including:

Get API Access Token
Create Account for advertisers
Get Account Usage, for example, for billing purposes

Full Integration

A use case based on full integration:

The advertiser opts in for Gateway service using the partner’s UI.
Partner onboards the advertiser’s Gateway account and receives permission to manage the account; the advertiser authorizes the partner using the Meta Business Extension (MBE) or manual token generation.
The advertiser can perform data source management as well as account user, domain and routing management in the partner’s UI.
Partner retrieves the advertiser’s account usage and bills accordingly.

A high-level user flow may look like below:

For this integration path, partners need to request authorization and get system user access tokens via authentication in order to send events on behalf of the advertisers.

Authentication

Partners have the following two authentication options for Meta Pixels not managed by them:

Option 1 - Meta Business Extension (MBE)

Before you start, you need to:

Complete all the requirements for implementing MBE

MBE provides an endpoint to retrieve system user access tokens created in the advertiser’s Business Manager. Partners may follow up to Step 4 of the MBE integration guide. Ensure that you:

Set the value of channel parameter in setup configuration object as CONVERSIONS_API_GATEWAY_ADVERTISER.
Are able to receive the webhook response at the completion of onboarding.
Use the access token returned via MBE and convert it into a System User Access Token by making an additional API call.
Save a copy of external_business_id, pixel_id, business_id and system user access token in your system.

Option 2 - Client System User Access Token

With this option, partners may have the advertisers:

Manually create a system user access token via the Conversions API inside Settings in Events Manager (EM)
Share pixel_id, business_id and system user access token with the partner and save a copy of it.

Integration

Partners can integrate the complete set of control plane API. Further details are covered in the API Reference.

API and UI Parity

We are enforcing API and UI parity by exposing the same API endpoints used in the Gateway UI. However, any API endpoint not covered in the API Reference is subject to change in future development. In order to limit the unexpected impact to the minimum, those uncovered API endpoints return Error code: 418. You can still use the API but at your own risk.