Overview of Campaign and Reporting Endpoints
Pentaleap provides an HTTP-based REST API to support integrations.
The endpoints described in this documentation are detailed with parameters and further information in the respective section for each. This is an overview of what each endpoint is used for and some best practise for users of the endpoints.
Access to the endpoints is dependent on each partner's use case, so not all endpoints are relevant for every partner.
These endpoints describe how a retailer is set up and the available ad units (formerly called Ad Grids) they run on their properties. Here is a visual overview of the structure:
Pentaleap supports both single and multi-publisher retailers as standard and will provide an organisation ID to all new retailer partners. These might be different banners within one market or across geographies.
Brands and advertisers can be shared across organizations for easy campaign setup and management - so advertisers can manage multi-retailer campaigns seamlessly. The Organization endpoint retrieves a list of all available brands for a given organization.
Publishers are distinct retailers within an organization, typically a banner within a retail group.
The Publisher endpoints allow users to retrieve information about each publisher including the products and brands available under each publisher and the ID of each publisher, which is used for further operations.
Each publisher also has one or more Sites under them, for example a retailer may have different sites set up for Desktop and App, or for different geographic markets. Site IDs and names are retrieved from the Sites endpoint. Each Site is tied to a particular product feed (set up by the retailer and not relevant for the scope of this documentation), and each market (eg. US, GB, MX) has its own product feed and currency.
Ad Units are the ad units a retailer has set up in their various publishers, markets and sites and which are optionally available for campaign targeting. The Ad-Grid endpoint retrieves a list of available ad units for a Publisher and Site. While each ad unit is named, the locations are most relevant for any targeting purposes.
These endpoints are used for advertiser and campaign creation and management via Pentaleap's first-party DSP, as well as reporting on campaign performance and status.
Advertisers access is managed by the retailer and is designed to be flexible depending on the retailer setup. An example structure is shown below
Retailers can grant access to all or a subset of available publishers, and retailers also assign available brands to each advertiser within and across publishers.
Advertisers create campaigns within one publisher at a time, but can target any and all of their associated brands and products within a campaign. Campaigns can also target specific retailer locations such as Search, Homepage and Category, but this is optional. We recommend that campaigns default to targeting across all locations since Crealytics adserving technology is designed to place ads in the most relevant place in real time.
The Advertiser endpoints allow users to retrieve (and if applicable create and update) advertiser information. This includes the brands, locations and sites they are eligible to target.
Multiple advertisers can be allocated against the same brand, but this will be listed specifically in the exclusive-brands endpoint to avoid unwanted crossover of brands.
The Campaign endpoints are used to create and report on campaigns for a specified advertiser. This includes choosing markets and locations to target, dates, budget-setting, setting campaigns live or pausing them, adding default bids as well as reporting on campaign and product-level performance metrics.
Campaign-Products endpoints are used to set and update product-level bids and settings to optimise campaigns. There are also endpoints to help filter and bulk edit campaign settings for groups of products such as brands or categories within campaigns.
NB. Targeting locations are available within the campaign setup options, however we typically recommend to target all locations by default, as Crealytics relevancy technology specialises in only placing ads where they are naturally relevant to the customer's need.