Integration and API Spec

Integration and API Spec

Lead Magnet & Landing Page Follow-up

Typeform is the workflow trigger. Every new form submission fires an HTTP POST webhook to the orchestration layer endpoint. The payload contains all field responses keyed by field reference ID. A Personal Access Token is used only if the orchestration layer needs to backfill missed events via the Responses API.

// Inbound webhook payload (key fields)
POST /webhook/typeform-inbound
Headers: typeform-signature: sha256=<hmac>
{
  "form_id": "<TYPEFORM_FORM_ID>",
  "token": "<unique_response_token>",
  "submitted_at": "2024-04-19T10:23:11Z",
  "answers": [
    { "field": { "ref": "email_field_ref" }, "email": "contact@example.com" },
    { "field": { "ref": "first_name_ref" }, "text": "Jane" },
    { "field": { "ref": "last_name_ref" }, "text": "Smith" },
    { "field": { "ref": "magnet_choice_ref" }, "choice": { "label": "SEO Checklist" } }
  ]
}
// Output to Agent 1
{ email, first_name, last_name, lead_magnet_label, submitted_at, response_token }

HubSpot is used by both agents. Agent 1 performs contact deduplication via email lookup, upserts the contact record, applies list membership, sets custom properties for lead source and lead magnet label, and writes an initial lead score. Agent 2 reads the contact's engagement score to determine whether the warm-lead threshold has been crossed.

// Deduplication search request
POST /crm/v3/objects/contacts/search
{ "filterGroups": [{ "filters": [{ "propertyName": "email", "operator": "EQ", "value": "<email>" }] }] }
// Upsert (create)
POST /crm/v3/objects/contacts
{ "properties": { "email", "firstname", "lastname", "hs_lead_source", "lead_magnet_label", "lead_magnet_delivered_at", "nurture_sequence_enrolled" } }
// Upsert (update)
PATCH /crm/v3/objects/contacts/<hs_object_id>
// Add to list
POST /contacts/v1/lists/<HUBSPOT_LIST_ID>/contacts/add
{ "vids": [<hs_object_id>] }
// Warm-lead engagement read (Agent 2)
GET /crm/v3/objects/contacts/<hs_object_id>?properties=hs_email_open_count,hs_email_click_count,hubscore

Mailchimp handles two distinct functions: transactional asset delivery emails (via Mandrill) and nurture sequence enrolment (via Mailchimp Automations). These use separate API surfaces and separate keys. The correct template and sequence are selected based on the lead_magnet_label value passed from Agent 1.

// Mandrill transactional send
POST https://mandrillapp.com/api/1.0/messages/send-template
{
  "key": "<MANDRILL_API_KEY>",
  "template_name": "<MANDRILL_TEMPLATE_SLUG_seo-checklist>",
  "template_content": [],
  "message": {
    "to": [{ "email": "contact@example.com", "name": "Jane Smith" }],
    "merge_vars": [{ "rcpt": "contact@example.com", "vars": [
      { "name": "FIRST_NAME", "content": "Jane" },
      { "name": "ASSET_URL", "content": "<GDRIVE_ASSET_URL_seo-checklist>" },
      { "name": "MAGNET_LABEL", "content": "SEO Checklist" }
    ]}]
  }
}
// Nurture enrolment
POST /3.0/automations/<MAILCHIMP_WORKFLOW_ID_seo-checklist>/emails/<MAILCHIMP_WORKFLOW_EMAIL_ID_seo-checklist>/queue
{ "email_address": "contact@example.com" }

Google Drive is not called at runtime for file content. The orchestration layer resolves the correct asset shareable link from a pre-built lookup table stored in the credential store, keyed by magnet slug. The Drive API is used during setup to verify link validity and confirm share permissions. If link rotation is required, a Drive API call updates the lookup table.

// Link verification (setup only)
GET https://www.googleapis.com/drive/v3/files/<file_id>?fields=id,name,webViewLink,permissions
// Expected: permissions includes { type: 'anyone', role: 'reader' }
// Runtime: no Drive API call. Orchestration layer reads GDRIVE_ASSET_URL_<MAGNET_SLUG> from credential store directly.

Google Sheets receives one appended row per successful submission, written by Agent 1 after the HubSpot upsert is confirmed. The sheet acts as the operational tracking log and is read by the marketing coordinator for exception review and volume reporting.

// Append row
POST https://sheets.googleapis.com/v4/spreadsheets/<GSHEETS_SPREADSHEET_ID>/values/<GSHEETS_SHEET_NAME>!A:H:append?valueInputOption=USER_ENTERED
{
  "values": [[
    "<submitted_at>",
    "<email>",
    "<first_name>",
    "<last_name>",
    "<lead_magnet_label>",
    "<hs_object_id>",
    "<mandrill_message_id>",
    "<delivery_status>"
  ]]
}

Slack receives a single inbound message from Agent 2 when a contact crosses the warm-lead threshold (2 email opens and 1 link click recorded in HubSpot). The message is posted via an Incoming Webhook URL to the designated sales channel. No Slack API read operations are performed by this workflow.

// Warm-lead alert post
POST <SLACK_WEBHOOK_URL>
{
  "text": "Warm lead alert",
  "blocks": [
    { "type": "section", "text": { "type": "mrkdwn",
      "text": "*<first_name> <last_name>* (<email>) has reached warm-lead threshold.\nMagnet: <lead_magnet_label>\n<hubspot_contact_url>" } }
  ]
}

// Credential store contents (all entries required before build begins)

// Typeform
TYPEFORM_WEBHOOK_SECRET=<hmac_secret_from_typeform_ui>
TYPEFORM_FORM_ID=<form_id_from_typeform>
TYPEFORM_PAT=<personal_access_token>          // fallback Responses API only

// HubSpot
HUBSPOT_PORTAL_ID=<portal_id>
HUBSPOT_PRIVATE_APP_TOKEN=<private_app_token>
HUBSPOT_LIST_ID_seo-checklist=<list_id>
HUBSPOT_LIST_ID_<magnet_slug>=<list_id>       // one entry per active lead magnet

// Mailchimp / Mandrill
MAILCHIMP_API_KEY=<mailchimp_api_key>
MAILCHIMP_AUDIENCE_ID=<audience_id>
MAILCHIMP_DC=us21                             // replace with actual data centre
MANDRILL_API_KEY=<mandrill_api_key>
MANDRILL_TEMPLATE_SLUG_seo-checklist=lm-asset-seo-checklist
MANDRILL_TEMPLATE_SLUG_<magnet_slug>=<template_slug>  // one per magnet
MAILCHIMP_WORKFLOW_ID_seo-checklist=<automation_workflow_id>
MAILCHIMP_WORKFLOW_EMAIL_ID_seo-checklist=<first_email_id_in_workflow>
MAILCHIMP_WORKFLOW_ID_<magnet_slug>=<workflow_id>     // one per magnet
MAILCHIMP_WORKFLOW_EMAIL_ID_<magnet_slug>=<email_id>  // one per magnet

// Google (shared service account)
GDRIVE_SERVICE_ACCOUNT_KEY=<base64_encoded_service_account_json>
GSHEETS_SERVICE_ACCOUNT_KEY=<base64_encoded_service_account_json>  // may be same key
GSHEETS_SPREADSHEET_ID=<spreadsheet_id>
GSHEETS_SHEET_NAME=Submissions
GDRIVE_ASSET_URL_seo-checklist=https://drive.google.com/uc?export=download&id=<file_id>
GDRIVE_ASSET_URL_<magnet_slug>=<drive_url>    // one per active lead magnet

// Slack
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/<T_ID>/<B_ID>/<token>
SLACK_CHANNEL_ID=<channel_id>

// Warm-lead threshold (configurable without code change)
WARM_LEAD_OPEN_THRESHOLD=2
WARM_LEAD_CLICK_THRESHOLD=1