Getting Started

Our website hosts videos detailing our features, which are also described in technical detail in this documentation. A video overview of our integration process is found below. If you're ready to integrate, go to Integrating with Promoted.


There are three main options for getting started with Promoted:

  1. Integrate with both ads and organic
  2. Integrate with organic only (i.e., search and discovery)
  3. Integrate with ads only (i.e., native ads and sponsored search)

You can always start with ads or organic, and then add more functionality down the road. The Promoted team adapts to the needs of each business.

Initial discussions

You'll meet with Promoted to discuss your goals and existing infrastructure. Please come prepared with the following information:

  • Your goals and business objectives related to search, feed, and/or native ads.
  • Technology details like your cloud providers, geographic regions, programming languages, etc., as well as information about existing search tools and models you use and signals you collect.
  • Details about the queries that Promoted will rank, such as the query type and volume.

Promoted will then setup your environment. You may have additional engineering follow-up calls to further customize your needs.

5 minute summary for Promoted integration

Here are terms that your team will encounter during the integration. For more detail on Promoted and ads terminology, see the Glossary.

  • Delivery API - Our API that matches content to the user and delivers ranked results in response to search queries and other user actions.
  • Insertion - An item in the response list, generated after the user performs an action like submitting a search query. Promoted initially generates a large list of items, then narrows down to a subset of insertions to return to the user interface. Insertions differ from impressions, because insertions may not necessarily get viewed by the user.
  • Impression - A binary measurement an item, or insertion, is viewed on the user's screen above some viewing and time threshold. For example, the International Advertising Board counts an impression when an item is at least 50% visible for at least 1 second.

Please share this page with other engineers who work with Promoted.