Install & Compatibility
Where this runs
tested against v13.0.29 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.654s · 32.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.7s · import 1.588s · 33MB
30MB installed
● package 30MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AuthorizationData
✓ from bingads.authorization import AuthorizationData
Core class for holding authentication details.
OAuthDesktopMobileApplication
✓ from bingads.authorization import OAuthDesktopMobileApplication
Used for managing OAuth authentication flow and tokens.
ServiceClient
✓ from bingads.service_client import ServiceClient
✗ from suds.client import Client
The SDK provides its own ServiceClient wrapper around Suds. Directly using suds.client can lead to unexpected behavior or missing SDK features.
BulkServiceManager
✓ from bingads.service_client import BulkServiceManager
High-level manager for bulk operations.
ReportingServiceManager
✓ from bingads.service_client import ReportingServiceManager
High-level manager for reporting operations.
CustomerManagementService
✓ from bingads.v13.customermanagement import CustomerManagementService
Import for a specific service, version-prefixed as per SDK structure.
This quickstart demonstrates how to authenticate with the Bing Ads API using OAuth and retrieve a list of accessible accounts. It assumes you have a Developer Token, Client ID, and a pre-obtained Refresh Token (which for server-side applications requires an initial interactive OAuth consent flow to acquire). Ensure `BINGADS_DEVELOPER_TOKEN`, `BINGADS_CLIENT_ID`, and `BINGADS_REFRESH_TOKEN` environment variables are set or replace the placeholders directly.
import os
from bingads.authorization import AuthorizationData, OAuthDesktopMobileApplication
from bingads.service_client import ServiceClient
# --- Configuration (replace with your actual values or env vars) ---
DEVELOPER_TOKEN = os.environ.get('BINGADS_DEVELOPER_TOKEN', 'YOUR_DEVELOPER_TOKEN_HERE')
CLIENT_ID = os.environ.get('BINGADS_CLIENT_ID', 'YOUR_CLIENT_ID_HERE')
REFRESH_TOKEN = os.environ.get('BINGADS_REFRESH_TOKEN', '') # Obtain this initially via user consent flow
# NOTE: For server-side apps, the REFRESH_TOKEN needs to be obtained once via a browser-based flow
# and then stored securely. This example assumes a refresh token is available.
# Define the OAuth scope for the Bing Ads API.
OAUTH_SCOPE = ['https://ads.microsoft.com/.default']
if not REFRESH_TOKEN:
print("WARNING: REFRESH_TOKEN not set. This example will only work if you manually obtain a refresh token.")
print("Refer to Bing Ads Python SDK documentation for obtaining refresh token via OAuth flow.")
# In a real application, you'd initiate the OAuth flow here if no refresh token is present.
# For this quickstart, we'll proceed assuming an empty token or one from env.
# Setup AuthorizationData
authorization_data = AuthorizationData(
developer_token=DEVELOPER_TOKEN,
authentication=OAuthDesktopMobileApplication(
client_id=CLIENT_ID,
oauth_scopes=OAUTH_SCOPE
)
)
# Set the refresh token if available
if REFRESH_TOKEN:
authorization_data.authentication.refresh_token = REFRESH_TOKEN
# Example: Get a list of accessible accounts
try:
# Get Customer Management Service Client
customer_service = ServiceClient(
service='CustomerManagementService',
version=13,
authorization_data=authorization_data
)
# Authenticate and get an access token (if refresh token is valid)
if not authorization_data.authentication.oauth_tokens:
authorization_data.authentication.request_oauth_tokens(authorization_data.authentication.refresh_token)
# If the refresh token was empty, this will likely fail unless the user interactively provides consent.
# For a quickstart, we assume refresh_token is pre-populated for non-interactive execution.
print(f"Access Token: {authorization_data.authentication.oauth_tokens.access_token[:10]}...\n")
# Get User accounts
user_accounts = customer_service.GetAccountsInfo(
UserId=None, # None implies current authenticated user
ReturnAdditionalFields=customer_service.factory.create('AccountAdditionalField').None
)
if user_accounts and user_accounts.AccountInfo:
print("Successfully retrieved accounts:")
for account in user_accounts.AccountInfo:
print(f"- Account ID: {account.Id}, Name: {account.Name}, Number: {account.Number}")
else:
print("No accounts found or accessible.")
except Exception as e:
print(f"An error occurred: {e}")
if "AuthenticationToken" in str(e) or "DeveloperToken" in str(e) or "Customer " in str(e):
print("Please ensure your DEVELOPER_TOKEN, CLIENT_ID, and REFRESH_TOKEN are correctly configured and valid.")
print("If running for the first time or if the refresh token is expired, you might need to run an interactive OAuth flow.")
Debug
Known issues
breakingThe `bingads` library is built for the legacy SOAP API. Microsoft has introduced a new REST API-based SDK called `msads` (available via `pip install msads`), which offers better performance, simpler architecture, and modern Python features. While `bingads` is still supported, new projects are encouraged to consider `msads` for future compatibility and benefits.fixFor new projects, evaluate migrating to the `msads` library and the REST API. For existing projects, be aware that new features might first appear in the REST API. Refer to the official 'Migration Guide - SOAP to REST for Python SDK' for details.
affects: All versions of `bingads` (as it's SOAP-based)
breakingWhen upgrading between major Bing Ads API versions (e.g., from v12 to v13), there can be significant changes in SOAP object namespaces or structure that can cause `suds.resolver:(ClassGoesHere) not-found` errors. For example, `ns4:DateRangeSearchParameter` might become `DateRangeSearchParameter`.fixAlways review the Bing Ads API release notes and migration guides (e.g., 'Migrate to Bing Ads API Version 13') for namespace and schema changes. Use the SDK's `service_client.factory.create()` method and inspect generated XML or object structures to identify correct types.
affects: All major API version upgrades (e.g., v12 to v13)
gotchaInitial OAuth authentication for the Bing Ads API (to obtain a refresh token) requires a user to interact with a browser, even for non-interactive (server-side) applications. This refresh token then needs to be securely stored and used for subsequent non-interactive access token refreshes.fixImplement an initial one-time interactive OAuth flow (e.g., via a local web server or a desktop application) to get the refresh token. Store this refresh token securely (e.g., in environment variables, a vault, or a secure configuration file) and use it to obtain new access tokens programmatically. Do not hardcode refresh tokens directly in code.
affects: All versions using OAuth authentication
deprecatedThe default OAuth scope for `bingads` SDK has transitioned to `https://ads.microsoft.com/.default` (or `msads.manage`). Additionally, the sandbox authentication endpoint `login.live-int.com` has been replaced by `login.windows-ppe.net` and will be deprecated.fixEnsure your OAuth client application is configured for the `https://ads.microsoft.com/.default` scope. Update sandbox authentication configurations to use `login.windows-ppe.net`.
affects: Versions 13.0.15 and earlier might default to older scopes; `login.live-int.com` for sandbox auth is being phased out.
deprecatedThe Microsoft Advertising Developer Portal page for obtaining developer tokens is scheduled for deprecation on May 31, 2025. A new portal will replace it.fixFamiliarize yourself with the new developer portal interface once it becomes available to ensure continued access to developer token management.
affects: Users relying on the old Developer Portal interface
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'bingads'
The 'bingads' Python SDK library is not installed in your current Python environment, or the environment where your script is being run does not have it installed.
fixInstall the bingads package using pip: `pip install bingads`
OAuthTokenRequestException: error_code: invalid_client, error_description: AADSTS70002: The provided request must include a 'client_secret' input parameter. OR <AdApiError><Code>105</Code><Message>Authentication failed. Either supplied credentials are invalid or the account is inactive</Message></AdApiError>
These errors indicate issues with your OAuth 2.0 application registration or credentials, such as an incorrect Client ID, a missing Client Secret (for confidential applications), an invalid Redirect URI, an expired refresh token, or an outdated OAuth scope. Error code 105 specifically signals invalid credentials or an inactive account.
fixEnsure your Azure AD application registration has the correct 'client_id', 'client_secret' (if applicable), and 'redirect_uri' configured. Regenerate your refresh token using the correct and current OAuth scopes (e.g., `https://ads.microsoft.com/.default` or `msads.manage`), and ensure your developer token is valid for the target environment (production or sandbox).
suds.WebFault: Server raised fault: 'Invalid client data. Check the SOAP fault details for more information.' OR suds.TypeNotFound: Type not found: 'Aggregation'
These errors generally point to issues with the structure or content of the SOAP request being sent to the Bing Ads API, or a version incompatibility with the underlying `suds` library. 'Type not found' specifically suggests that a complex data type expected by the API is not being correctly generated or referenced by Suds.
fixVerify that all data objects and their properties in your request precisely match the Bing Ads API documentation for the specific service and version you are using. Ensure you are using a compatible `suds` library, such as `suds-community` (recommended by Microsoft). For 'Type not found' errors, explicitly use namespace prefixes (e.g., `ns3:ArrayOfstring`) for Suds objects or leverage the dictionary approach for object creation where appropriate. Enable SUDS logging to inspect the exact SOAP XML payload being sent to the API.
Upgrade
Version history
13.0.29latest on PyPI · released Aug 3, 2026
Audit
Dependencies
suds-jurkorequiredUsed as a SOAP proxy to instantiate Bing Ads API programming elements.
requestsrequiredHTTP client for API communication.
futurerequiredPython 2/3 compatibility layer (often included for broader compatibility).
sixrequiredPython 2/3 compatibility utilities.
enum34requiredEnum backport for older Python versions, if not natively available.