Integration and API Spec

Integration and API Spec

Proposal Creation Automation

Serves as the automation trigger source and the final write destination. A deal moving to the 'Proposal Requested' pipeline stage fires the inbound webhook. At the end of the flow, the Approval and Delivery Agent writes the updated deal stage and logs a timestamped activity. Estimated integration complexity: Moderate.

// Inbound webhook payload (abbreviated)
{
  "objectId": "<deal_id>",
  "propertyName": "dealstage",
  "propertyValue": "<stage_id_proposal_requested>",
  "subscriptionType": "deal.propertyChange"
}

// GET /crm/v3/objects/deals/{deal_id}?properties=dealname,amount,hubspot_owner_id,hs_custom_pricing_tier,hs_custom_discount_pct
// GET /crm/v3/objects/deals/{deal_id}/associations/contacts
// GET /crm/v3/objects/deals/{deal_id}/associations/companies

// PATCH /crm/v3/objects/deals/{deal_id} — update stage to Proposal Sent
// POST /crm/v3/timeline/events — log proposal send activity

Receives the structured deal data object from the Proposal Assembly Agent and generates a new document from the stored master template. Returns a document ID and shareable link. The Approval and Delivery Agent later retrieves the document status to confirm it has been sent. Estimated integration complexity: Moderate.

// POST /public/v1/documents
{
  "name": "Proposal - {{deal.dealname}} - {{date}}",
  "template_uuid": "{{PANDADOC_TEMPLATE_ID}}",
  "recipients": [{
    "email": "{{contact.email}}",
    "first_name": "{{contact.firstname}}",
    "last_name": "{{contact.lastname}}",
    "role": "Prospect"
  }],
  "fields": {
    "prospect_name": { "value": "{{contact.firstname}} {{contact.lastname}}" },
    "company_name": { "value": "{{company.name}}" },
    "deal_value": { "value": "{{deal.amount}}" },
    "pricing_tier": { "value": "{{resolved.pricing_tier}}" },
    "discount_pct": { "value": "{{resolved.discount_pct}}" },
    "expiry_date": { "value": "{{resolved.expiry_date}}" },
    "scope_description": { "value": "{{resolved.scope_description}}" }
  }
}

// Response — store document_id and view_link
{ "id": "<document_id>", "view_link": "https://app.pandadoc.com/..." }

Read-only source of pricing tier rules, discount thresholds, and product configurations. The Proposal Assembly Agent reads the canonical pricing sheet each time a proposal is triggered, ensuring the latest approved rates are always used. Write access is not required. Estimated integration complexity: Simple.

// GET https://sheets.googleapis.com/v4/spreadsheets/{GOOGLE_PRICING_SHEET_ID}/values/{GOOGLE_PRICING_NAMED_RANGE}
// Headers: Authorization: Bearer <service_account_access_token>

// Expected response structure
{
  "values": [
    ["tier_name", "min_value", "max_value", "base_price", "max_discount_pct", "scope_description"],
    ["Starter",   "0",         "4999",      "1200",       "10",              "Core package..."],
    ["Growth",    "5000",       "14999",     "2800",       "15",              "Full suite..."],
    ["Enterprise","15000",      "999999",    "5500",       "20",              "Custom scope..."]
  ]
}

Hosts the manager approval interaction. The Approval and Delivery Agent posts a structured Block Kit message to the designated approval channel containing a deal summary, the PandaDoc preview link, and two interactive buttons: Approve and Request Changes. The platform listens for the interactive payload on the configured interactivity endpoint. Estimated integration complexity: Moderate.

// POST https://slack.com/api/chat.postMessage
{
  "channel": "{{SLACK_APPROVAL_CHANNEL_ID}}",
  "text": "Proposal ready for approval: {{deal.dealname}}",
  "blocks": [
    { "type": "section", "text": { "type": "mrkdwn",
      "text": "*<@{{SLACK_MANAGER_USER_ID}}>* — proposal ready for {{contact.firstname}} {{contact.lastname}} ({{company.name}})\nDeal value: ${{deal.amount}} | Tier: {{resolved.pricing_tier}}\n<{{pandadoc.view_link}}|Preview proposal>" }
    },
    { "type": "actions", "elements": [
      { "type": "button", "text": { "type": "plain_text", "text": "Approve" },
        "style": "primary", "action_id": "proposal_approve", "value": "{{deal.hs_object_id}}" },
      { "type": "button", "text": { "type": "plain_text", "text": "Request Changes" },
        "style": "danger",  "action_id": "proposal_changes", "value": "{{deal.hs_object_id}}" }
    ]}
  ]
}

// Inbound interactive payload (button click)
{ "payload": { "type": "block_actions", "actions": [{ "action_id": "proposal_approve|proposal_changes", "value": "<deal_id>" }], "user": { "id": "<slack_user_id>" } } }

Delivers the approved PandaDoc proposal link to the prospect via a personalised email. The Approval and Delivery Agent composes the message using a pre-approved template, substitutes prospect and deal variables, and sends via the Gmail API. Estimated integration complexity: Simple.

// POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
// Headers: Authorization: Bearer <access_token>
{
  "raw": "<base64url-encoded RFC 2822 message>"
}

// Decoded message structure
From: {{GMAIL_SENDER_DISPLAY_NAME}} <{{GMAIL_SENDER_ADDRESS}}>
To: {{contact.email}}
Subject: Your proposal from [YourCompany.com] — {{company.name}}
Content-Type: text/html

Hi {{contact.firstname}},
Please find your tailored proposal here: {{pandadoc.view_link}}
This proposal is valid until {{resolved.expiry_date}}.
...

# ============================================================
# CREDENTIAL STORE — Proposal Creation Automation
# All values stored as encrypted secrets. Never log or expose.
# ============================================================

# HubSpot
HUBSPOT_PRIVATE_APP_TOKEN          # HubSpot Private App — API auth for all CRM reads and writes
HUBSPOT_WEBHOOK_CLIENT_SECRET      # HubSpot app client secret — HMAC-SHA256 webhook signature validation
HUBSPOT_PIPELINE_ID                # Internal ID of the sales pipeline containing the target stages
HUBSPOT_STAGE_ID_PROPOSAL_REQUESTED  # Deal stage ID for 'Proposal Requested'
HUBSPOT_STAGE_ID_PROPOSAL_SENT       # Deal stage ID for 'Proposal Sent'

# PandaDoc
PANDADOC_API_KEY                   # PandaDoc API key — Bearer token for document create and read
PANDADOC_TEMPLATE_ID               # UUID of the master proposal template in PandaDoc
PANDADOC_WEBHOOK_SECRET            # Shared secret for verifying inbound PandaDoc webhook signatures

# Google Sheets (service account)
GOOGLE_SERVICE_ACCOUNT_JSON        # Full JSON key file contents for the Google service account
GOOGLE_PRICING_SHEET_ID            # Spreadsheet ID from the pricing sheet URL
GOOGLE_PRICING_TAB_NAME            # Exact tab name containing the pricing table (e.g. 'Pricing_v2')
GOOGLE_PRICING_NAMED_RANGE         # Named range for the pricing data table

# Slack
SLACK_BOT_TOKEN                    # Bot User OAuth Token (xoxb-) — post messages and handle interactions
SLACK_SIGNING_SECRET               # App signing secret — validate interactive payload signatures
SLACK_APPROVAL_CHANNEL_ID          # Channel ID for the manager approval messages
SLACK_MANAGER_USER_ID              # Slack user ID of the sales manager for @mention
SLACK_ALERT_CHANNEL_ID             # Channel ID for automation error and alert notifications

# Gmail
GMAIL_CLIENT_ID                    # OAuth 2.0 client ID for Gmail API
GMAIL_CLIENT_SECRET                # OAuth 2.0 client secret for Gmail API
GMAIL_OAUTH_REFRESH_TOKEN          # Long-lived refresh token for the sending Gmail account
GMAIL_SENDER_ADDRESS               # Full email address of the sending account
GMAIL_SENDER_DISPLAY_NAME          # Display name shown in the From field to the prospect