Google Ads
Create Search, Display, Performance Max and Demand Gen campaigns, mine keywords, upload Customer Match lists, send conversions, manage conversion goals, labels and MCC links, act on Google's recommendations, and query GAQL on a googleads account.
Create Google Search, Display, Performance Max and Demand Gen campaigns with POST /v1/ads/create, read keywords and run Keyword Planner, choose what Google bids on with conversion goals, organize accounts with labels and manager (MCC) links, apply or dismiss Google's optimization recommendations, and query anything Google's reporting can answer with the Insights endpoints, all on a googleads account.
Quick reference
| Property | Value |
|---|---|
| Hierarchy | Campaign > Ad Group > Ad (created in one call) |
| Campaign types (create) | Search (Responsive Search Ads), Display (Responsive Display Ads), Performance Max (asset groups), Demand Gen (image, video and carousel ads) |
| Goals (`goal`) | engagement, traffic, awareness. video_views and conversion goals are rejected at create with a 422 |
| Keyword targeting | Broad, phrase, exact; synced keyword list plus Keyword Planner |
| Insights | Rolled-up metrics on /ads/tree plus raw GAQL passthrough (see Insights and GAQL) |
| Discovered campaigns | All types sync into /ads/tree with metrics, including Performance Max |
| Audiences | Customer Match (create plus member upload) |
| Conversions API | Data Manager API (click ids plus Enhanced Conversions for Leads), EEA/UK consent |
| Conversion goals | Account, campaign and custom goals; primary or secondary actions |
| Recommendations | List with estimated impact, apply (suggested or custom values) and dismiss, up to 100 per call |
| Account management | Manager (MCC) hierarchy, manager-link invitations, labels on campaigns, ad groups, ads and keywords |
| URL tracking tags | Campaign-level trackingUrlTemplate plus finalUrlSuffix (read and update) |
| Search ad text | 15 headlines (30 characters) and 4 descriptions (90 characters) |
| Display images | Landscape 1.91:1 and square 1:1 both required, JPEG or PNG, 5120 KB |
Before you start
Google Ads uses a dedicated OAuth connection, separate from YouTube and Google Business Profile. You need a Google Ads account (the customer id, from List ad accounts); accounts under an MCC manager work too. There is no MCC or Standard Access application on your side: Zernio operates under its own approved developer token. To see how the accounts behind a connection nest under managers, read the manager hierarchy.
Display campaigns need 2 images. Google's Responsive Display Ads require both a landscape (1.91:1) and a square (1:1) marketing image; sending only one is rejected upstream with NOT_ENOUGH_SQUARE_MARKETING_IMAGE_ASSET.
Zernio's developer token holds Standard access, so there is no daily operations cap. User-driven live calls (GAQL, search terms, Keyword Planner, keyword and other writes) pass a per-user burst limit of 15 requests a minute; see Quotas and the ops budget.
Connect
Call GET /v1/connect/googleads/ads with profileId (Connect ads). Google Ads is a standalone connection with no parent posting account, so the response always carries an authUrl the first time; send the user there, as in the connecting accounts guide. Once connected, the same call returns alreadyConnected: true with the accountId.
curl "https://zernio.com/api/v1/connect/googleads/ads?profileId=66a1f0c2a4b9d3e8f1a2b3c4&redirect_url=https://myapp.com/callback" \
-H "Authorization: Bearer $ZERNIO_API_KEY"Response (200), the first time:
{
"authUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...",
"state": "..."
}Response (200), once the profile already has a googleads account:
{
"alreadyConnected": true,
"accountId": "66b2e19d8c3f5a7e9d0b1c2d",
"platform": "googleads",
"username": "Acme Search",
"displayName": "Google Ads (Acme Search)"
}Branch on alreadyConnected: when it is there, skip the redirect and use accountId. The two shapes never arrive together.
The connection requests 2 scopes (scopes):
| Scope | What it enables |
|---|---|
https://www.googleapis.com/auth/adwords | Full Google Ads API access: campaigns, ad groups, ads, reporting, conversions |
https://www.googleapis.com/auth/datamanager | Data Manager API: Customer Match audience uploads |
Zernio's adSetId is the Google ad group id (on Meta the same field is an ad set, on LinkedIn a campaign); adAccountId is the customer id without dashes.
In this section
Create ads
Search, Display and Performance Max campaigns in one call, RSA text edits and pinning, and sitelink/callout/snippet assets
Performance Max
Asset groups: read with ad strength, add, edit, swap assets, and retail product targeting
Demand Gen
Image, video and carousel ads on YouTube, Discover and Gmail, with channels and audiences
Keywords
Synced keyword criteria and the Keyword Planner
Customer Match
CRM-list audiences with hashed member upload
Insights and GAQL
Rolled-up metrics and raw GAQL queries
Conversions
Offline and enhanced conversions through the Data Manager API, and the conversion goals Google bids on
URL tracking tags
Campaign tracking templates and final URL suffixes
Recommendations
Google's optimization suggestions with estimated impact: apply or dismiss them
Accounts and labels
Manager (MCC) hierarchy, manager-link invitations, and labels
Limits and errors
Quotas, what you cannot do, and Google's recurring errors
Common errors
Connecting is where this page's own errors live; the per-job pages carry the rest, and Limits and errors collects the recurring ones.
| Error | Cause | Fix |
|---|---|---|
Redirect with error=google_ads_auth_failed | The user declined the Google consent screen, or the token exchange failed | Restart the connect flow. Google's own string arrives in error_message. |
Redirect with error=google_ads_quota_exhausted | Google's shared API quota ran out during the flow | Retry the connect flow later. |
429 on List ad accounts | Google throttled the shared token or your account, so the call fails rather than returning an empty list | Retry after details.resetsAt (Quotas and the ops budget). |
403 with code ads_addon_required | The team is on a legacy plan that does not include ads access | Move the team to usage-based billing, where every account includes ads (Pricing). |
Error handling covers the envelope and the stable codes.
Related
- Create standalone ad: campaign, ad group and ad in one call.
- List Search keywords: synced keyword criteria.
- Keyword ideas and Historical metrics.
- Query ad insights: raw GAQL passthrough.
- Send conversions: Data Manager events.
- List Google Ads recommendations and Apply Google Ads recommendations.
- Get manager account hierarchy and Create a Google Ads label.
Enums, Limits & Error Codes
Look up the Meta ads enums, media limits, unsupported operations and Meta error subcodes that the rest of this section links to.
Create Ads
Create a Google Search, Display or Performance Max campaign in one POST /v1/ads/create call, edit RSA headlines and descriptions with pinning, and manage sitelink, callout and structured-snippet assets.