{"id":4897,"library":"bingads","title":"Bing Ads Python SDK","description":"The Bing Ads Python SDK (pypi-slug: `bingads`) is a client library designed to simplify interactions with the Microsoft Advertising (formerly Bing Ads) SOAP API. It provides proxy classes for various web services, abstracts OAuth authentication, and offers high-level interfaces for campaign management, bulk operations, and reporting. The library is actively maintained with frequent updates to reflect changes in Bing Ads API Version 13.","status":"active","version":"13.0.27","language":"en","source_language":"en","source_url":"https://github.com/BingAds/BingAds-Python-SDK","tags":["ads","marketing","microsoft","bing","api","soap","advertising"],"install":[{"cmd":"pip install bingads","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used as a SOAP proxy to instantiate Bing Ads API programming elements.","package":"suds-jurko","optional":false},{"reason":"HTTP client for API communication.","package":"requests","optional":false},{"reason":"Python 2/3 compatibility layer (often included for broader compatibility).","package":"future","optional":false},{"reason":"Python 2/3 compatibility utilities.","package":"six","optional":false},{"reason":"Enum backport for older Python versions, if not natively available.","package":"enum34","optional":false}],"imports":[{"note":"Core class for holding authentication details.","symbol":"AuthorizationData","correct":"from bingads.authorization import AuthorizationData"},{"note":"Used for managing OAuth authentication flow and tokens.","symbol":"OAuthDesktopMobileApplication","correct":"from bingads.authorization import OAuthDesktopMobileApplication"},{"note":"The SDK provides its own ServiceClient wrapper around Suds. Directly using suds.client can lead to unexpected behavior or missing SDK features.","wrong":"from suds.client import Client","symbol":"ServiceClient","correct":"from bingads.service_client import ServiceClient"},{"note":"High-level manager for bulk operations.","symbol":"BulkServiceManager","correct":"from bingads.service_client import BulkServiceManager"},{"note":"High-level manager for reporting operations.","symbol":"ReportingServiceManager","correct":"from bingads.service_client import ReportingServiceManager"},{"note":"Import for a specific service, version-prefixed as per SDK structure.","symbol":"CustomerManagementService","correct":"from bingads.v13.customermanagement import CustomerManagementService"}],"quickstart":{"code":"import os\nfrom bingads.authorization import AuthorizationData, OAuthDesktopMobileApplication\nfrom bingads.service_client import ServiceClient\n\n# --- Configuration (replace with your actual values or env vars) ---\nDEVELOPER_TOKEN = os.environ.get('BINGADS_DEVELOPER_TOKEN', 'YOUR_DEVELOPER_TOKEN_HERE')\nCLIENT_ID = os.environ.get('BINGADS_CLIENT_ID', 'YOUR_CLIENT_ID_HERE')\nREFRESH_TOKEN = os.environ.get('BINGADS_REFRESH_TOKEN', '') # Obtain this initially via user consent flow\n\n# NOTE: For server-side apps, the REFRESH_TOKEN needs to be obtained once via a browser-based flow\n# and then stored securely. This example assumes a refresh token is available.\n\n# Define the OAuth scope for the Bing Ads API.\nOAUTH_SCOPE = ['https://ads.microsoft.com/.default']\n\nif not REFRESH_TOKEN:\n    print(\"WARNING: REFRESH_TOKEN not set. This example will only work if you manually obtain a refresh token.\")\n    print(\"Refer to Bing Ads Python SDK documentation for obtaining refresh token via OAuth flow.\")\n    # In a real application, you'd initiate the OAuth flow here if no refresh token is present.\n    # For this quickstart, we'll proceed assuming an empty token or one from env.\n\n# Setup AuthorizationData\nauthorization_data = AuthorizationData(\n    developer_token=DEVELOPER_TOKEN,\n    authentication=OAuthDesktopMobileApplication(\n        client_id=CLIENT_ID,\n        oauth_scopes=OAUTH_SCOPE\n    )\n)\n\n# Set the refresh token if available\nif REFRESH_TOKEN:\n    authorization_data.authentication.refresh_token = REFRESH_TOKEN\n\n# Example: Get a list of accessible accounts\ntry:\n    # Get Customer Management Service Client\n    customer_service = ServiceClient(\n        service='CustomerManagementService',\n        version=13,\n        authorization_data=authorization_data\n    )\n\n    # Authenticate and get an access token (if refresh token is valid)\n    if not authorization_data.authentication.oauth_tokens:\n        authorization_data.authentication.request_oauth_tokens(authorization_data.authentication.refresh_token)\n    \n    # If the refresh token was empty, this will likely fail unless the user interactively provides consent.\n    # For a quickstart, we assume refresh_token is pre-populated for non-interactive execution.\n    print(f\"Access Token: {authorization_data.authentication.oauth_tokens.access_token[:10]}...\\n\")\n\n    # Get User accounts\n    user_accounts = customer_service.GetAccountsInfo(\n        UserId=None, # None implies current authenticated user\n        ReturnAdditionalFields=customer_service.factory.create('AccountAdditionalField').None\n    )\n\n    if user_accounts and user_accounts.AccountInfo:\n        print(\"Successfully retrieved accounts:\")\n        for account in user_accounts.AccountInfo:\n            print(f\"- Account ID: {account.Id}, Name: {account.Name}, Number: {account.Number}\")\n    else:\n        print(\"No accounts found or accessible.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    if \"AuthenticationToken\" in str(e) or \"DeveloperToken\" in str(e) or \"Customer \" in str(e):\n        print(\"Please ensure your DEVELOPER_TOKEN, CLIENT_ID, and REFRESH_TOKEN are correctly configured and valid.\")\n        print(\"If running for the first time or if the refresh token is expired, you might need to run an interactive OAuth flow.\")\n","lang":"python","description":"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."},"warnings":[{"fix":"For 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.","message":"The `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.","severity":"breaking","affected_versions":"All versions of `bingads` (as it's SOAP-based)"},{"fix":"Always 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.","message":"When 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`.","severity":"breaking","affected_versions":"All major API version upgrades (e.g., v12 to v13)"},{"fix":"Implement 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.","message":"Initial 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.","severity":"gotcha","affected_versions":"All versions using OAuth authentication"},{"fix":"Ensure your OAuth client application is configured for the `https://ads.microsoft.com/.default` scope. Update sandbox authentication configurations to use `login.windows-ppe.net`.","message":"The 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.","severity":"deprecated","affected_versions":"Versions 13.0.15 and earlier might default to older scopes; `login.live-int.com` for sandbox auth is being phased out."},{"fix":"Familiarize yourself with the new developer portal interface once it becomes available to ensure continued access to developer token management.","message":"The Microsoft Advertising Developer Portal page for obtaining developer tokens is scheduled for deprecation on May 31, 2025. A new portal will replace it.","severity":"deprecated","affected_versions":"Users relying on the old Developer Portal interface"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}