Integration and API Spec

Integration and API Spec

Influencer & Partnership Outreach Automation

Notion serves as the campaign brief capture point. The automation platform listens for a page-updated event on the designated campaign briefs database. When a page's Status property transitions to 'Ready', the platform reads the brief fields and passes them to the Prospect Research Agent. The Notion internal integration token must be scoped to the specific database; do not grant workspace-wide access.

// Output to Prospect Research Agent
campaign_name: string
target_niche: string
min_audience_size: integer
max_audience_size: integer
channel: enum(Instagram|YouTube|Podcast|Blog)
brief_owner_email: string
notion_page_id: string  // retained for status write-back

Google Sheets acts as the prospect staging layer. The Prospect Research Agent writes one row per prospect with enrichment data. The Pitch Drafting Agent reads those rows to construct personalised draft emails. A dedicated sheet per campaign is required; the orchestration layer references the sheet by its stored spreadsheet ID, not by tab name alone.

// Input from Prospect Research Agent (append)
prospect_name, handle, niche, audience_size_est, channel, email_address, email_verified, hunter_confidence

// Output read by Pitch Drafting Agent
prospect_name, email_address, niche, handle, campaign_name, channel

// Written back by Pitch Drafting Agent
draft_status: enum(PENDING|DRAFTED|APPROVED|SENT)
hubspot_contact_id: string
sent_timestamp: ISO8601

Hunter.io provides email address lookup and confidence scoring for each prospect. The Prospect Research Agent calls the Email Finder endpoint per prospect using the prospect's full name and domain derived from their social handle or website. Results with a confidence score below 70 are flagged for manual review rather than passed downstream.

// Request
GET /v2/email-finder
  domain: string          // e.g. 'janedoe.com'
  first_name: string
  last_name: string
  api_key: HUNTER_API_KEY

// Response fields used
data.email: string
data.score: integer       // confidence 0-100
data.status: enum(valid|accept_all|webmail|unknown)

// Written to Google Sheet
email_address: data.email
hunter_confidence: data.score
email_verified: boolean   // true if score >= HUNTER_CONFIDENCE_THRESHOLD

HubSpot is used in two stages: the Pitch Drafting Agent creates contact records and tags them with campaign metadata; the Follow-Up and Pipeline Agent manages sequence enrolment, deal stage transitions, and monitors reply events. A private app token is used throughout. Sequences require Sales Hub Starter or higher.

// Contact creation (Agent 2)
POST /crm/v3/objects/contacts
  email, firstname, lastname
  campaign_tag: string
  channel: string
  niche: string
  hs_lead_status: 'NEW'

// Deal stage update (Agent 3)
PATCH /crm/v3/objects/deals/{dealId}
  dealstage: HUBSPOT_STAGE_ID

// Sequence enrolment (Agent 3)
POST /automation/v4/sequences/enroll
  sequenceId: HUBSPOT_SEQUENCE_ID
  contactId: string
  senderEmail: string

Gmail is used by the Pitch Drafting Agent to save personalised draft emails for human review, and by the Follow-Up and Pipeline Agent to detect replies and mark sent emails. The marketing manager's Gmail account is the sending account. OAuth must be granted by the account owner, not a service account, because drafts must appear in the manager's own Gmail interface.

// Draft creation (Agent 2)
POST /gmail/v1/users/me/drafts
  message.raw: base64url(MIME email with To, Subject, Body)
  // Label applied post-creation:
POST /gmail/v1/users/me/messages/{draftMsgId}/modify
  addLabelIds: ['OUTREACH-PENDING-REVIEW']

// Reply detection (Agent 3)
GET /gmail/v1/users/me/threads/{threadId}
  // Check messages[].labelIds for absence of SENT
  // Check In-Reply-To or References headers

Slack receives hot lead alert messages posted by the Follow-Up and Pipeline Agent when a prospect replies or clicks through. A dedicated Slack App with a bot token is used. The bot must be invited to the target channel before any message can be posted.

// Post message (Agent 3)
POST https://slack.com/api/chat.postMessage
  Authorization: Bearer SLACK_BOT_TOKEN
  channel: SLACK_ALERT_CHANNEL_ID
  blocks: [
    { type: 'section', text: { type: 'mrkdwn',
      text: '*Hot lead:* {prospect_name} replied to {campaign_name}' }},
    { type: 'actions', elements: [
      { type: 'button', text: 'View in HubSpot', url: deal_url }
    ]}
  ]

// Credential store contents
// Namespace: influencer-outreach
// All values encrypted at rest; never logged or exposed in error messages

NOTION_API_TOKEN          // Notion internal integration token (secret_...)
NOTION_CAMPAIGN_DB_ID     // Notion database ID for campaign briefs

GOOGLE_SERVICE_ACCOUNT_JSON  // JSON key for Google service account (Sheets + Drive)
GOOGLE_OAUTH_REFRESH_TOKEN   // User OAuth refresh token (Gmail)
GOOGLE_CLOUD_PROJECT_ID      // GCP project with Gmail API + Pub/Sub enabled
GMAIL_PUBSUB_TOPIC           // Full Pub/Sub topic name for Gmail watch
GMAIL_SENDING_ADDRESS        // Marketing manager's Gmail address
GMAIL_DRAFT_LABEL_ID         // Gmail label ID for 'Outreach-Pending-Review'
GOOGLE_SHEET_TEMPLATE_ID     // Google Sheets template file ID

HUNTER_API_KEY               // Hunter.io account API key
HUNTER_CONFIDENCE_THRESHOLD  // Integer, default: 70

HUBSPOT_PRIVATE_APP_TOKEN    // HubSpot private app Bearer token
HUBSPOT_PORTAL_ID            // HubSpot account/portal ID
HUBSPOT_PIPELINE_ID          // Deal pipeline ID for outreach pipeline
HUBSPOT_SEQUENCE_ID          // Sequence ID for follow-up enrolment
HUBSPOT_WEBHOOK_SECRET       // HMAC secret for webhook signature validation
// Stage IDs (fetched at build time, stored here):
HUBSPOT_STAGE_PROSPECT       // 'Prospect Identified' stage ID
HUBSPOT_STAGE_DRAFTED        // 'Pitch Drafted' stage ID
HUBSPOT_STAGE_SENT           // 'Pitch Sent' stage ID
HUBSPOT_STAGE_REPLIED        // 'Replied' stage ID
HUBSPOT_STAGE_DECLINED       // 'Declined' stage ID

SLACK_BOT_TOKEN              // Slack bot OAuth token (xoxb-...)
SLACK_ALERT_CHANNEL_ID       // Slack channel ID for hot lead alerts

ENVIRONMENT                  // 'staging' | 'production'