Integration and API Spec

Integration and API Spec

Lead Nurture Sequence

Used by Agent 1 (Lead Qualification Agent), Agent 2 (Sequence Messaging Agent), and Agent 3 (Sales Alert Agent). HubSpot is the system of record for all contact data, lifecycle stages, activity logs, and qualification tags. All reads and writes route through the HubSpot v3 CRM API.

// Read
GET /crm/v3/objects/contacts/{id}?properties=firstname,lastname,email,lifecyclestage,hs_lead_source,qualification_tag,hs_lead_score
// Write
PATCH /crm/v3/objects/contacts/{id}
  body: { properties: { qualification_tag, hs_lead_score, lifecyclestage, sequence_status } }
// Activity log
POST /crm/v3/objects/communications
  body: { properties: { hs_communication_channel_type: 'EMAIL', hs_communication_body: '<summary>' } }

Used exclusively by Agent 2 (Sequence Messaging Agent) for outbound email delivery across all three sequence touchpoints. Email is sent via the Gmail API using pre-approved templates stored in the credential store. No emails are sent without a resolved contact record in HubSpot.

// Send email
POST /gmail/v1/users/{userId}/messages/send
  body: { raw: base64url(RFC2822_message) }
// RFC2822 headers required
  To: {contact.email}
  From: {GMAIL_SENDER_ADDRESS}
  Subject: {TEMPLATE_SUBJECT_T1 | T2 | T3}
  Content-Type: text/html; charset=UTF-8
// Reply check
GET /gmail/v1/users/{userId}/threads/{threadId}
  filter: messages where from != {GMAIL_SENDER_ADDRESS} AND date > {send_timestamp}

Used by Agent 2 (Sequence Messaging Agent) to detect whether a lead has booked a meeting, and by Agent 3 (Sales Alert Agent) to retrieve booking details for the Slack notification. Calendly webhooks are the primary trigger for the booking path.

// Inbound webhook payload (invitee.created)
POST {ORCHESTRATION_WEBHOOK_ENDPOINT}
  payload.event_type.uri == CALENDLY_EVENT_TYPE_URI
  payload.payload.invitee.email -> match to HubSpot contact by email
  payload.payload.invitee.name -> Slack alert display name
  payload.payload.scheduled_event.start_time -> Slack alert meeting time
// Webhook registration
POST /webhook_subscriptions
  body: { url, organization, scope: 'organization', events: ['invitee.created'], signing_key: CALENDLY_WEBHOOK_SECRET }

Used by Agent 3 (Sales Alert Agent) to post a formatted booking or positive-reply notification to the designated sales channel. Slack is write-only in this automation; no data is read from Slack.

// Post booking alert
POST https://slack.com/api/chat.postMessage
  Authorization: Bearer {SLACK_BOT_TOKEN}
  body: {
    channel: {SLACK_SALES_CHANNEL_ID},
    blocks: [
      { type: 'section', text: { type: 'mrkdwn',
        text: '*New booking:* {{lead_name}} | {{meeting_time}} | <{{hubspot_contact_url}}|View in HubSpot>' }
      }
    ]
  }

Used by Agent 1 (Lead Qualification Agent) as a read-only reference for the ICP scoring matrix. The sheet holds the scoring rules that determine whether a lead clears the qualification threshold. The sheet must be structured in a specific format before go-live.

// Read scoring matrix
GET /spreadsheets/{GSHEETS_SCORING_SHEET_ID}/values/{GSHEETS_SCORING_RANGE}
  Authorization: Bearer {service_account_access_token}
// Response structure expected
  values: [
    ['criterion_name', 'field_key', 'match_value', 'score_weight'],
    ['Company size', 'company_size_range', '11-50', '25'],
    ['Lead source', 'hs_lead_source', 'Organic Search|Referral', '20'],
    ...
  ]

// CREDENTIAL STORE CONTENTS
// All values encrypted at rest; reference by key name only in workflow config

HUBSPOT_PRIVATE_APP_TOKEN        = 'pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
HUBSPOT_PORTAL_ID                = '12345678'
HUBSPOT_LIFECYCLE_STAGE_LEAD     = 'lead'
HUBSPOT_LIFECYCLE_STAGE_CONTACTED = 'contacted'
HUBSPOT_LIFECYCLE_STAGE_OPPORTUNITY = 'opportunity'
HUBSPOT_LIFECYCLE_STAGE_NURTURE  = 'long_term_nurture'
HUBSPOT_WEBHOOK_SECRET           = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

GMAIL_CLIENT_ID                  = 'xxxxxxxx.apps.googleusercontent.com'
GMAIL_CLIENT_SECRET              = 'GOCSPX-xxxxxxxxxxxxxxxxxxxxxxxx'
GMAIL_REFRESH_TOKEN              = '1//xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
GMAIL_SENDER_ADDRESS             = 'outreach@[YourCompany.com]'
GMAIL_SENDER_DISPLAY_NAME        = '[YourCompany.com] Sales'

GMAIL_TEMPLATE_SUBJECT_T1        = 'Quick note about your enquiry, {{firstname}}'
GMAIL_TEMPLATE_SUBJECT_T2        = 'Following up, {{firstname}}'
GMAIL_TEMPLATE_SUBJECT_T3        = 'Last touch from us, {{firstname}}'
GMAIL_TEMPLATE_BODY_T1           = '<stored HTML string with {{firstname}}, {{lead_source}}, {{enquiry_topic}}, {{calendly_link}}>'
GMAIL_TEMPLATE_BODY_T2           = '<stored HTML string with {{firstname}}, {{calendly_link}}>'
GMAIL_TEMPLATE_BODY_T3           = '<stored HTML string with {{firstname}}, {{calendly_link}}>'

CALENDLY_API_TOKEN               = 'eyJxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
CALENDLY_ORGANISATION_URI        = 'https://api.calendly.com/organizations/xxxxxxxx'
CALENDLY_EVENT_TYPE_URI          = 'https://api.calendly.com/event_types/xxxxxxxx'
CALENDLY_BOOKING_LINK            = 'https://calendly.com/[YourCompany.com]/sales-intro'
CALENDLY_WEBHOOK_SECRET          = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

SLACK_BOT_TOKEN                  = 'xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx'
SLACK_SALES_CHANNEL_ID           = 'C0XXXXXXXXX'
SLACK_ALERT_TEMPLATE             = '*New booking:* {{lead_name}} | {{meeting_time}} | <{{hubspot_contact_url}}|View in HubSpot>'

GSHEETS_SERVICE_ACCOUNT_JSON     = '{ "type": "service_account", "project_id": "...", ... }'
GSHEETS_SCORING_SHEET_ID         = '1BxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxA'
GSHEETS_SCORING_RANGE            = 'ICP_Criteria!A2:D50'
GSHEETS_ICP_THRESHOLD            = '60'

ORCHESTRATION_WEBHOOK_ENDPOINT   = 'https://orchestration.[YourCompany.com]/hooks/lead-nurture'
POLL_CURSOR_KEY                  = 'hubspot_last_poll_timestamp'