Integration and API Spec

Integration and API Spec

Paid Ad Campaign Management

Queried daily by the Ad Data Sync Agent to retrieve spend, clicks, impressions, and conversions for all active campaigns. Uses the Google Ads Query Language (GAQL) via the REST reporting endpoint. Developer token must be at Standard Access level to pull data across all campaigns without restrictions.

// GAQL query (stored as workflow variable, not hardcoded)
SELECT campaign.id, campaign.name, campaign.status,
  metrics.cost_micros, metrics.clicks,
  metrics.impressions, metrics.conversions
FROM campaign
WHERE segments.date DURING YESTERDAY
  AND campaign.status = 'ENABLED'
// Output: array of campaign objects -> passed to Sheets write node

Queried daily in parallel with Google Ads by the Ad Data Sync Agent. Uses the Meta Marketing API (Graph API v18.0 or later) to pull spend, impressions, clicks, and conversions for all active Facebook and Instagram campaigns under the configured ad account. Requires a system user token created in Meta Business Manager.

// Meta Insights API call (parameters stored as workflow variables)
GET /{META_AD_ACCOUNT_ID}/insights
  ?fields=campaign_id,campaign_name,spend,impressions,clicks,actions
  &date_preset=yesterday
  &level=campaign
  &access_token={META_SYSTEM_USER_TOKEN}
// Output: array of campaign insight objects -> passed to Sheets write node

Used by both agents. The Ad Data Sync Agent writes daily campaign metrics to the master log tab. The Campaign Analysis and Alert Agent reads from the master log and from a separate thresholds configuration tab. Looker Studio connects directly to the sheet as a data source and refreshes automatically when new rows are written.

// Write payload from Agent 1 (batchUpdate, values array)
range: 'campaign_daily_log!A:K'
values: [[date, platform, campaign_id, campaign_name,
          spend_usd, impressions, clicks, conversions,
          cpc_usd, anomaly_flag, anomaly_reason]]
// Read payload for Agent 2 (threshold lookup)
range: 'budget_thresholds!A:E'
// Returns: campaign_id -> threshold map for comparison logic

Used by the Campaign Analysis and Alert Agent to send formatted anomaly alerts to the designated marketing Slack channel. Each alert names the campaign, the metric that triggered the flag, the current value, the threshold, and the recommended action for the manager.

// chat.postMessage payload (Block Kit, abbreviated)
{
  channel: {SLACK_ALERT_CHANNEL_ID},
  blocks: [
    { type: 'header', text: { type: 'plain_text',
        text: 'Campaign Alert: {campaign_name}' }},
    { type: 'section', fields: [
        { type: 'mrkdwn', text: '*Metric:* {anomaly_reason}' },
        { type: 'mrkdwn', text: '*Value:* {current_value}' },
        { type: 'mrkdwn', text: '*Threshold:* {threshold_value}' },
        { type: 'mrkdwn', text: '*Action:* {recommended_action}' }
    ]},
    { type: 'context', elements: [
        { type: 'mrkdwn', text: 'Alert generated: {run_timestamp}' }
    ]}
  ]
}

Used by the Campaign Analysis and Alert Agent to write conversion attribution data to HubSpot contact and deal records. Conversions captured in the ad platform APIs are matched to HubSpot contacts via UTM source and email where available, and the deal source properties are updated to reflect the paid channel.

// HubSpot Batch Contact Update (PATCH /crm/v3/objects/contacts/batch/update)
inputs: [
  {
    id: {hubspot_contact_id},
    properties: {
      paid_ad_platform: '{platform}',
      last_conversion_campaign_id: '{campaign_id}',
      last_conversion_date: '{conversion_date_iso}',
      hs_analytics_source: 'PAID_SEARCH' | 'PAID_SOCIAL',
      hs_analytics_source_data_1: '{utm_source}'
    }
  }
]
// Unmatched conversions -> written to Google Sheets attribution_unmatched tab

The Looker Studio dashboard connects directly to the Google Sheets master log as its data source. No direct API call is made by the automation to Looker Studio. The dashboard refreshes automatically each time the orchestration layer writes new rows to the sheet. Configuration is handled at the Looker Studio level, not within the workflow.

// No direct API call from automation to Looker Studio
// Data flow: Agent 1 writes to Google Sheets campaign_daily_log
// Looker Studio reads campaign_daily_log on its own refresh cycle (<= 15 min)
// Dashboard fields consumed:
//   date, platform, campaign_name, spend_usd,
//   impressions, clicks, conversions, cpc_usd, anomaly_flag

// Credential store contents (all values stored as encrypted secrets)
// Keys are referenced by name in all workflow nodes

GOOGLE_ADS_DEVELOPER_TOKEN        // Google Ads Standard Access developer token
GOOGLE_ADS_REFRESH_TOKEN          // OAuth 2.0 refresh token for Google Ads API
GOOGLE_ADS_CLIENT_ID              // OAuth 2.0 client ID (from Google Cloud Console)
GOOGLE_ADS_CLIENT_SECRET          // OAuth 2.0 client secret (from Google Cloud Console)
GOOGLE_ADS_CUSTOMER_ID            // Google Ads customer ID (format: 123-456-7890)

META_SYSTEM_USER_TOKEN            // Meta Business Manager system user access token (60-day TTL)
META_AD_ACCOUNT_ID               // Meta ad account ID (format: act_XXXXXXXXXX)
META_APP_ID                       // Meta app ID from Meta Developer Console
META_APP_SECRET                   // Meta app secret from Meta Developer Console

GOOGLE_SHEETS_SERVICE_ACCOUNT_KEY // JSON key for Google service account (minified)
GOOGLE_SHEETS_SPREADSHEET_ID      // Google Sheets spreadsheet ID (from sheet URL)

SLACK_BOT_TOKEN                   // Slack bot OAuth token (format: xoxb-...)
SLACK_ALERT_CHANNEL_ID            // Slack channel ID for anomaly alerts (format: C0XXXXXXXXX)

HUBSPOT_PRIVATE_APP_TOKEN         // HubSpot private app bearer token
HUBSPOT_PORTAL_ID                 // HubSpot portal (account) ID

LOOKER_STUDIO_REPORT_URL          // Public or shared URL of the Looker Studio dashboard
AGENT1_LAST_RUN_TIMESTAMP         // Written by Agent 1 on completion; read by Agent 2 trigger
AGENT1_COMPLETE                   // Boolean flag: 'true' when Agent 1 write is confirmed