BuySellAds Content Portal

Best Practices For Using the BuySellAds DFP API

Last Updated on December 20, 2016

Best Practices for Using the BuySellAds DFP API

Biases aside, the BuySellAds DFP API is simply amazing. It allows you to unlock new potential revenue without ever leaving the comfort of your ad server. Once you approve the order the line item and creatives are trafficked in your DFP automagically. You don’t even have to put down your latte.

Now, with any API connection you’re giving the provider a certain level of access to your system – in this case, your DFP. As such, it is important to follow some best practices.

If that latte is pretty full and you don’t have something better to do, Google has a great support document that outlines how DFP handles authentication. What we’re after is the section on “Scope“. In this case, the only scope (“permission“) available is:

  • Read/write access to DFP API

Okay, I know that probably doesn’t mean much, but in a nutshell, it means our API has the same level of access to your DFP as the DFP user you used to authenticate your account when connecting the BuySellAds API. For example, let’s say Bob has “Administrator” access to your DFP. If Bob’s credentials are used when connecting BuySellAds to your DFP, our API will have access to everything in your DFP (the same access as his administrator role).

When you authenticate your DFP account with BuySellAds, we only ever modify your account through our API. We don’t know your password, nor is it stored anywhere on our server.

Furthermore, the credentials are only valid for our server, and all communication between our servers and the DFP servers is encrypted.

After the API connection is made we use it to perform common actions in your DFP, again, only about orders relevant to BuySellAds. These actions include:

  • Creating a BuySellAds advertiser
  • Create / Edit BSA-related orders (appears with the prefix “BuySellAds Self-Serve“)
  • Create / Edit line items and creatives under the BuySellAds order(s)
  • Scheduling and activation of these line items
  • Continual synchronization of line-item status with BuySellAds-status
  • Report generation

So what IS the best practice?

If you’re okay with our API having full access to your DFP, then you don’t need to do anything special. If you’re not, then it’s best to create a new user and give that user a special role that limits their scope.

You can create a new role in DFP by heading to Settings > Roles > “New role” (there is also a handful of default roles to chose from). Once you click “New role” you’ll see there are a lot of options to chose from. At the very minimum, our API requires the following options be selected:

Define and deliver orders

  • View all orders and line items
  • Edit the priority and delivery rate for line items
  • View creatives
  • Edit creatives
  • Enable and disable creatives
  • Pause, unpause, archive and unarchive orders and line items
  • Approve and reject orders and line items
  • Overbook sponsorship line items
  • View ad units, placements, and key-values
  • Run availability forecasts
  • View my orders and line items
  • Edit approved orders and line items
  • Activate line items
  • Edit creative templates
  • Edit orders and line items and submit for approval
  • Overbook standard line items
  • View line item defaults
  • View ad exclusion rules
  • Edit key-values values

Manage people

  • View users, roles, and teams
  • View companies and contacts
  • Edit companies
  • Edit contacts
  • View change history
  • Edit labels
  • Edit custom fields

Define and deliver orders

  • Create and view all reports
  • View dynamic allocation opportunity report

After you’ve defined the new role, you can create a new user via Settings > Users > New user. Simply give the user a name, fill in the required details, then set the “Role” to the name of the role created above.

Congratulations! You have setup the BuySellAds DFP API integration following our recommended best practices.

How our API interacts with in your DFP

Line Item

  • Start Date (if changed)
  • End Date (if changed *OR* past)
  • costType
  • costPerUnit
  • Goal (impressions/share %)
  • lineItemType – ‘Sponsorship‘ for fixed rate ads and ‘Standard‘ for CPM


  • GEO Targeting
  • Custom Criteria (key/value)


  • Creative placeholders: There is always a single creative of the same size as the zone
  • creativeRotationType: always “EVEN”
  • deliveryRateType: always “EVENLY”


  • allowOverbook: always “TRUE”