# Microsoft Ads

Create Bing search campaigns with responsive search ads and keywords, pause or rebudget them, and read their daily metrics on a microsoftads account.

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Create a search campaign with `POST /v1/ads/create` on a `microsoftads` account (ad platform value `microsoft`, alias `microsoftads`). Campaigns, ad groups and ads made in Microsoft Advertising sync in too.

## Quick reference

| Property | Value |
|----------|-------|
| Hierarchy | Campaign > Ad Group > Ad, created in one call |
| Campaign type | Search only |
| Goal (`goal`) | `traffic` |
| Ad format | Responsive search ad: 3 to 15 headlines of up to 30 characters, 2 to 4 descriptions of up to 90 characters |
| Keywords | Optional on create, `EXACT`, `PHRASE` or `BROAD` (the default) |
| Budget | `daily` only, set on the campaign |
| Bidding | Maximize Clicks; bid fields are not available |
| Targeting | Countries, required on every create |
| Edits after creation | Status at each level and the daily budget |
| Delete | Deletes on Microsoft Advertising |
| Performance sync | Daily impressions, clicks, spend, conversions and revenue |
| Sign in | Microsoft account, or Google for a Microsoft Advertising login made with Google |

## Before you start

You need a user with access to at least one Microsoft Advertising ad account, set up at ads.microsoft.com with a payment method.

Microsoft Ads is a standalone connection: it has its own OAuth and its own `accountId`, with no posting account behind it.

## Connect

Call `GET /v1/connect/microsoftads/ads` with the `profileId` the connection belongs to ([Connect ads](/connect/connect-ads)).

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
import Zernio from '@zernio/node';

const zernio = new Zernio();

const { data: start } = await zernio.connect.connectAds({
  path: { platform: 'microsoftads' },
  query: { profileId: '66a1f0c2a4b9d3e8f1a2b3c4', redirect_url: 'https://your-app.com/cb' }
});

console.log(start.authUrl ?? start.accountId);
```
</Tab>
<Tab value="Python">
```python
from zernio import Zernio

client = Zernio()

start = client.connect.connect_ads(
    platform="microsoftads",
    profile_id="66a1f0c2a4b9d3e8f1a2b3c4",
    redirect_url="https://your-app.com/cb",
)

print(start.get("authUrl") or start.get("accountId"))
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/connect/microsoftads/ads?profileId=66a1f0c2a4b9d3e8f1a2b3c4&redirect_url=https://your-app.com/cb" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```
</Tab>
</Tabs>

Send the user to the `authUrl` the call returns. A user who signs in to ads.microsoft.com with a Google account adds `identityProvider=google`, and consent then runs on Google.

**Choosing ad accounts.** After consent, Zernio syncs every Microsoft Advertising ad account the user can reach.

Pass `adAccountId` (or `adAccountIds`) on the connect call to limit sync to some of them. The id is the numeric account Id, not the account number.

Call the connect endpoint again once the browser lands on your `redirect_url`: it answers with `alreadyConnected: true` and the `accountId` every sample in this section uses.

## Common errors

| Error | Cause | Fix |
|-------|-------|-----|
| `error=microsoft_ads_unknown_user` | The account that signed in is not a Microsoft Advertising user | Sign in with the account used at ads.microsoft.com, adding `identityProvider=google` for a Google login. |
| `error=microsoft_ads_no_ad_accounts` | The user reaches no Microsoft Advertising ad account | Create one at ads.microsoft.com, or sign in with a user that has access. |
| `error=microsoft_ads_scope_not_granted` | The user declined the Microsoft Advertising permission | Connect again and accept it. |

## In this section

<PlatformPages platform="microsoft-ads" />

## Related

- [Connect ads](/connect/connect-ads): every parameter of the connect call.
- [Create standalone ad](/ad-campaigns/create-standalone-ad): every field of the create request.
- [Get campaign tree](/ad-campaigns/get-ad-tree): campaigns, ad groups and ads with their metrics.
- [Get ad analytics](/ad-insights/get-ad-analytics): metrics, date ranges and rollups.