Integration and API Spec

Integration and API Spec

Proposal & SOW Creation

Acts as the automation trigger. When a deal's lifecycle stage is set to a configured value (e.g., 'Scoping Call Complete'), FullSpec Automation reads the associated note body, deal properties, and contact record to seed the Scope Extraction Agent.

// Inbound trigger payload (HubSpot webhook)
{
  "objectId": "<dealId>",
  "objectType": "DEAL",
  "propertyName": "dealstage",
  "propertyValue": "Scoping Call Complete",
  "occurredAt": "<ISO8601 timestamp>"
}

// Data fetched after trigger
deal.dealname, deal.amount, deal.closedate,
deal.hubspot_owner_id, note.hs_note_body,
contact.email, contact.firstname, contact.lastname,
company.name, company.domain

Hosts the proposal and SOW templates. The Estimate & Proposal Agent creates a copy of each master template in the designated output Drive folder, performs field substitution via the Docs API, and returns the resulting document URLs for downstream handoff to PandaDoc.

// Copy template call
POST /drive/v3/files/{{GDOCS_PROPOSAL_TEMPLATE_ID}}/copy
Body: { "name": "Proposal - {{company_name}} - {{today_date}}" }

// batchUpdate replaceAllText request
{
  "requests": [
    { "replaceAllText": { "containsText": { "text": "{{CLIENT_NAME}}" }, "replaceText": "<company.name>" } },
    { "replaceAllText": { "containsText": { "text": "{{TOTAL_PRICE}}" }, "replaceText": "<calculated_total>" } }
  ]
}

// Output
{ "documentId": "<newDocId>", "webViewLink": "https://docs.google.com/document/d/<newDocId>/edit" }

Receives the approved proposal as a Google Docs URL or uploaded PDF, creates a PandaDoc document with pre-filled recipient details, sends it for e-signature, and exposes webhook events for open and signed status back into FullSpec Automation.

// Create document from Google Docs URL
POST /public/v1/documents
{
  "name": "Proposal - {{company_name}}",
  "url": "<gdocs_export_pdf_url>",
  "recipients": [{ "email": "<contact.email>", "first_name": "<contact.firstname>", "last_name": "<contact.lastname>", "role": "Signer" }],
  "fields": { "client_name": { "value": "<company.name>" } }
}

// Send document
POST /public/v1/documents/{documentId}/send
{
  "message": "Please review and sign the attached proposal.",
  "subject": "Your Proposal from [YourCompany.com]"
}

// Inbound webhook payload (state change)
{
  "event": "document.state_changed",
  "data": { "id": "<docId>", "status": "completed", "date_completed": "<ISO8601>" }
}

// n8n Credential Store -- required entries
// (Settings > Credentials > New Credential)

credential: HubSpot_PrivateApp_Token
  type:   hubspotApi
  field:  apiKey = <HubSpot private app token>
  scope:  crm.objects.deals.read, crm.objects.contacts.read,
          crm.objects.notes.read, crm.objects.companies.read,
          timeline.write

credential: Google_ServiceAccount_Docs
  type:   googleServiceAccount
  field:  serviceAccountEmail = automation@<project>.iam.gserviceaccount.com
  field:  privateKey           = <PEM key from JSON key file>
  scope:  https://www.googleapis.com/auth/drive
          https://www.googleapis.com/auth/documents
          https://www.googleapis.com/auth/drive.file

credential: PandaDoc_ApiKey
  type:   httpHeaderAuth
  field:  name  = Authorization
  field:  value = API-Key <pandadoc_api_key>

credential: FullSpec_Internal_ApiKey
  type:   httpHeaderAuth
  field:  name  = X-FullSpec-Key
  field:  value = <fullspec_service_account_key>

// Environment variables (set in FullSpec > Settings > Variables)
HUBSPOT_TRIGGER_STAGE     = Scoping Call Complete
HUBSPOT_NOTES_FIELD       = hs_note_body
GDOCS_PROPOSAL_TEMPLATE_ID = <google_doc_file_id_proposal>
GDOCS_SOW_TEMPLATE_ID      = <google_doc_file_id_sow>
GDOCS_OUTPUT_FOLDER_ID     = <google_drive_folder_id>
PANDADOC_SENDER_EMAIL      = proposals@[YourCompany.com]
PANDADOC_TEMPLATE_ID       = <pandadoc_template_id_if_used>
RATE_CARD_VERSION          = v2.1
ALERT_EMAIL                = owner@[YourCompany.com]