Skip to main content
Availability
Available Airbyte CloudAvailable Airbyte OSSAvailable PyAirbyte
Support Level
Certified
Latest Version
2.5.0

Bing Ads

This page contains the setup guide and reference information for the Bing Ads source connector.

Prerequisites​

  • Microsoft Advertising account
  • Microsoft Developer Token

Setup guide​

For Airbyte Open Source set up your application to get Client ID, Client Secret, Refresh Token

  1. Register your application in the Azure portal.
  2. Request user consent to get the authorization code.
  3. Use the authorization code to get a refresh token.
note

The refresh token expires in 90 days. Repeat the authorization process to get a new refresh token. The full authentication process described here. Please be sure to authenticate with the email (personal or work) that you used to sign in to the Bing ads/Microsoft ads platform.

Step 1: Set up Bing Ads​

  1. Get your Microsoft developer token. To use Bing Ads APIs, you must have a developer token and valid user credentials. See Microsoft Advertising docs for more info.

    1. Sign in with Super Admin credentials at the Microsoft Advertising Developer Portal account tab.
    2. Choose the user that you want associated with the developer token. Typically an application only needs one universal token regardless how many users will be supported.
    3. Click on the Request Token button.

  2. If your OAuth app has a custom tenant, and you cannot use Microsoft’s recommended common tenant, use the custom tenant in the Tenant ID field when you set up the connector.

info

The tenant is used in the authentication URL, for example: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize

Step 2: Set up the source connector in Airbyte​

For Airbyte Cloud:

  1. Log in to your Airbyte Cloud account.
  2. Click Sources and then click + New source.
  3. On the Set up the source page, select Bing Ads from the Source type dropdown.
  4. Enter a name for your source.
  5. For Tenant ID, enter the custom tenant or use the common tenant.
  6. Add the developer token from Step 1.
  7. For Account Names Predicates - see predicates in bing ads docs. Will be used to filter your accounts by specified operator and account name. You can use multiple predicates pairs. The Operator is a one of Contains or Equals. The Account Name is a value to compare Accounts Name field in rows by specified operator. For example, for operator=Contains and name=Dev, all accounts where name contains dev will be replicated. And for operator=Equals and name=Airbyte, all accounts where name is equal to Airbyte will be replicated. Account Name value is not case-sensitive.
  8. For Reports Replication Start Date, enter the date in YYYY-MM-DD format. The data added on and after this date will be replicated. If this field is blank, Airbyte will replicate all data from previous and current calendar years.
  9. For Lookback window (also known as attribution or conversion window) enter the number of days to look into the past. If your conversion window has an hours/minutes granularity, round it up to the number of days exceeding. If you're not using performance report streams in incremental mode and Reports Start Date is not provided, let it with 0 default value.
  10. For Custom Reports - see custom reports section, list of custom reports object:
  11. For Report Name enter the name that you want for your custom report.
  12. For Reporting Data Object add the Bing Ads Reporting Object that you want to sync in the custom report.
  13. For Columns add list columns of Reporting Data Object that you want to see in the custom report.
  14. For Aggregation add time aggregation. See report aggregation section.
  15. Click Authenticate your Bing Ads account.
  16. Log in and authorize the Bing Ads account.
  17. Click Set up source.

For Airbyte Open Source:

  1. Log in to your Airbyte Open Source account.

  2. Click Sources and then click + New source.

  3. On the Set up the source page, select Bing Ads from the Source type dropdown.

  4. Enter a name for your source.

  5. For Tenant ID, enter the custom tenant or use the common tenant.

  6. Enter the Client ID, Client Secret, Refresh Token, and Developer Token from Step 1.

  7. For Account Names Predicates - see predicates in bing ads docs. Will be used to filter your accounts by specified operator and account name. You can use multiple predicates pairs. The Operator is a one of Contains or Equals. The Account Name is a value to compare Accounts Name field in rows by specified operator. For example, for operator=Contains and name=Dev, all accounts where name contains dev will be replicated. And for operator=Equals and name=Airbyte, all accounts where name is equal to Airbyte will be replicated. Account Name value is not case-sensitive.

  8. For Reports Replication Start Date, enter the date in YYYY-MM-DD format. The data added on and after this date will be replicated. If this field is blank, Airbyte will replicate all data from previous and current calendar years.

  9. For Lookback window (also known as attribution or conversion window) enter the number of days to look into the past. If your conversion window has an hours/minutes granularity, round it up to the number of days exceeding. If you're not using performance report streams in incremental mode and Reports Start Date is not provided, let it with 0 default value.

  10. For Custom Reports - see custom reports section:

  11. For Report Name enter the name that you want for your custom report.

  12. For Reporting Data Object add the Bing Ads Reporting Object that you want to sync in the custom report.

  13. For Columns add columns of Reporting Data Object that you want to see in the custom report.

  14. For Aggregation select time aggregation. See report aggregation section.

  15. Click Set up source.

Supported sync modes​

The Bing Ads source connector supports the following sync modes:

Supported Streams​

The Bing Ads source connector supports the following streams. For more information, see the Bing Ads API.

Basic streams​

Report Streams​

note

Be careful with removing fields that you don't want to sync in the Replication Stream Settings. Report will be generated by request with all fields in the Stream Schema. Removing fields from in the setting does not affect actual request for the report. The results of such a report can be not accurate due to not visible values in removed fields. If you faced this issue please use custom report, where you can define only that fields that you want to see in the report, and no other fields will be used in the request.

info

Ad Group Impression Performance Report, Geographic Performance Report, Account Impression Performance Report have user-defined primary key. This means that you can define your own primary key in Replication tab in your connection for these streams.

Example pk: Ad Group Impression Performance Report: composite pk - [AdGroupId, Status, TimePeriod, AccountId] Geographic Performance Report: composite pk - [AdGroupId, Country, State, MetroArea, City] Account Impression Performance Report: composite pk - [AccountName, AccountNumber, AccountId, TimePeriod]

Note: These are just examples, and you should consider your own data and needs in order to correctly define the primary key.

See more info about user-defined pk here.

Custom Reports​

You can build your own report by providing:

  • Report Name - name of the stream
  • Reporting Data Object - Bing Ads reporting data object that you can find here. All data object with ending ReportRequest can be used as data object in custom reports.
  • Columns - Reporting object columns that you want to sync. You can find it on ReportRequest data object page by clicking the ...ReportColumn link in Bing Ads docs. The report must include the Required Columns (you can find it under list of all columns of reporting object) at a minimum. As a general rule, each report must include at least one attribute column and at least one non-impression share performance statistics column. Be careful you can't add extra columns that not specified in Bing Ads docs and not all fields can be skipped.
  • Aggregation - Hourly, Daily, Weekly, Monthly, DayOfWeek, HourOfDay, WeeklyStartingMonday, Summary. See report aggregation.

Report aggregation​

All reports synced by this connector can be aggregated using hourly, daily, weekly, or monthly time windows.

For example, if you select a report with daily aggregation, the report will contain a row for each day for the duration of the report. Each row will indicate the number of impressions recorded on that day.

A report's aggregation window is indicated in its name. For example, account_performance_report_hourly is the Account Performance Reported aggregated using an hourly window.

Limitations & Troubleshooting​

Expand to see details about Bing Ads connector limitations and troubleshooting.

Connector limitations​

Rate limiting​

The Bing Ads API limits the number of requests for all Microsoft Advertising clients. You can find detailed info here.

Troubleshooting​

  • Check out common troubleshooting issues for the Bing Ads source connector on our Airbyte Forum.

Reference​

Config fields reference

Field
Type
Property name
string
client_id
string
refresh_token
string
developer_token
auth_method
"oauth2.0"
auth_method
string
tenant_id
string
client_secret
array<object>
account_names
string
reports_start_date
integer
lookback_window
array<object>
custom_reports

Changelog​

VersionDatePull RequestSubject
2.5.02024-03-2135891Accounts stream: add TaxCertificate field to schema.
2.4.02024-03-1936267Pin airbyte-cdk version to ^0
2.3.02024-03-0535812New streams: Audience Performance Report, Goals And Funnels Report, Product Dimension Performance Report.
2.2.02024-02-1335201New streams: Budget and Product Dimension Performance.
2.1.42024-02-1235179Manage dependencies with Poetry.
2.1.32024-01-3134712Fix duplicated records for report-based streams
2.1.22024-01-0934045Speed up record transformation
2.1.12023-12-1533500Fix state setter when state was provided
2.1.02023-12-0533095Add account filtering
2.0.12023-11-1632597Fix start date parsing from stream state
2.0.02023-11-0731995Schema update for Accounts, Campaigns and Search Query Performance Report streams. Convert date and date-time fields to standard RFC3339
1.13.02023-11-1332306Add Custom reports and decrease backoff max tries number
1.12.12023-11-1032422Normalize numeric values in reports
1.12.02023-11-0932340Remove default start date in favor of Time Period - Last Year and This Year, if start date is not provided
1.11.02023-11-0632201Skip broken CSV report files
1.10.02023-11-0632148Add new fields to stream Ads: "BusinessName", "CallToAction", "Headline", "Images", "Videos", "Text"
1.9.02023-11-0332131Add "CampaignId", "AccountId", "CustomerId" fields to Ad Groups, Ads and Campaigns streams.
1.8.02023-11-0232059Add new streams CampaignImpressionPerformanceReport (daily, hourly, weekly, monthly)
1.7.12023-11-0232088Raise config error when user does not have accounts
1.7.02023-11-0132027Add new streams AdGroupImpressionPerformanceReport
1.6.02023-10-3132008Add new streams Keywords
1.5.02023-10-3031952Add new streams Labels, App install ads, Keyword Labels, Campaign Labels, App Install Ad Labels, Ad Group Labels
1.4.02023-10-2731885Add new stream: AccountImpressionPerformanceReport (daily, hourly, weekly, monthly)
1.3.02023-10-2631837Add new stream: UserLocationPerformanceReport (daily, hourly, weekly, monthly)
1.2.02023-10-2431783Add new stream: SearchQueryPerformanceReport (daily, hourly, weekly, monthly)
1.1.02023-10-2431712Add new stream: AgeGenderAudienceReport (daily, hourly, weekly, monthly)
1.0.22023-10-1931599Base image migration: remove Dockerfile and use the python-connector-base image
1.0.12023-10-1631432Remove primary keys from the geographic performance reports - complete what was missed in version 1.0.0
1.0.02023-10-1131277Remove primary keys from the geographic performance reports.
0.2.32023-09-2830834Wrap auth error with the config error.
0.2.22023-09-2730791Fix missing fields for geographic performance reports.
0.2.12023-09-0430128Add increasing download timeout if ReportingDownloadException occurs
0.2.02023-08-1727619Add Geographic Performance Report
0.1.242023-06-2227619Retry request after facing temporary name resolution error.
0.1.232023-05-1125996Implement a retry logic if SSL certificate validation fails.
0.1.222023-05-0824223Add CampaignLabels report column in campaign performance report
0.1.212023-04-2825668Add undeclared fields to accounts, campaigns, campaign_performance_report, keyword_performance_report and account_performance_report streams
0.1.202023-03-0923663Add lookback window for performance reports in incremental mode
0.1.192023-03-0823868Add dimensional-type columns for reports.
0.1.182023-01-3022073Fix null values in the Keyword column of keyword_performance_report streams
0.1.172022-12-1020005Add Keyword to keyword_performance_report stream
0.1.162022-10-1217873Fix: added missing campaign types in (Audience, Shopping and DynamicSearchAds) in campaigns stream
0.1.152022-10-0317505Fix: limit cache size for ServiceClient instances
0.1.142022-09-2917403Fix: limit cache size for ReportingServiceManager instances
0.1.132022-09-2917386Migrate to per-stream states.
0.1.122022-09-0516335Added backoff for socket.timeout
0.1.112022-08-2515684 (published in 15987)Fixed log messages being unreadable
0.1.102022-08-1215602Fixed bug caused Hourly Reports to crash due to invalid fields set
0.1.92022-08-0214862Added missing columns
0.1.82022-06-1513801All reports hourly/daily/weekly/monthly will be generated by default, these options are removed from input configuration
0.1.72022-05-1712937Added OAuth2.0 authentication method, removed redirect_uri from input configuration
0.1.62022-04-3012500Improve input configuration copy
0.1.52022-01-0111652Rebump attempt after DockerHub failure at registring the 0.1.4
0.1.42022-03-2211311Added optional Redirect URI & Tenant ID to spec
0.1.32022-01-149510Fixed broken dependency that blocked connector's operations
0.1.22021-12-148429Update titles and descriptions
0.1.12021-08-315750Added reporting streams)
0.1.02021-07-224911Initial release supported core streams (Accounts, Campaigns, Ads, AdGroups)
Was this page helpful?