Integration and API Spec

Integration and API Spec

Win/Loss Analysis Automation

Acts as the primary trigger source (deal stage change) and as a read/write data store for deal records and outcome tags. Used by Agent 1 (Deal Capture) and Agent 2 (Outcome Classification).

// Inbound webhook payload (key fields)
{ "subscriptionType": "deal.propertyChange",
  "objectId": 12345678,
  "propertyName": "dealstage",
  "propertyValue": "<stage_id_closedwon|closedlost>" }

// Deal GET response (fields extracted)
dealname, amount, closedate, hubspot_owner_id,
hs_num_associated_contacts, pipeline, dealstage

// PATCH body for outcome writeback
{ "properties": {
  "hs_wl_outcome_tag": "Won - Champion",
  "hs_wl_reason_code": "W-CHAMP",
  "hs_wl_summary": "<150-char AI summary>" } }

Hosts the 8-question structured buyer outcome survey. Agent 1 dispatches a pre-filled survey link via Gmail. Agent 2 ingests the completed response via webhook.

// Webhook response payload (key fields)
{ "form_id": "<TYPEFORM_FORM_ID>",
  "token": "<response_token>",
  "hidden": { "deal_id": "12345678", "deal_name": "Acme Q2",
               "company_name": "Acme Corp", "rep_name": "Sam Okafor" },
  "answers": [
    { "field": { "ref": "primary_outcome_reason" }, "choice": { "label": "Pricing" } },
    { "field": { "ref": "competitor_named" }, "text": "Competitor X" },
    { "field": { "ref": "nps_score" }, "number": 7 }
  ] }

Sends the personalised Typeform survey link to the primary buyer contact. Used exclusively by Agent 1. Sending is done via the Gmail API on behalf of the authenticated Google account.

// Gmail API send body (Messages.send)
{ "raw": "<base64url-encoded RFC 2822 message>" }

// Constructed email headers
From: Win/Loss Insights <automation@[YourCompany.com]>
To: {{buyer_email}}
Subject: Quick question about your decision — {{deal_name}}
Content-Type: text/html

// Response (success)
{ "id": "<message_id>", "threadId": "<thread_id>", "labelIds": ["SENT"] }

Delivers the rep notification with embedded structured form (Agent 1) and posts the monthly report digest to the sales channel (Agent 3). Uses a Slack Bot token with Block Kit payloads.

// chat.postMessage payload (rep notification)
{ "channel": "<rep_slack_user_id>",
  "blocks": [
    { "type": "section", "text": { "type": "mrkdwn",
      "text": "*Deal closed: {{deal_name}}* ({{outcome}}). Please log your outcome below." } },
    { "type": "actions", "elements": [
      { "type": "static_select", "action_id": "wl_outcome_reason",
        "placeholder": { "type": "plain_text", "text": "Select primary reason" },
        "options": [ <taxonomy options from TAXONOMY_JSON> ] }
    ] }
  ] }

// Inbound Block Kit interaction payload (key fields)
{ "type": "block_actions",
  "user": { "id": "U0123ABC", "email": "sam@[YourCompany.com]" },
  "actions": [ { "action_id": "wl_outcome_reason",
    "selected_option": { "value": "W-CHAMP" } } ] }

Serves as the persistent win/loss data tracker. Agent 2 appends a structured row per closed deal. Agent 3 reads all rows from the prior calendar month to generate the insight report.

// Sheets API append body (values.append)
{ "range": "WinLoss_Tracker!A:M",
  "majorDimension": "ROWS",
  "values": [[
    "12345678",       // deal_id
    "Acme Q2",        // deal_name
    "Acme Corp",      // company_name
    "Sam Okafor",     // rep_name
    "2024-06-01",     // close_date
    "Lost",           // outcome
    "Pricing",        // outcome_tag
    "L-PRICE",        // reason_code
    "18500",          // deal_value
    "Competitor X",   // competitor
    "Chose on price", // buyer_response_summary
    "Rep notes text", // rep_notes
    "2024-06-01T09:14:00Z" // row_created_at
  ]] }

Receives the monthly insight report as a new structured page in a designated database. Used exclusively by Agent 3 on the first business day of each month.

// Notion pages.create body
{ "parent": { "database_id": "<NOTION_DATABASE_ID>" },
  "properties": {
    "Report Month": { "date": { "start": "2024-06-01" } },
    "Status": { "select": { "name": "Published" } },
    "Created By": { "select": { "name": "Automation" } }
  },
  "children": [
    { "object": "block", "type": "heading_2",
      "heading_2": { "rich_text": [{ "text": { "content": "Win/Loss Summary: June 2024" } }] } },
    { "object": "block", "type": "paragraph",
      "paragraph": { "rich_text": [{ "text": { "content": "<AI-generated summary>" } }] } }
  ] }

// Credential store contents (all values encrypted at rest)

// HubSpot
HUBSPOT_PRIVATE_APP_TOKEN=<private_app_token>
HUBSPOT_WEBHOOK_SECRET=<hmac_secret>
HUBSPOT_PIPELINE_ID=<pipeline_id>
HUBSPOT_STAGE_CLOSEDWON_ID=<stage_id>
HUBSPOT_STAGE_CLOSEDLOST_ID=<stage_id>

// Typeform
TYPEFORM_ACCESS_TOKEN=<oauth_access_token>
TYPEFORM_REFRESH_TOKEN=<oauth_refresh_token>
TYPEFORM_FORM_ID=<form_id>
TYPEFORM_WEBHOOK_SECRET=<hmac_secret>

// Gmail (Google OAuth)
GMAIL_OAUTH_CLIENT_ID=<google_client_id>
GMAIL_OAUTH_CLIENT_SECRET=<google_client_secret>
GMAIL_OAUTH_REFRESH_TOKEN=<google_refresh_token>
GMAIL_SENDER_ADDRESS=automation@[YourCompany.com]
GMAIL_FROM_NAME=Win/Loss Insights
GMAIL_SURVEY_TEMPLATE_ID=<template_id_in_store>

// Slack
SLACK_BOT_TOKEN=xoxb-<token>
SLACK_SIGNING_SECRET=<signing_secret>
SLACK_SALES_CHANNEL_ID=C0123ABCDEF
SLACK_ALERT_CHANNEL_ID=C0456GHIJKL
SLACK_BOT_USER_ID=U0789MNOPQR

// Google Sheets
GSHEETS_SERVICE_ACCOUNT_JSON=<json_key_contents>
GSHEETS_SPREADSHEET_ID=<spreadsheet_id>
GSHEETS_SHEET_NAME=WinLoss_Tracker

// Notion
NOTION_INTEGRATION_TOKEN=secret_<token>
NOTION_DATABASE_ID=<32-char-database-id>

// Taxonomy
TAXONOMY_JSON=<json_string_of_win_loss_reason_categories>

// AI classification
AI_CLASSIFIER_API_KEY=<api_key>
AI_CLASSIFIER_MODEL=<model_id>
AI_CLASSIFIER_ENDPOINT=<endpoint_url>