The Symbiosys API provides retailers with a common interface for managing advertisers, campaigns, and advertising resources across supported channels.
Understanding how these resources relate to your retailer environment will make it easier to navigate and integrate with the API.
Resource Model
At a high level, API resources are organized within your retailer context.
Your Retailer
│
├── Advertisers
│ │
│ └── Campaigns
│
├── Brands
├── Sellers
├── Chains
├── Merchants
├── Audiences
└── Ads Accounts
Your API credentials establish the retailer context and determine which resources are available to your integration.
Your Retailer Context
The retailer represents the top-level context for your API integration.
You do not typically need to provide a retailer ID with every request. Your API credentials establish your retailer context and determine which advertisers, campaigns, and supporting resources your integration can access.
Retailer-level resources can include brands, sellers, chains, merchants, audiences, and ads accounts.
Advertisers
Advertisers represent the brands or organizations that run advertising through your retail media program.
Advertisers sit between your retailer and the campaigns you manage on their behalf:
Your Retailer
↓
Advertiser
↓
Campaign
Advertiser configuration determines which advertising capabilities are available when campaigns are created for that advertiser.
Depending on your retailer configuration and the selected channel, advertiser configuration can include:
-
Country and currency
-
Available advertising channels
-
Supported ad formats
-
Ads accounts
-
Catalog and pixel configuration
-
Available audiences
-
Geo-targeting capabilities
-
Bid strategy controls
-
Product targeting capabilities
-
Product set optimization capabilities
Retailers can use the Advertiser API to synchronize advertiser configuration between their own systems and Symbiosys.
Campaigns
Campaigns represent advertising activity created for advertisers within your retail media program.
Retailers can use the Campaign API to create, retrieve, and manage campaign configuration programmatically.
Campaigns combine common advertising properties with configuration specific to the selected advertising channel.
Common properties can include:
-
Campaign name
-
External ID
-
Country
-
Objective
-
Start and end dates
-
Budget and budget type
-
Bid strategy
-
Product configuration
-
Geographic targeting
-
Asset configuration
Channel-specific behavior is defined separately through the campaign's channel settings.
See Campaigns for a detailed explanation of the campaign model.
Retailer Resources
Your retailer environment can expose supporting resources that are used when configuring advertisers and campaigns.
These include:
Brands
Brands available within your retailer environment.
Sellers
Sellers available within your retailer environment.
Chains
Retailer chain information available to your integration.
Merchants
Merchant resources that can be referenced by applicable advertising configuration.
Audiences
Audiences your retailer makes available for advertising and targeting.
Audience availability can depend on the advertiser and advertising channel.
Ads Accounts
Advertising platform accounts configured for your retailer.
Ads account IDs may be required when configuring advertisers to use particular advertising channels.
Using Retailer Resources
A typical integration may need to retrieve resources from your retailer environment before configuring an advertiser or campaign.
For example:
Identify Advertiser
↓
Retrieve Available Ads Account
↓
Retrieve Available Audiences
↓
Retrieve Other Required Resources
↓
Configure Advertiser or Campaign
Several retailer resource endpoints support lookup by name. This allows your integration to resolve values from your own systems to the Symbiosys resource IDs required by other API operations.
Symbiosys IDs and Retailer IDs
Resources within Symbiosys are assigned Symbiosys IDs.
Your retailer may also maintain its own identifier for the same advertiser, campaign, or other supported resource.
For endpoints that support the use_client_ids parameter:
use_client_ids=false
indicates that supplied IDs should be interpreted as Symbiosys IDs.
use_client_ids=true
allows supported identifiers to be resolved using the corresponding retailer-provided ID.
Using retailer-provided IDs can simplify synchronization between Symbiosys and your existing systems.
Common Model, Channel-Specific Capabilities
Symbiosys provides retailers with a common campaign model across supported advertising channels.
Common advertising concepts are standardized where possible:
Campaign
├── Dates
├── Budget
├── Objective
├── Bid Strategy
├── Products
├── Geography
└── Assets
Channel-specific configuration supplements this common model when an advertising platform requires additional settings.
This allows your integration to use a consistent overall structure while still accessing capabilities unique to individual channels.
Available configuration can depend on your retailer setup, the advertiser, selected channel, campaign type, and capabilities enabled for that advertiser.
See Campaigns for additional information.