Google Ads API · Tool Design Document
SynthBid — Internal Google Ads Operations Workspace
Design and architecture of the internal tool through which our team manages Search campaigns in the Google Ads accounts we own, with a human review checkpoint on every write.
Version 1.0Company: SynthBidSite: https://synthbid.comUse: Internal · own accounts
1Overview & purpose
SynthBid is an internal tool operated by our own authorized advertising team. Its single purpose is to plan, review and apply changes to Search campaigns in the Google Ads accounts that we own and that are linked under our own manager (MCC) account. It is not a product offered, sold or exposed to third-party advertisers, and it does not manage accounts belonging to other companies.
The tool exists because managing keywords, responsive search ads, bids and negative keywords by hand across many of our own accounts is slow and error-prone. SynthBid automates the mechanical work through the Google Ads API while keeping a named operator in control of every change that reaches a live account.
2Users & access model
- Internal users only. The tool is used exclusively by named, authorized operators on our team. There is no public sign-up, no external tenant, and no client-facing access.
- Single developer token on our manager account, used only against our own linked accounts.
- Least privilege. Operators authenticate via Google OAuth 2.0; the tool acts within the scope of our own accounts and nothing else.
3System architecture
SynthBid is organised as a pipeline. Drafts are assembled automatically, but no write is sent to a live account until an operator approves it in the review queue.
Intakebrief & product data
→
Draft buildercampaign / kw / RSA
→
Review queueoperator approves
→
Apply engineAds API mutate
→
ReportingGAQL read-back
- Intake — an operator sets the brief: which of our accounts, which products, target terms and budget guidance.
- Draft builder — assembles the proposed campaign structure, keywords and ad copy. Nothing is written at this stage.
- Review queue — every proposed create, update and removal is listed as a discrete item. An operator approves, edits or rejects each one.
- Apply engine — only approved items are sent to the Google Ads API as targeted mutate operations.
- Reporting — performance is read back via GAQL to inform the next cycle.
4How SynthBid uses the Google Ads API
All access is through the official Google Ads API. The surface is grouped into three categories.
| Category | What we do | Services / resources |
|---|
| Creation | Build Search campaigns: campaign + budget, ad groups, keywords (exact/phrase/broad), responsive search ads | CampaignService, CampaignBudgetService, AdGroupService, AdGroupCriterionService, AdGroupAdService |
| Management | Adjust CPC bids, add negative keywords, pause/enable keywords & campaigns, update ad-group structure | AdGroupCriterionService, CampaignCriterionService, CampaignService (mutate + FieldMask) |
| Reporting | Read search terms, keyword & campaign metrics, impression share, responsive-ad strength & status | GoogleAdsService.SearchStream over search_term_view, keyword_view, campaign, ad_group_ad |
Write operations use targeted mutate calls with a field mask so only the intended field changes. Reporting reads never modify the account. The tool de-duplicates against existing criteria before adding keywords or negatives, keeping operations idempotent.
5Human-review workflow
This is the core control of the design: no create, update or removal reaches a live account without a named operator approving that specific item.
- Each proposed change is a queue item recording the target account, the change, and the underlying API call.
- An operator approves, edits or rejects it. Only approved items are sent to the Apply engine.
- Every applied operation is logged — what changed, on which account, approved by whom — so actions can be traced and reversed.
There is no unattended, fully-automatic write loop. The API performs the mechanical work; a person authorises every change that goes live.
6Authentication & security
- OAuth 2.0 with a single developer token held only in our operating environment; never embedded in client code or exposed publicly. Refresh tokens are revocable at any time.
- Scope is restricted to our own manager account and its linked sub-accounts.
- No end-user personal data is collected, stored or processed. The tool handles only our own account configuration and performance metrics.
- Retention — operational reports are working artifacts, rotated out when no longer useful; account data is never sold, shared or transferred to third parties.
7Compliance & operating limits
- SynthBid operates only on Google Ads accounts we own, linked under our own manager account.
- It is an internal tool, not resold or made available to outside advertisers.
- The tool stays within Google Ads API quota limits and the Google Ads policies, and keeps the API contact email current to receive service notices.