Integration and API Spec

Integration and API Spec

Lead Capture and Routing

Typeform acts as the primary lead intake trigger. A webhook is registered against the target form and fires a POST payload to the orchestration layer on every new submission. The orchestration layer validates the webhook signature before processing the payload.

// Inbound webhook payload (key fields)
form_response.form_id          -> string
form_response.token            -> string (unique response ID)
form_response.submitted_at     -> ISO 8601 timestamp
form_response.answers[].field.ref -> string (maps to scoring field keys)
form_response.answers[].text   -> string | null
form_response.answers[].email  -> string | null
form_response.hidden.utm_source -> string | null

// Output passed to Agent 1
raw_lead.source                = 'typeform'
raw_lead.response_id           = form_response.token
raw_lead.submitted_at          = form_response.submitted_at
raw_lead.fields                = normalised key-value map from answers[]

HubSpot is the system of record for all contact data, lead scores, lifecycle stages, rep assignments, and follow-up tasks. The automation platform communicates with HubSpot via the Contacts, Properties, Owners, and Tasks APIs using a Private App token.

// Deduplication search request body
POST /crm/v3/objects/contacts/search
{ filterGroups: [{ filters: [{ propertyName: 'email', operator: 'EQ', value: raw_lead.email }] }] }

// Contact create/update body (representative fields)
properties.firstname           = raw_lead.first_name
properties.lastname            = raw_lead.last_name
properties.email               = raw_lead.email
properties.phone               = raw_lead.phone
properties.company             = raw_lead.company
properties.lead_score          = scoring_result.numeric_score
properties.lead_priority       = scoring_result.priority_tag
properties.lead_source_channel = raw_lead.source
properties.lifecyclestage      = HUBSPOT_STAGE_LEAD_ID | HUBSPOT_STAGE_OPP_ID
properties.hubspot_owner_id    = routing_result.assigned_owner_id

Gmail serves two roles: (1) an inbound alias listener that detects lead emails arriving in the sales inbox as a secondary trigger source, and (2) the outbound sender for personalised prospect acknowledgement emails within two minutes of lead arrival.

// Inbound Pub/Sub notification (trigger only)
message.data                   -> base64-encoded JSON { emailAddress, historyId }

// After message fetch and parse
raw_lead.source                = 'gmail-alias'
raw_lead.email                 = parsed headers['From']
raw_lead.subject               = parsed headers['Subject']
raw_lead.body_text             = decoded text/plain part

// Outbound acknowledgement send body
POST /gmail/v1/users/me/messages/send
{ raw: base64url(RFC2822 message with To, From, Subject, body) }

Slack is used exclusively for outbound rep notification messages posted by Agent 2 (Lead Routing and Notification Agent). The bot posts a structured message to a rep-specific DM or a shared team channel with lead context and a HubSpot deep link.

// chat.postMessage request body (simplified Block Kit)
channel                        = resolved slack_user_id (or SLACK_FALLBACK_CHANNEL_ID)
blocks[0].type                 = 'header' -> text: 'New Lead: {first_name} {last_name}'
blocks[1].type                 = 'section' -> fields:
  Priority: {lead_priority}
  Score: {numeric_score}
  Source: {lead_source_channel}
blocks[2].type                 = 'section' -> text: top 3 form answers (mrkdwn)
blocks[3].type                 = 'actions' -> button: 'Open in HubSpot' url={hubspot_contact_url}

Google Sheets has two roles: (1) a read source for the scoring rubric configuration consumed by Agent 1, and (2) an append-only write target for the manager-facing lead volume log updated by Agent 2 after each lead is processed.

// Scoring rubric read
GET /v4/spreadsheets/{SHEETS_SCORING_CONFIG_ID}/values/{SHEETS_SCORING_RUBRIC_RANGE}
response.values[]              -> array of [criterion, field_ref, weight, hot_threshold, warm_threshold, low_threshold]

// Log append request body
POST /v4/spreadsheets/{SHEETS_LEAD_LOG_ID}/values/{SHEETS_LOG_APPEND_RANGE}:append
valueInputOption: RAW
insertDataOption: INSERT_ROWS
values: [[timestamp, response_id, first_name, last_name, email, company, source, numeric_score, priority_tag, assigned_rep_name]]

// Credential store contents (all keys; values stored encrypted)

// Typeform
TYPEFORM_OAUTH_TOKEN            // OAuth 2.0 access token
TYPEFORM_WEBHOOK_SECRET         // HMAC-SHA256 signing secret for webhook validation
TYPEFORM_FORM_ID                // Production form ID
TYPEFORM_FORM_ID_STAGING        // Staging/test form ID

// HubSpot
HUBSPOT_PRIVATE_APP_TOKEN       // Bearer token for all HubSpot API calls
HUBSPOT_PORTAL_ID               // Production portal ID
HUBSPOT_PORTAL_ID_SANDBOX       // Sandbox portal ID
HUBSPOT_STAGE_LEAD_ID           // Pipeline stage ID for 'Lead'
HUBSPOT_STAGE_OPP_ID            // Pipeline stage ID for 'Opportunity'

// Gmail
GMAIL_CLIENT_ID                 // Google OAuth 2.0 client ID
GMAIL_CLIENT_SECRET             // Google OAuth 2.0 client secret
GMAIL_OAUTH_ACCESS_TOKEN        // Short-lived access token (refresh automatically)
GMAIL_OAUTH_REFRESH_TOKEN       // Long-lived refresh token
GMAIL_LEAD_ALIAS                // Production lead inbox address
GMAIL_LEAD_ALIAS_STAGING        // Staging inbox address for testing
GMAIL_ACK_TEMPLATE_ID           // Google Docs Draft or Sheets row ref for ack email template
GMAIL_PUBSUB_HMAC_SECRET        // HMAC secret for Pub/Sub push validation
GMAIL_PUBSUB_TOPIC              // Pub/Sub topic name (full resource path)

// Slack
SLACK_BOT_TOKEN                 // Bot User OAuth Token (xoxb-...)
SLACK_FALLBACK_CHANNEL_ID       // Channel ID for unresolved rep routing alerts
SLACK_FALLBACK_CHANNEL_ID_STAGING // Staging fallback channel
SLACK_REP_MAP_SHEET_RANGE       // Sheets range ref for HubSpot->Slack user ID mapping

// Google Sheets
GOOGLE_SERVICE_ACCOUNT_JSON     // Full service account key JSON (base64-encoded)
SHEETS_SCORING_CONFIG_ID        // Spreadsheet ID for scoring rubric
SHEETS_SCORING_RUBRIC_RANGE     // Named range (e.g. ScoringConfig!A2:F50)
SHEETS_LEAD_LOG_ID              // Spreadsheet ID for lead volume log
SHEETS_LEAD_LOG_ID_STAGING      // Staging log spreadsheet ID
SHEETS_LOG_APPEND_RANGE         // Append range (e.g. LeadLog!A:J)