Network Accounts

Introduction

If you manage multiple accounts under a Taboola network, you will be allocated:

  • A network account.
  • Individual sub-accounts for your network.

Your network account is provided to you by Taboola when your API credentials are first created. You can use it to fetch a list of your individual sub-accounts.

Your network account has a special role, and is not used to create and modify campaigns. You will use your individual sub-accounts for this purpose.

Additional uses of the network account are outlined below.

🚧

Video Campaigns

For Video Campaign reporting, see: Video Campaigns.

πŸ“˜

Fetching account details

  1. To fetch your network account details, use the users/current/account endpoint (see above: Get Account Details).

    Your network account is provided to you during onboarding.

  2. To fetch a list of all sub-accounts in your network, use the advertisers endpoint (see below: Get Advertiser Accounts in Network).

    By default, returns sub-accounts (without the network account).

  3. Alternatively, to obtain a list of all accounts for your user credentials, use the users/current/allowed-accounts endpoint (see below: Get Allowed Accounts).

    Returns both the network account and all sub-accounts.

🚧

Which Account ID should I pass?

When invoking a given endpoint, pass the relevant Account ID as a path param.

  1. To get basic details of all campaigns across the network, pass the network account:
    • GET backstage/api/1.0/{network-account}/campaigns/base
  2. To get full details of all campaigns owned by a sub-account, pass the sub-account:
    • GET backstage/api/1.0/{sub-account}/campaigns/
  3. To fetch (or update) an individual campaign, pass the sub-account that owns the campaign (i.e. that created the ca):
    • GET backstage/api/1.0/{sub-account}/campaigns/{campaign_id}

🚧

Campaign owner

The account that created a campaign is the owner of that campaign.

The role of the network account

Your network account has a special role, and is used with specific endpoints only.

The capabilities of the network account are outlined in the sections that follow.

1. Reporting

  1. Report on campaign data across the network:
    • GET backstage/api/1.0/{network-account}/reports/campaign-summary/dimensions/day?start_date=2020-12-30&end_date=2020-12-31

🚧

Video Campaigns

For Video Campaign reporting, see: Video Campaigns.

2. Create a network-wide Custom Audience Rule (/Conversion Rule)

  1. Create a Custom Audience Rule (/Conversion Rule) that is available to all sub-accounts in the network:
    • POST /backstage/api/1.0/{network-account}/universal_pixel/custom_audience_rule/

🚧

Audience Rules (/Conversion Rules) created by the network account

A Custom Audience Rule (/Conversion Rule) created by the network account is visible to all sub-accounts:
- GET /backstage/api/1.0/{sub-account}/universal_pixel/custom_audience_rule/

Similarly, each sub-account can target the audience:
- POST /backstage/api/1.0/{sub-account}/campaigns/123/targeting/custom_audience

However, only the network account can update the Custom Audience Rule (/Conversion Rule).

A Custom Audience Rule can only be updated by the account that created it.

3. Fetch a list of sub-accounts in your network

  1. Fetch a list of sub-accounts in your network:
    • GET /backstage/api/1.0/{network-account}/advertisers

🚧

Each sub-account will be used to create campaigns and items.

4. Perform network-wide bulk operations (on campaigns and items)

For the most part, the network account is not used to modify campaigns and items. However, it can be used for network-wide bulk operations.

Overall, the following operations are supported for campaigns and items:

  1. Fetch basic details for all campaigns across your network (using the campaigns/base endpoint):
    • GET backstage/api/1.0/{network-account}/campaigns/base
  2. Update a single campaign (using the campaigns endpoint):
    • POST backstage/api/1.0/{network-account}/campaigns/1234
    • (This is the only operation that the network account can perform with the campaigns endpoint.)
  3. Bulk update campaigns across your network:
    • POST backstage/api/1.0/{network-account}/campaigns/bulk-update
  4. Bulk update items across your network - e.g. pause all items:
    • POST backstage/api/1.0/{network-account}/items/bulk
  5. Bulk delete items across your network:
    • DELETE backstage/api/1.0/{network-account}/items/bulk
  6. Bulk create items across your network:
    • PUT backstage/api/1.0/{network-account}/items/bulk

🚧

Limitations of the network account

  1. The network account cannot create campaigns (using the campaigns endpoint). Attempting to do so will return 400 - "Campaigns are not allowed on Networks and Groups".

    Each campaign must belong to a specific sub-account.

  2. The network account cannot duplicate a campaign to another account.

    Only the account that owns the campaign can duplicate it to another account.

  3. The network account cannot fetch details for all campaigns (using the campaigns endpoint). Attempting to do so will return 0 results.

    The campaigns endpoint returns only those campaigns owned by that account.

  4. The network account cannot fetch details for a given campaign (using the campaigns endpoint). Attempting to do so will return 404 "Resource not found".

    Only the account that owns the campaign can fetch its full details.

  5. The network account cannot fetch items for a given campaign (using the items endpoint). Attempting to do so will return 403 - "Requested action is forbidden".

    Only the account that owns the campaign can fetch its items.

  6. The network account cannot update a given item or create a new item (using the items endpoint). Attempting to do so will return 403 - "Requested action is forbidden".

    Only the account that owns the campaign can update one of its items or create a new item for it (using the items endpoint).
    (The exception to this rule is bulk operations - see above.)