Integration and API Spec

Integration and API Spec

Customer Segmentation & List Management

Used by Agent 1 (Data Merge and Dedup) to pull contact records on trigger, and by Agent 2 (Segmentation Rules) to write segment tags and suppression flags back to each contact. All calls use the HubSpot Contacts v3 API.

// Inbound webhook payload (contact.propertyChange)
{
  "objectId": 12345678,
  "subscriptionType": "contact.propertyChange",
  "propertyName": "email",
  "propertyValue": "user@example.com",
  "occurredAt": 1718500000000,
  "portalId": 99999999
}

// Agent 1 read call
GET /crm/v3/objects/contacts/{objectId}
  ?properties=email,firstname,lastname,phone,lifecyclestage,
              hs_lead_status,hs_segment_tag,hs_suppression_flag,
              hs_last_modified_date,associatedcompanyid

// Agent 2 write call (batch update)
POST /crm/v3/objects/contacts/batch/update
  body: { "inputs": [
    { "id": "12345678",
      "properties": {
        "hs_segment_tag": "high_value_buyer",
        "hs_suppression_flag": "false",
        "hs_last_segment_run": "2024-06-16T10:00:00Z"
      }
    }
  ]}

Delivers new lead capture responses to Agent 1 via a real-time webhook. A scheduled backfill poll covers any webhook delivery failures. Used by Agent 1 only.

// Inbound webhook payload (abbreviated)
{
  "event_id": "abc123",
  "event_type": "form_response",
  "form_response": {
    "form_id": "FORM_ID_FROM_CONFIG",
    "submitted_at": "2024-06-16T09:45:00Z",
    "answers": [
      { "field": { "id": "field_001", "type": "email" }, "email": "user@example.com" },
      { "field": { "id": "field_002", "type": "short_text" }, "text": "Jane Smith" },
      { "field": { "id": "field_003", "type": "phone_number" }, "phone_number": "+15550001234" }
    ]
  }
}

Acts as the deduplication and data routing layer between Agent 1 and Agent 2. Agent 1 sends identify and track calls to Segment; Agent 2 queries the Profiles API to retrieve the resolved canonical identity before applying segment rules.

// Agent 1 -> Segment identify call
POST https://api.segment.io/v1/identify
Authorization: Basic base64(SEGMENT_WRITE_KEY:)
{
  "userId": "hs_12345678",
  "traits": {
    "email": "user@example.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "phone": "+15550001234",
    "source": "hubspot"
  }
}

// Agent 2 -> Segment Profiles API read
GET https://profiles.segment.com/v1/spaces/{SEGMENT_SPACE_ID}/collections/users/profiles/email:user@example.com
Authorization: Basic base64(SEGMENT_API_TOKEN:)
// Returns canonical profile with merged userId list

Receives segment audience updates from Agent 2 and provides the suppression list (unsubscribes and bounces) for Agent 2 to exclude before syncing. Used by Agent 2 only.

// Agent 2 -> suppression list pull
GET /3.0/lists/{MAILCHIMP_DEFAULT_LIST_ID}/members
  ?status=unsubscribed&count=1000&offset=0
// Paginate using total_items vs offset

// Agent 2 -> batch segment sync
POST /3.0/batches
{
  "operations": [
    {
      "method": "PUT",
      "path": "/lists/{audience_id}/members/{md5_email}",
      "body": "{\"email_address\":\"user@example.com\",\"status_if_new\":\"subscribed\",\"merge_fields\":{\"FNAME\":\"Jane\",\"LNAME\":\"Smith\"},\"tags\":[\"high_value_buyer\"]}"
    }
  ]
}

Receives append-only log rows from Agent 3 after each automation run. Stores segment counts, record change totals, flagged contacts, and run timestamps for audit purposes.

// Agent 3 -> append log row
POST https://sheets.googleapis.com/v4/spreadsheets/{GSHEETS_LOG_SPREADSHEET_ID}
     /values/{GSHEETS_LOG_SHEET_NAME}!A:H:append
  ?valueInputOption=USER_ENTERED
{
  "values": [[
    "2024-06-16T10:05:00Z",
    "Reporting and Notification Agent",
    "412",
    "38",
    "4",
    "2",
    "success",
    "2 contacts flagged: ambiguous segment; routed to marketing manager review"
  ]]
}

Receives a structured run summary message from Agent 3 after each automation run. The message is posted to a designated marketing ops channel. Used by Agent 3 only.

// Agent 3 -> Slack post
POST https://slack.com/api/chat.postMessage
Authorization: Bearer {SLACK_BOT_TOKEN}
{
  "channel": "{SLACK_CHANNEL_ID}",
  "blocks": [
    { "type": "header", "text": { "type": "plain_text", "text": "Segmentation Run Complete" } },
    { "type": "section", "fields": [
        { "type": "mrkdwn", "text": "*Records processed:* 412" },
        { "type": "mrkdwn", "text": "*Records changed:* 38" },
        { "type": "mrkdwn", "text": "*Segments updated:* 4" },
        { "type": "mrkdwn", "text": "*Flagged for review:* 2" }
    ]},
    { "type": "context", "elements": [
        { "type": "mrkdwn", "text": "Run at 2024-06-16T10:05:00Z | <log_url|View full log>" }
    ]}
  ]
}

// Credential store contents (all required before first run)

// HubSpot
HUBSPOT_PRIVATE_APP_TOKEN=<hubspot_private_app_token>
HUBSPOT_PORTAL_ID=<hubspot_portal_id>
HUBSPOT_WEBHOOK_CLIENT_SECRET=<hubspot_webhook_client_secret>

// Typeform
TYPEFORM_API_TOKEN=<typeform_personal_access_token>
TYPEFORM_FORM_ID=<target_form_id>
TYPEFORM_WEBHOOK_SECRET=<typeform_webhook_signing_secret>

// Segment
SEGMENT_WRITE_KEY=<segment_source_write_key>
SEGMENT_API_TOKEN=<segment_public_api_token>
SEGMENT_SPACE_ID=<segment_unify_space_id>
SEGMENT_MAILCHIMP_DESTINATION_ID=<segment_mailchimp_destination_id>

// Mailchimp
MAILCHIMP_API_KEY=<mailchimp_api_key>
MAILCHIMP_DC=<data_centre_suffix_e.g._us6>
MAILCHIMP_DEFAULT_LIST_ID=<master_audience_id>
MAILCHIMP_AUDIENCE_HIGH_VALUE_ID=<audience_id>
MAILCHIMP_AUDIENCE_LAPSED_ID=<audience_id>
MAILCHIMP_AUDIENCE_NEWSLETTER_ONLY_ID=<audience_id>
// Add one entry per additional segment audience

// Google Sheets
GOOGLE_SERVICE_ACCOUNT_JSON=<json_key_as_single_line_string>
GSHEETS_LOG_SPREADSHEET_ID=<spreadsheet_id>
GSHEETS_LOG_SHEET_NAME=<tab_name_e.g._RunLog>

// Slack
SLACK_BOT_TOKEN=<xoxb_bot_token>
SLACK_CHANNEL_ID=<marketing_ops_channel_id>
SLACK_ALERT_CHANNEL_ID=<ops_alerts_channel_id>

// Orchestration internal
PIPELINE_LOCK_KEY=segmentation-list-mgmt
DATASET_TTL_SECONDS=21600
RUN_BACKFILL_LOOKBACK_HOURS=25