API tool design document
AdSoups is designed to support reviewed Search campaigns for our content business.
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 publishes practical paid search operations guides for campaign planning, keyword research, reporting, budget pacing, landing page checks, and daily account maintenance. We use Google Ads to promote our own guide content to relevant audiences and measure qualified traffic.
The internal AdSoups operations tool supports this advertising work. It combines reporting, review queues, and controlled write workflows for Google Ads accounts that our organization owns under its manager account. 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 our own accounts, including Search campaigns that promote AdSoups guide content. The tool does not request Google Ads API access for unrelated account data, public user profiles, client accounts, 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 in AdSoups-owned 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 that support our content promotion in AdSoups-owned accounts. 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, reporting, campaign review, guide promotion analysis, and troubleshooting. It 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 documentation pages.
For additional detail, see Security, Data Handling, and the Privacy Policy.