Multi-Flow Support Using x-brand-id

This feature is available for two different flows within the platform. The behavior and logic remain the same across both — the only distinction lies in specifying which brand the action should be applied to.

To handle this, simply include the x-brand-id header in each request. This value identifies the target brand, allowing the platform to execute the operation in the correct context.

1. API Authentication

All API requests must include the x-api-key header, which corresponds to the brand configured during onboarding.

📘

If your integration involves multiple users, each user will have their own brand associated with your partner account. In this case, you must also include the x-brand-id header in every request to specify which user's brand is being accessed.

For all advertising-related flows, it is essential to identify the brand being used, whether it is the default brand or one explicitly specified via the header. The brand must be connected to a Facebook account with permissions for the ad account and the pages used in the campaigns.

2. FB Connections

In this path, you will be using your own ad account + FB/IG page to run ads. There are two methods to this approach involves generating a System User Access Token for a system user within your Facebook Business Manager. It provides access to the required Facebook assets.

2.1.1 If you are using your own ad accounts + pages to run ads:

Using a System User Access Token:

If you choose to use a System User Access Token, you must first:

1. Login to the SymphonyOS app, by going to:
   1. https://beta.symphonyos.co
   2. Log into an account
   3. Connect the Ad Account owner’s Facebook by clicking Settings > Login with Facebook under Account Settings

From there, please coordinate with the Symphony team to setup a time, to create a System User Access Token directly within your FB Business Manager.

Once you have obtained the token, you need to call the following endpoint. In the payload, include the access_token you generated and set the system_token flag to true to indicate that the token is a system-level token.

📘

To make the association of the ad account and page, you need to send the x-brand-id to which the accounts will be assigned independently of the main brand or the additional brands (sending the x-brand-id field as empty for this endpoint is exclusive for the hybrid connection).

curl -X 'POST' \
  '{{ADVERTISING_API}}/v1/meta/connect/brand' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {{YOUR_API_KEY}}' \
  -H 'x-brand-id: {{YOUR_USER_BRAND_ID}}'
  -d '{
  "access_token": "{{YOUR_ACCESS_TOKEN}}"
}'

2.2 Connecting Ad Accounts and Pages

Once your partner account is connected to Facebook, you need to select the ad account and page that will be used for all advertising processes through the API.

📘

The x-brand-id must be sent with the value of the main brand or the extra brands. Sending the empty field indicates that the actions to be run will be with the main brand. It is not possible to send a random value.

To do this, query the following endpoints:

2.2.1 Retrieve Ad Accounts

curl -X 'GET' \
  '{{ADVERTISING_API}}/v1/meta/ad_accounts' \
  -H 'accept: application/json' \
  -H 'x-api-key: {{YOUR_API_KEY}}' \
  -H 'x-brand-id: {{YOUR_OPTIONAL_USER_BRAND_ID}}'

2.2.2 Retrieve Pages

curl -X 'GET' \
  '{{ADVERTISING_API}}/v1/meta/pages' \
  -H 'accept: application/json' \
  -H 'x-api-key: {{YOUR_API_KEY}}' \
  -H 'x-brand-id: {{YOUR_OPTIONAL_USER_BRAND_ID}}'

These endpoints, documented in the Meta Connect section of the Swagger documentation, return lists of ad accounts and pages associated with the connected Facebook account. Select the desired ad account and page, and retrieve their IDs.

2.2.3 Associating ad account and page

📘

To make the association of the ad account and page, in the next endpoint you need to send the x-brand-id to which the accounts will be assigned independently of the main brand or the additional brands (sending the x-brand-id field as empty for this endpoint is exclusive for the hybrid connection).

To associate a brand with an ad account and page, use the following endpoint:

curl -X 'POST' \
  '{{ADVERTISING_API}}/v1/meta/connect/brand' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {{YOUR_API_KEY}}' \
  -H 'x-brand-id: {{YOUR_USER_BRAND_ID}}'
  -d '{
  "facebook_page": "{{FACEBOOK_PAGE_ID}}",
  "facebook_ad_account": "{{FACEBOOK_AD_ACCOUNT_ID}}"
}'

3. Flows

A simple workflow for using the API includes the following steps:

1. List Existing Campaigns: Retrieve a list of campaigns that have been created. 3.1 Retrieving the List of Campaigns

2. View Campaign Details:3.2 Get Campaign Details

   For each campaign, you can access its details, including:

   • General campaign information.
   • Analytics generated during its execution.

3. Create and Configure New Campaigns: Use the API to create and set up new campaigns tailored to your requirements. 3.3 Create Campaigns

4. Update Ongoing Campaigns: Explore the available workflows for updating a campaign currently in progress. Campaigns Management

4. Campaign Lifecycle Webhooks

WEBHOOKS Documentation