API tool design document
AdSoups is designed as a private review-and-apply workflow for Google Ads operations.
This document summarizes the tool design for Google Ads API review: actors, account scope, data flow, API services, review controls, and operational safeguards.
1. System Overview
AdSoups is a private internal advertising operations platform. It helps our team manage Google Ads accounts that our organization owns or is authorized to manage. The platform is not a public SaaS product, does not allow public signup, and is not offered as a campaign management service to unrelated advertisers.
The system combines reporting, review queues, and controlled write workflows. Operators use retrieved Google Ads data to evaluate account health, propose campaign updates, and apply approved changes through Google Ads API services.
2. Actors and Permissions
- Internal operator: reviews account data and approves campaign, keyword, negative keyword, bid, or status changes.
- Operations manager: reviews higher-impact account changes and monitors operational results.
- System process: performs scoped read and write API calls after account and workflow validation.
3. Data Flow
- AdSoups authenticates with authorized Google Ads credentials.
- The platform confirms linked account scope through manager-client account data.
- Reporting jobs retrieve campaign, ad group, keyword, search term, and performance metrics.
- Operators review proposed changes in an internal queue.
- Approved changes are sent through scoped Google Ads API mutate services.
- Operational results and failures are logged for review and troubleshooting.
4. API Boundary
AdSoups uses the Google Ads API only for advertising operations inside authorized accounts. The tool does not request Google Ads API access for unrelated account data, public user profiles, or external data products.
GoogleAdsService.Search
GoogleAdsService.SearchStream
CustomerClientService
CampaignBudgetService.MutateCampaignBudgets
CampaignService.MutateCampaigns
CampaignCriterionService.MutateCampaignCriteria
AdGroupService.MutateAdGroups
AdGroupCriterionService.MutateAdGroupCriteria
AdGroupAdService.MutateAdGroupAds
AssetService.MutateAssets
CampaignAssetService.MutateCampaignAssets
KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics
5. Review Controls
- Read operations are used for reporting, diagnostics, and review preparation.
- Write operations are constrained to campaign management tasks and authorized accounts.
- Operators review changes before production mutations are sent.
- Budget, CPC, status, keyword, and negative keyword updates follow internal operating limits.
- API errors are reviewed before retrying broad update batches.
6. Expected Usage
AdSoups is requesting Basic Access because the tool needs production account access for internal Google Ads campaign operations. Expected API usage is below 15,000 operations per day.
Usage patterns are primarily scheduled reporting, operator-triggered campaign creation, keyword review, negative keyword updates, CPC ceiling changes, and campaign status maintenance.
7. Data Protection
Google Ads data is used only for internal advertising operations and is not sold or transferred for unrelated purposes. OAuth credentials and refresh tokens are treated as confidential operational credentials and are not exposed in the public website or application review materials.
For additional detail, see Security, Data Handling, and the Privacy Policy.