Google Ads

A googleads connection lets you build Google Search, Display, Performance Max and Demand Gen campaigns, run Keyword Planner, upload Customer Match lists, choose conversion goals, act on Google's recommendations and query anything Google reporting can answer. Campaigns of every type, including Shopping and Video ones made in Google Ads, sync into the campaign tree with metrics.

#Connect

Call GET /v1/connect/googleads/ads with the profileId. Google Ads is its own OAuth connection, separate from YouTube and Google Business Profile. The first call returns an authUrl; once the user consents, the same call returns alreadyConnected: true and the accountId.

You do not need a Google Ads developer token or an API access application of your own. Accounts under a manager (MCC) account work too.

GET /v1/ads/accounts?accountId=... lists the customer ids the connection reaches. Use the id without dashes as adAccountId. GET /v1/ads/accounts/hierarchy shows how the accounts nest under managers.

#Create a Search campaign

campaignType picks the campaign: search, display, pmax or demand_gen. A Search create needs the ad copy and keywords.

curl -X POST https://api.pozy.ai/v1/ads/create \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: search-plumbing-austin" \
  -d '{
    "accountId": "66b2e19d8c3f5a7e9d0b1c3e",
    "adAccountId": "1234567890",
    "campaignType": "search",
    "name": "Emergency plumbing - Austin",
    "goal": "traffic",
    "budgetAmount": 50,
    "budgetType": "daily",
    "headline": "24/7 Emergency Plumber",
    "body": "Licensed plumbers at your door in 60 minutes. Upfront prices.",
    "additionalHeadlines": [
      "Same-Day Repairs",
      { "text": "Austin Plumbing Pros", "pinnedField": "HEADLINE_1" }
    ],
    "additionalDescriptions": ["No call-out fee before 8pm. Book online in two minutes."],
    "linkUrl": "https://plumbing.example.com/austin",
    "keywords": [
      "emergency plumber austin",
      { "text": "burst pipe repair", "matchType": "phrase" }
    ],
    "countries": ["US"]
  }'

const res = await fetch("https://api.pozy.ai/v1/ads/create", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Idempotency-Key": "search-plumbing-austin",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    accountId: "66b2e19d8c3f5a7e9d0b1c3e",
    adAccountId: "1234567890",
    campaignType: "search",
    name: "Emergency plumbing - Austin",
    goal: "traffic",
    budgetAmount: 50,
    budgetType: "daily",
    headline: "24/7 Emergency Plumber",
    body: "Licensed plumbers at your door in 60 minutes. Upfront prices.",
    additionalHeadlines: ["Same-Day Repairs", { text: "Austin Plumbing Pros", pinnedField: "HEADLINE_1" }],
    additionalDescriptions: ["No call-out fee before 8pm. Book online in two minutes."],
    linkUrl: "https://plumbing.example.com/austin",
    keywords: ["emergency plumber austin", { text: "burst pipe repair", matchType: "phrase" }],
    countries: ["US"],
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.ad.platformAdSetId); // the ad group id

import os, requests

resp = requests.post(
    "https://api.pozy.ai/v1/ads/create",
    headers={
        "Authorization": f"Bearer {os.environ['POZY_API_KEY']}",
        "Idempotency-Key": "search-plumbing-austin",
    },
    json={
        "accountId": "66b2e19d8c3f5a7e9d0b1c3e",
        "adAccountId": "1234567890",
        "campaignType": "search",
        "name": "Emergency plumbing - Austin",
        "goal": "traffic",
        "budgetAmount": 50,
        "budgetType": "daily",
        "headline": "24/7 Emergency Plumber",
        "body": "Licensed plumbers at your door in 60 minutes. Upfront prices.",
        "additionalHeadlines": ["Same-Day Repairs", {"text": "Austin Plumbing Pros", "pinnedField": "HEADLINE_1"}],
        "additionalDescriptions": ["No call-out fee before 8pm. Book online in two minutes."],
        "linkUrl": "https://plumbing.example.com/austin",
        "keywords": ["emergency plumber austin", {"text": "burst pipe repair", "matchType": "phrase"}],
        "countries": ["US"],
    },
    timeout=60,
)
resp.raise_for_status()
print(resp.json()["ad"]["_id"])

Rules for the Search create:

• goal is engagement, traffic or awareness. video_views and conversion goals return 422.
• keywords are broad match unless you send { text, matchType } with exact, phrase or broad. Up to 1,000 per call, 80 characters each. negativeKeywords and campaignNegativeKeywords take the same shape.
• The responsive search ad ends up with 3 to 15 headlines (30 characters each) and 2 to 4 descriptions (90 characters each) after headline, body, additionalHeadlines and additionalDescriptions are combined. pinnedField fixes one to HEADLINE_1, HEADLINE_2, HEADLINE_3, DESCRIPTION_1 or DESCRIPTION_2.
• sitelinks, callouts and structuredSnippets attach assets to the new campaign in the same call.
• Every Google create starts as pending_review. Later syncs move it to active, rejected, paused, completed or cancelled.
• validateOnly: true checks the whole request against Google without creating anything.

#Display campaigns

Send campaignType: "display", businessName (25 characters) and both images:

{
  "campaignType": "display",
  "businessName": "Austin Plumbing",
  "headline": "Fast, fair plumbing",
  "longHeadline": "Licensed Austin plumbers, same-day repairs, upfront prices",
  "body": "Book online in two minutes.",
  "images": {
    "landscape": "https://cdn.example.com/plumbing-1200x628.jpg",
    "square": "https://cdn.example.com/plumbing-1080.jpg"
  }
}

Google requires a landscape (1.91:1) and a square (1:1) image, JPEG or PNG up to 5,120 KB. Sending only one fails with NOT_ENOUGH_SQUARE_MARKETING_IMAGE_ASSET. longHeadline defaults to headline.

#Performance Max

Send campaignType: "pmax" with an assetGroup. The campaign, its budget and the asset group with every asset are created in one atomic request.

{
  "campaignType": "pmax",
  "budgetAmount": 80,
  "budgetType": "daily",
  "assetGroup": {
    "name": "All services",
    "finalUrl": "https://plumbing.example.com",
    "businessName": "Austin Plumbing",
    "headlines": ["Emergency plumber", "Same-day repairs", "Upfront prices"],
    "longHeadline": "Licensed Austin plumbers at your door in 60 minutes",
    "descriptions": ["Book online in two minutes.", "No call-out fee before 8pm."],
    "images": {
      "landscape": ["https://cdn.example.com/pm-1200x628.jpg"],
      "square": ["https://cdn.example.com/pm-1080.jpg"],
      "logo": ["https://cdn.example.com/logo-512.png"]
    },
    "youtubeVideoId": "dQw4w9WgXcQ"
  }
}

After launch, manage asset groups under /v1/ads/campaigns/{campaignId}/asset-groups: list them with Google's ad strength (POOR to EXCELLENT), add groups, edit URLs and status, link and unlink assets in one atomic request, and replace the retail listing-group tree for Merchant Center campaigns. An asset group's status is separate from its campaign's: an enabled group in a paused campaign spends nothing.

#Demand Gen

Demand Gen serves on YouTube (in-stream, in-feed, Shorts), Discover, Gmail and display partners. Send campaignType: "demand_gen" with a demandGen object. The format follows from what you send:

To restrict where a Demand Gen campaign shows, list channels in demandGen.channels, choosing from youtube_in_stream, youtube_in_feed, youtube_shorts, discover, gmail and display. Describe the audience in demandGen.audience (user lists, interests, custom audiences, age ranges, genders), or point demandGen.audienceId at one you already have. These campaigns are created paused, and their locations and languages are set per ad group. The same create endpoint adds more: an ad group with existingCampaignId, an ad with adSetId.

#Bidding and budgets

bidStrategy uses the same names as the other networks and maps to Google's strategies:

Other ways to bid, in place of bidStrategy: a shared portfolio strategy through portfolioBidStrategyId (ids come from GET /v1/ads/bid-strategies), targetImpressionShare for Search, and manualCpc: { maxCpc } for Search or Display. Use networkSettings to include or exclude search partners and the display network.

Google budgets are daily. PUT /v1/ads/campaigns/{campaignId} with budget changes one. A shared budget changes every campaign on it, so the call returns 409 unless you send allowSharedBudgetUpdate: true. sharedBudgetId moves a campaign onto a budget from GET /v1/ads/shared-budgets.

#Keywords

keywordId takes Pozy's id or Google's {adSetId}~{criterionId}. A bare criterion id is rejected because it is only unique inside its ad group. The synced keyword list refreshes about once a day, so keywords added in Google Ads can take a day to appear. Keyword Planner rows come back in Google's raw shape: counters are strings and bids are micros.

#Assets, labels and accounts

• Sitelinks, callouts and structured snippets exist at account, campaign and ad group level. Create and attach them with the /v1/ads/accounts/sitelinks family, POST /v1/ads/campaigns/{campaignId}/assets or POST /v1/ads/ad-sets/{adSetId}/assets. Updating an asset edits it everywhere it is attached. Removing only detaches it, because Google assets cannot be deleted.
• Labels organize campaigns, ad groups, ads and keywords: POST /v1/ads/labels, then attach with POST /v1/ads/labels/{labelId}/assignments.
• Manager accounts: create a client account under a manager with POST /v1/ads/accounts, bill it to the manager's monthly invoicing with POST /v1/ads/accounts/billing, invite a client account to a manager with POST /v1/ads/accounts/manager-links, and accept, decline or end links with PATCH. Ads do not serve until the account has billing.
• User access: invite people to an ad account by email with POST /v1/ads/accounts/user-invitations.
• Conversion goals: read and change which conversion actions a campaign bids on with /v1/ads/campaigns/{campaignId}/conversion-goals. Sending conversions is covered in Conversions.

#Recommendations

GET /v1/ads/recommendations lists Google's suggestions (budgets, bidding targets, keywords, assets) with impact.base and impact.potential estimates. Filter by campaignId or types. POST /v1/ads/recommendations/apply applies up to 100, with Google's suggested values or your own in parameters. POST /v1/ads/recommendations/dismiss stops Google suggesting them.

#Targeting

Locations, languages, age, gender, the top_10 income tier, interests and Customer Match lists. Google has no city radius: use a customLocations pin instead. locationTargetingType decides whether locations reach people who are there (presence) or also people interested in them (presence_or_interest, Google's default). PUT /v1/ads/campaigns/{campaignId}/targeting changes a live campaign's devices, locations, exclusions and languages. Full rules are in Targeting.

#Reporting

With GET /v1/ads/insights you can run your own read-only GAQL SELECT. Rows come back exactly as Google returns them, up to 10,000 a page; pass paging.nextPageToken as pageToken for the next one. Selecting segments.date requires a bounded date range in the query, for example DURING LAST_30_DAYS.

curl -G https://api.pozy.ai/v1/ads/insights \
  -H "Authorization: Bearer $POZY_API_KEY" \
  --data-urlencode "accountId=66b2e19d8c3f5a7e9d0b1c3e" \
  --data-urlencode "query=SELECT campaign.name, metrics.cost_micros, metrics.conversions FROM campaign WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.cost_micros DESC"

Impression share fields are ratios: 0.42 is 42%. Pozy imports the last 90 days of metrics when an account connects. For older days, query GAQL directly.

#Limits and errors

Live calls to Google (GAQL, search terms, Keyword Planner, keyword and asset writes, recommendations) share a burst limit of 15 requests a minute per user and 120 across your accounts, on top of your Pozy rate limit. Cached reads (asset groups, recommendations, shared lists) carry cachedAt and stale: stale: true means Google throttled the request and you are reading the last good copy.

Redirects after consent can carry error=google_ads_auth_failed (the user declined) or error=google_ads_quota_exhausted (retry later).

#Endpoints

Google-only endpoints:

Assets and labels:

The shared campaign, ad and reporting endpoints are listed on the ads overview.