Integration and API Spec

Integration and API Spec

Renewal and Contract Expiry Management

Used by Agent 1 (Contract Monitoring Agent) to scan deal records for expiry dates, enrich contract data, and write the prioritised outreach queue. Used by Agent 2 (Renewal Outreach Agent) to log sent emails and update sequence stage flags on deal records. Used by Agent 3 (Approval and Closing Agent) to move deals to the Renewed stage and write new contract dates post-signature.

// Input (Agent 1 scan)
GET /crm/v3/objects/deals?limit=100&properties=contract_expiry_date,dealname,amount,hubspot_owner_id,contract_value_usd,assigned_account_manager_email,renewal_sequence_stage&filterGroups=[{filters:[{propertyName:'contract_expiry_date',operator:'LTE',value:'TODAY+90'},{propertyName:'renewal_sequence_stage',operator:'NEQ',value:'renewed'}]}]

// Output (Agent 2 activity log)
POST /crm/v3/objects/deals/{dealId}/associations/emails
PATCH /crm/v3/objects/deals/{dealId} { properties: { renewal_sequence_stage: 'day90_sent' } }

Used exclusively by Agent 2 (Renewal Outreach Agent) to send staged personalised renewal emails from each account manager's individual Gmail address, and to monitor for client replies so that the sequence can be paused automatically.

// Input (reply detection)
Pub/Sub message -> fetch GET /gmail/v1/users/{userId}/messages/{messageId}?format=metadata
Check headers: In-Reply-To matches open renewal threadId

// Output (send renewal email)
POST /gmail/v1/users/{userId}/messages/send
{ raw: base64url(MIME message with template populated, thread headers set) }

Used by Agent 3 (Approval and Closing Agent) to generate a renewal contract from a pre-built template, send it to the client contact for electronic signature, and receive a signed status webhook that triggers the HubSpot and Xero post-signature updates.

// Input (create and send envelope from template)
POST /restapi/v2.1/accounts/{DOCUSIGN_ACCOUNT_ID}/envelopes
{ templateId: DOCUSIGN_RENEWAL_TEMPLATE_ID, templateRoles: [{ email, name, roleName:'Client', tabs:{...} }], status: 'sent' }

// Output (webhook on completion)
POST {orchestration_webhook_endpoint}
Header: X-DocuSign-Signature-1: {hmac_sha256_hex}
Body: { envelopeId, status:'completed', completedDateTime, recipients:[{ email, signedDateTime }] }

Used by Agent 3 (Approval and Closing Agent) to deliver structured daily renewal summaries to account managers and to route approval requests to the sales manager with interactive approve or decline buttons. Approval responses from Slack trigger the DocuSign send step.

// Output (approval request to sales manager)
POST https://slack.com/api/chat.postMessage
{ channel: SLACK_APPROVER_USER_ID, blocks: [ section(deal_name, contract_value, expiry_date), actions([ button('Approve', value: deal_id), button('Decline', value: deal_id) ]) ] }

// Input (interaction callback)
POST {orchestration_interaction_endpoint}
Header: X-Slack-Signature, X-Slack-Request-Timestamp
Body: payload={ type:'block_actions', actions:[{ action_id:'approve'|'decline', value: deal_id }], user:{ id, name } }

Used by Agent 3 (Approval and Closing Agent) to create a recurring invoice in the correct Xero account when DocuSign returns a signed envelope status. The invoice is matched to the client contact and a pre-configured renewal product line item.

// Input (create invoice)
POST https://api.xero.com/api.xro/2.0/Invoices
Header: Xero-tenant-id: {XERO_TENANT_ID}, Authorization: Bearer {XERO_ACCESS_TOKEN}
Body: { Type:'ACCREC', Contact:{ ContactID: resolved_contact_id }, LineItems:[{ ItemCode: XERO_RENEWAL_ITEM_CODE, Quantity:1, UnitAmount: deal_value }], DueDate: contract_start_date+14d, Reference: hubspot_deal_id }

// Output
{ InvoiceID, InvoiceNumber, Status:'AUTHORISED', AmountDue, DueDate }

Used by Agent 1 (Contract Monitoring Agent) to write the daily prioritised renewal queue as a structured sheet that account managers can review at a glance. The sheet acts as a read-only summary output; the CRM remains the source of truth.

// Output (daily queue write)
POST https://sheets.googleapis.com/v4/spreadsheets/{GOOGLE_SHEET_RENEWAL_QUEUE_ID}/values/RenewalQueue!A2:H{n}:clear
POST https://sheets.googleapis.com/v4/spreadsheets/{GOOGLE_SHEET_RENEWAL_QUEUE_ID}/values/RenewalQueue!A2:H{n}?valueInputOption=USER_ENTERED
Body: { values: [ [deal_id, client_name, expiry_date, days_remaining, contract_value, account_manager, sequence_stage, last_activity_date], ... ] }

// Credential store contents
// HubSpot
HUBSPOT_PRIVATE_APP_TOKEN        = 'pat-na1-...'
HUBSPOT_PORTAL_ID                = '12345678'

// Gmail (per account manager; repeat pattern for each user)
GMAIL_ACCESS_TOKEN_AM1           = 'ya29...'
GMAIL_REFRESH_TOKEN_AM1          = '1//0e...'
GMAIL_ACCESS_TOKEN_AM2           = 'ya29...'
GMAIL_REFRESH_TOKEN_AM2          = '1//0e...'

// Gmail email templates (stored as config, not code)
RENEWAL_TEMPLATE_90D             = '<template string with {{placeholders}}'
RENEWAL_TEMPLATE_60D             = '<template string with {{placeholders}}'
RENEWAL_TEMPLATE_30D             = '<template string with {{placeholders}}'

// DocuSign
DOCUSIGN_INTEGRATION_KEY         = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
DOCUSIGN_PRIVATE_KEY             = '-----BEGIN RSA PRIVATE KEY-----\n...'
DOCUSIGN_IMPERSONATION_USER_GUID = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
DOCUSIGN_ACCOUNT_ID              = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
DOCUSIGN_RENEWAL_TEMPLATE_ID     = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
DOCUSIGN_CONNECT_HMAC_SECRET     = 'abc123...'

// Slack
SLACK_BOT_TOKEN                  = 'xoxb-...'
SLACK_SIGNING_SECRET             = 'abc123...'
SLACK_APPROVER_USER_ID           = 'U0123456789'
SLACK_RENEWALS_CHANNEL_ID        = 'C0123456789'

// Xero
XERO_ACCESS_TOKEN                = 'eyJ...'
XERO_REFRESH_TOKEN               = 'abc123...'
XERO_TENANT_ID                   = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
XERO_RENEWAL_ITEM_CODE           = 'RENEWAL-STD'
XERO_WEBHOOK_KEY                 = 'abc123...'

// Google Sheets
GOOGLE_SERVICE_ACCOUNT_KEY       = '{ "type": "service_account", ... }'
GOOGLE_SHEET_RENEWAL_QUEUE_ID    = '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms'