Bing Ads API: Fix Setup Errors & Migrate to REST API
Why This Is Happening
I've worked with the Bing Ads API across dozens of enterprise advertising setups , and right now, in mid-2026, there is one root cause behind the majority of issues I'm seeing: the ongoing Microsoft Advertising transition from the legacy SOAP API to the new REST API. If your integration is suddenly throwing authentication failures, deprecated method errors, or unexpected 400/500 responses, that transition is almost certainly the culprit.
Here's the timeline that matters. Starting October 1, 2026, Microsoft has confirmed that all new Microsoft Advertising API features and enhancements will be available exclusively through the REST API. Your existing SOAP integrations won't instantly break, there's a six-month migration window after that date, but the SOAP API is fully scheduled for deprecation on January 31, 2027. If you're reading this after that date and your campaigns stopped reporting or your bulk uploads are silently failing, that's why.
Beyond the migration, I see a second cluster of issues: first-time Bing Ads API setup problems. Getting your developer token, OAuth credentials, and account hierarchy wired up correctly is not the most intuitive process Microsoft has ever designed. A missing developer token in the request header triggers a generic AuthenticationTokenExpired fault that tells you almost nothing useful. Selecting the wrong account ID, customer ID vs. account ID vs. manager account ID, causes silent data mismatches that only surface during reporting. These aren't edge cases; they're the first things every new integration trips over.
There's also a third category worth naming: organizations that are running hybrid setups, using the Microsoft Advertising web UI for day-to-day tasks but automating reporting or campaign optimization through the API. When the web UI works fine but the API calls fail, the problem is almost always credential scope or an API version mismatch, not anything wrong with the campaigns themselves.
I know this is frustrating, especially when your ad spend is running and you can't pull accurate performance data. The good news is that every one of these problems has a clear fix, and this guide walks through all of them in order. Browse all Microsoft fix guides →
The Bing Ads API, formally part of the Microsoft Advertising platform, is a pay-per-click advertising management interface that gives programmatic access to campaigns, bid management, audience targeting, and reporting. It's built for direct advertisers managing large ad spends, tools vendors building advertising platforms, agencies running campaigns across multiple client accounts, and aggregators who need to manage hundreds of advertiser relationships at scale. If any of those descriptions fit you, this guide is written for your exact situation.
The Quick Fix, Try This First
Before you go deep on diagnostics, run this checklist. About 60% of the Bing Ads API errors I see in developer forums get resolved by one of these four checks alone.
Step 1, Verify your developer token is in the header, not the body. Open your API request and confirm the DeveloperToken is passed as a SOAP header element (for legacy SOAP calls) or as a request header value (for REST calls). This is the single most common mistake on first-time Microsoft Advertising API setup. The token does not belong in the campaign data payload.
Step 2, Confirm you're targeting the correct API endpoint for your version. The Bing Ads API versioning matters. As of this writing, version 13 is current. If you inherited an older codebase pointing at a v12 or earlier endpoint, you will get either a hard 404 or a response schema mismatch that causes your parser to silently drop data. Update the base URL to the v13 endpoint.
Step 3, Refresh your OAuth access token. OAuth access tokens for the Microsoft Advertising API expire after 60 minutes. Refresh tokens last up to 90 days, but only if you've requested the offline_access scope during authorization. If your integration isn't automatically refreshing access tokens, any session longer than an hour will fail with InvalidCredentials. The fix is to implement a token refresh loop using your refresh token before expiry.
Step 4, Check account hierarchy: customer ID vs. account ID. In the Microsoft Advertising account structure, your customer ID (the top-level manager account) and your account ID (the individual advertiser account) are different numbers. Mixing these up in your API calls causes "account not found" errors that look identical to permission errors. Log into the Microsoft Advertising web UI, navigate to the account you want to manage, and pull both IDs from the URL, they're distinct numeric values.
If all four of these check out and you're still hitting errors, move to the step-by-step section below.
Every Bing Ads API integration, whether you're using the SDK or building raw HTTP calls, needs two things before a single campaign data request can succeed: an Azure Active Directory app registration and a Microsoft Advertising developer token. Skipping or mis-configuring either one produces authentication errors that look almost identical, which is why this step trips people up.
Head to the Microsoft Azure portal and create a new App Registration under your Azure AD tenant. During registration, add a Redirect URI, for server-side apps this is typically https://login.microsoftonline.com/common/oauth2/nativeclient. Note your Application (client) ID, you'll need this for every OAuth request.
Next, navigate to the Microsoft Advertising Developer Portal at https://developers.ads.microsoft.com. Sign in with the Microsoft account that has Super Admin access to your advertising account. Under the Account tab, you'll find your developer token listed. If you don't see one, you need to request production access, sandbox tokens work differently and will fail against production endpoints.
Once you have both values, your initial OAuth authorization URL should include these scopes: https://ads.microsoft.com/msads.manage offline_access. The offline_access scope is what grants you a refresh token; without it, you'll need to re-authorize every 60 minutes, which breaks any automated workflow.
When this step is done correctly, your first test call, a simple GetUser request, should return your user profile data with HTTP 200. If it returns AuthenticationTokenExpired immediately on a brand-new token, the developer token is likely copied incorrectly (watch for leading/trailing whitespace).
This is the most time-sensitive fix in this entire guide. If you have a working SOAP integration today and haven't started your Microsoft Advertising REST API migration, you need to start now. The deprecation isn't hypothetical, January 31, 2027 is the hard cutoff, and October 1, 2026 is when new features stop coming to SOAP entirely.
Microsoft has published both SDK and non-SDK migration guides. If you're using the official .NET, Java, Python, or PHP SDKs, the migration path is relatively clean, the SDK abstracts most of the transport layer differences. Update your SDK package to the latest version, then swap your service client initialization from the SOAP endpoint to the REST endpoint. Most data models remain consistent between versions, but response pagination and error object structures have changed in REST.
For non-SDK integrations (raw HTTP calls, custom SOAP clients), the migration is more involved. Key differences to account for:
# SOAP endpoint (legacy, do NOT use for new features after Oct 1, 2026)
https://campaign.api.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v13/CampaignManagementService.svc
# REST endpoint (current, all new features here)
https://campaign.api.bingads.microsoft.com/CampaignManagement/v13/CampaignsREST calls use standard HTTP verbs (GET, POST, PATCH, DELETE) rather than SOAP action headers. Your error handling code needs to be rewritten to parse JSON error responses rather than XML SOAP faults. If your integration complexity or scale makes a full migration before October 2026 genuinely unrealistic, contact Microsoft Advertising Support directly to discuss an extended migration plan, this is explicitly offered in their official documentation.
Once authentication is working, the next common failure point is campaign creation, specifically around network distribution settings and targeting. The Microsoft Advertising platform supports several network types for where your ads appear: the entire Microsoft Advertising Network, Microsoft sites and select traffic only, or partner-only traffic. Note that partner-only network type was deprecated as of July 2024. If your integration code was written before that date and still references the deprecated network type constant, your campaign creation calls will fail with a validation error.
Here's the fix, update your network type enum value in your campaign creation payload:
// Deprecated, do not use
"Network": "OwnedAndOperatedAndSyndicatedSearch" // partner-only variant
// Current valid values for CampaignManagement API v13
"Network": "OwnedAndOperatedOnly"
"Network": "SyndicatedSearchOnly" // select traffic
"Network": "OwnedAndOperatedAndSyndicatedSearch" // full network (this specific variant is still valid)For geo-targeting issues, like Pat's toy store example where you only want to reach customers within a specific radius, verify that your radius targeting is set in the correct unit (miles vs. kilometers) and that the center point coordinates are valid WGS84 latitude/longitude values. Invalid coordinate formats return a generic InvalidRequest rather than a specific coordinate error, which makes them hard to diagnose without checking your request payload carefully.
After a successful campaign creation call, you should get back a campaign ID in the response. Hold onto that, it's your key for every subsequent operation on that campaign.
Ad extensions are one of the most powerful Bing Ads API features, they let you attach additional information to your ads like deep links into your website, call buttons, location data, and promotional text. But they're also one of the trickiest to get right via the API because extensions operate at multiple account hierarchy levels simultaneously, and the association model is separate from the extension creation model.
The workflow has three distinct API operations that must happen in order. First, you create the extension entity using the appropriate Create operation (e.g., AddAdExtensions for SOAP, POST /AdExtensions for REST). This returns an extension ID. Second, you associate that extension ID with your campaign or ad group using SetAdExtensionsAssociations. Third, you verify the association status, not all extension types are eligible at all ad group levels, and a failed association doesn't throw an error, it just silently creates an inactive association.
Deep link extensions (Sitelink Extensions) are the most commonly requested type for driving customers to specific promotional or technical pages on your site. When creating them via API, the FinalUrls field is required in API v13, the older DestinationUrl field is deprecated and will be ignored. If your sitelinks are being created without destination URLs despite your code populating the field, check whether you're still using the legacy field name.
// Correct field name for API v13 Sitelink Extensions
"FinalUrls": ["https://yoursite.com/promo-page"]
// Deprecated, ignored in v13
"DestinationUrl": "https://yoursite.com/promo-page"Once extensions are correctly associated, verify in the Microsoft Advertising web UI under Ads & extensions > Extensions that the status shows "Active" rather than "Under review" or "Disapproved."
If your campaigns are running but your reporting API calls are returning empty datasets, partial data, or timeout errors, there are three specific things to check. The Microsoft Advertising Reporting API uses an asynchronous polling pattern, you submit a report request, get back a request ID, then poll until the report is ready for download. Developers who expect synchronous data back often misread an "InProgress" polling status as an error and abandon the request too early.
The correct polling flow looks like this:
# Step 1: Submit report request, returns ReportRequestId
POST /Reporting/v13/Reports
# Step 2: Poll status until Complete or Failed
GET /Reporting/v13/Reports/{ReportRequestId}
# Expected status progression: Pending → InProgress → Complete
# Step 3: Download the report from the URL in the Complete response
GET {ReportDownloadUrl}Report requests typically take between 30 seconds and 15 minutes depending on the date range and report type. Account-level and campaign-level performance reports for monitoring click and spend data are generally fast. Ad-level and keyword-level performance reports that track click-through rate and conversions across large accounts can take several minutes. Don't set your polling timeout shorter than 20 minutes for large accounts.
If your report keeps returning Failed status, the most common causes are: a date range that exceeds the allowed maximum (90 days for most report types), a combination of report columns that are incompatible with each other, or requesting data for accounts you don't have read permissions on. The error detail in the Failed response body will specify which of these applies, read it carefully rather than just logging the status code.
For ongoing campaign monitoring, the Ad Insight service gives you historical performance data and bid suggestions that help with keyword bid optimization. This is separate from the Reporting API and uses a different set of endpoints, don't confuse the two when building out your analytics pipeline.
Advanced Troubleshooting
Once you've ruled out the standard fixes, there are several less-obvious issues that show up in enterprise and agency setups that deserve their own section.
Agency and aggregator account hierarchy errors. If you're an agency managing campaigns for multiple clients, or an aggregator building a Bing Ads API application to manage hundreds of advertising accounts, the account hierarchy model works differently from a single-advertiser setup. You need to understand the distinction between the manager account (formerly known as the agency account), individual advertiser accounts, and how API permissions propagate through that hierarchy. Calling GetCustomersInfo returns the accounts your credentials can access, run this first to confirm you're seeing the accounts you expect. Missing accounts here almost always means your OAuth authorization was done under a Microsoft account that doesn't have the correct role assigned in the Microsoft Advertising Account Hierarchy.
Microsoft Shopping Campaigns product catalog sync failures. If you're running Microsoft Shopping Campaigns and your product ads are disappearing or showing outdated product information, the issue is typically in the catalog feed pipeline rather than the API itself. Product catalogs submitted through the Content API or via FTP/SFTP have their own validation rules. Feed submissions that fail validation don't always throw visible errors, they just don't update. Log into Microsoft Merchant Center directly, navigate to Catalog management > Feed status, and look for item-level rejection reasons. Common rejections include missing availability values, price format mismatches, and image URL accessibility failures.
Rate limiting and throttling. The Bing Ads API enforces per-credential rate limits on both the number of API calls per minute and the number of concurrent requests. When you hit these limits, you'll receive HTTP 429 responses or SOAP faults with error code 117 (CallRateExceeded) or 207 (ConcurrentRequestOverLimit). The fix is to implement exponential backoff with jitter in your retry logic, not a fixed retry interval. The standard pattern:
retry_delay = min(base_delay * (2 ** attempt) + random_jitter, max_delay)
# Base: 1 second, Max: 60 seconds, Jitter: random(0, 1)Language and locale targeting mismatches. Ads created with German language targeting will be eligible to show not just in Germany, but also in Austria and Switzerland. If your campaign performance data shows traffic from unexpected countries, check your language settings first before assuming a targeting bug. This is working as designed per the Microsoft Advertising ad distribution model, language targeting is separate from geo-targeting, and both apply simultaneously.
Keyword bid data vs. Ad Insight bid suggestions. The Ad Insight service returns bid suggestions based on historical performance data and demographic signals. These suggestions are informational, not automatically applied, your campaigns won't change bids unless your code explicitly writes back to the Campaign Management API with updated bid values. I've seen integrations where developers assumed the Ad Insight data was being applied automatically and were puzzled why campaign performance wasn't improving despite "optimization" calls running successfully.
InvalidGrant errors that refresh token rotation doesn't resolve; you're seeing data discrepancies between the Reporting API output and the web UI figures that persist across multiple report types; or your account has been flagged and API access is restricted. For these cases, open a support ticket through the Microsoft Advertising portal rather than the general Microsoft Support queue, advertising-specific support has access to account-level diagnostic tools that general support does not.
Prevention & Best Practices
Fixing the immediate problem is only half the job. Here's what separates integrations that stay stable for years from ones that need constant firefighting.
Subscribe to the Microsoft Advertising developer newsletter and Release Notes. Microsoft publishes Release Notes and a Migration Guide that cover every breaking change and deprecation announcement before it happens. You can sign up through the News tab of the Developer Portal. The SOAP-to-REST deprecation timeline, the July 2024 partner network type removal, the v13 field name changes for ad extensions, every one of these was announced months in advance in Release Notes. Teams that were subscribed had zero surprises; teams that weren't got blindsided.
Tag your Microsoft Q&A forum questions correctly. When you post a question to the Microsoft Q&A forum for developer community support, always tag it with advertising-api. This is the specific tag that Microsoft engineering monitors and responds to. Untagged questions often go unanswered for weeks. This sounds minor but it's the difference between getting an authoritative answer in hours versus waiting for a community response that may or may not be accurate.
Build version abstraction into your integration from day one. Hard-coding API endpoint URLs and version numbers directly into business logic is the single biggest reason API migrations are painful. Abstract your endpoint base URLs and API version constants into a configuration layer. When v14 eventually ships, you update one config value instead of hunting through hundreds of service calls.
Test in sandbox before pushing to production. Microsoft Advertising provides a sandbox environment specifically for Bing Ads API development testing. Run all schema changes, new feature integrations, and migration work against sandbox first. Sandbox uses different credentials from production but mirrors the production API behavior closely enough to catch most issues.
- Enable the
offline_accessOAuth scope on all app registrations so refresh tokens don't expire after 60 minutes and break overnight automation jobs - Store your developer token and client credentials in Azure Key Vault or equivalent secrets management, never in source code or environment files committed to version control
- Set up alerting on your reporting pipeline output row counts, a sudden drop to zero rows is almost always a credential or API version issue, not a real performance collapse
- Run
GetUseras a health check call at the start of every session to validate credentials before attempting write operations on campaigns
Frequently Asked Questions
Who should actually use the Bing Ads API, is it worth the setup complexity?
The Bing Ads API is genuinely worth it if you're a direct advertiser who wants to connect your ad spend data to internal inventory or conversion tracking systems, a tools vendor building advertising management software, an agency running campaigns across multiple client accounts, or an aggregator managing hundreds of advertisers at scale. If you're running a handful of campaigns with straightforward settings and you're comfortable in the Microsoft Advertising web UI, the API overhead probably isn't justified. But the moment you hit a scale or automation need that the UI can't handle, bulk keyword uploads, programmatic bid adjustments, scheduled performance reporting, the API pays for itself immediately.
Where will my Microsoft Advertising search ads actually appear?
Your search ads can appear across the Microsoft Advertising Network, which includes Bing search results pages worldwide along with Microsoft partner sites. The specific distribution depends on your campaign network setting, you can target the full Microsoft Advertising Network, Microsoft owned-and-operated properties only, or select partner traffic. One thing that surprises people: language targeting affects distribution geography. If you're running ads in German, they're eligible to show not just in Germany but also in Austria and Switzerland. For a complete list of countries and regions where Microsoft Advertising serves ads, check the "Where does Microsoft Advertising show your ads?" resource in the official help documentation.
What are ad extensions and how do I add them through the API?
Ad extensions are additional pieces of information you attach to your ads, things like deep links to specific pages on your site (Sitelink Extensions), phone numbers (Call Extensions), location information, and promotional text. They make your ads more visually prominent and give customers more ways to engage. Through the Bing Ads API, you add them in two steps: first create the extension entity using AddAdExtensions (SOAP) or the equivalent REST endpoint, which returns an extension ID; then associate that ID with your specific campaign or ad group using SetAdExtensionsAssociations. Always verify the association status after creation, a failed association doesn't throw an error, it just creates an inactive link that you'll only catch if you check the status explicitly.
Where do I go when I can't find the answer to a Bing Ads API question?
Your first stop should be the Microsoft Q&A forum, it's the official community support channel for Bing Ads API developers, and Microsoft engineers actively monitor it and respond to questions. The critical thing: tag your question with advertising-api or it won't get routed to the right team. If your issue involves sensitive account details, personal information, or you're not finding a solution through the forum, contact Microsoft Advertising Support directly through the advertising portal. When you do, include your customer ID, the exact API operation that failed, the complete error response, and the timestamp, this information dramatically speeds up resolution.
How do I stay on top of Bing Ads API changes and deprecations?
Sign up for the monthly developer newsletter through the News tab of the Microsoft Advertising Developer Portal, it aggregates all blog announcements and release notes in one place. The Release Notes page and Migration Guide are your authoritative sources for breaking changes; every major API change, including the current SOAP-to-REST deprecation, is announced there first. The SOAP deprecation deadline of January 31, 2027 with a feature freeze on October 1, 2026 has been documented in Release Notes for months, teams that subscribe to these updates have time to plan; teams that don't get surprised at the worst possible moment.
My Bing Ads API SOAP integration is working fine, do I really need to migrate to REST?
Yes, and the timeline is non-negotiable. October 1, 2026 is when all new Microsoft Advertising API features stop coming to SOAP. January 31, 2027 is full SOAP deprecation. If your SOAP integration is working today, it will continue working through the six-month migration window after October 2026, but you'll be frozen on current functionality with no new features, and then the entire integration will stop working when SOAP is turned off. The recommended path is to migrate to REST before October 1, 2026 using the SDK migration guide (if you're using the official SDKs) or the non-SDK guide (for custom integrations). If your scale or complexity genuinely makes that timeline impossible, contact Microsoft Advertising Support, they offer extended migration plan discussions for complex cases.