Integration and API Spec

Integration and API Spec

Insurance Renewal Management

Notion serves as the system of record for all policy data. The automation reads expiry dates on a daily schedule, writes renewal status updates throughout the workflow, and performs a final record update when the Approval and Completion Agent closes a renewal cycle.

// Poll query (daily)
GET /v1/databases/{NOTION_POLICY_DB_ID}/query
  Body: { filter: { property: 'Expiry Date', date: { on_or_before: '<today+90d>' } } }

// Update record on renewal completion
PATCH /v1/pages/{page_id}
  Body: { properties: { 'Renewal Status': 'Renewed', 'Next Renewal Date': '<date>', 'Xero Bill ID': '<id>', 'DocuSign Envelope ID': '<id>' } }

Gmail handles all outbound broker communication and inbound quote intake. Google Drive stores policy documents and quote files, with Drive file URLs referenced back to the Notion policy record. Two distinct Gmail operations are required: sending from a designated service address and reading an intake mailbox for incoming broker quotes.

// Send broker outreach email
POST /gmail/v1/users/{GMAIL_DELEGATE_ADDRESS}/messages/send
  Body: RFC 2822 message, To: {broker_email}, Subject: 'Renewal Request: {policy_name} - Expiry {expiry_date}'

// Poll intake inbox for quote attachments
GET /gmail/v1/users/{GMAIL_INTAKE_ADDRESS}/messages?q=has:attachment+is:unread+label:inbox
  Then: GET /gmail/v1/users/{userId}/messages/{messageId} to fetch attachment metadata
  Then: GET /gmail/v1/users/{userId}/messages/{messageId}/attachments/{attachmentId}

HubSpot tracks broker outreach activity and manages the automatic chase sequence. Each broker is treated as a Contact record. Outreach events are logged as Engagements. A custom property on the Contact records the last outreach date and current chase status, enabling the Renewal Tracker Agent to determine when a follow-up is due.

// Log outreach engagement
POST /crm/v3/objects/contacts/{contact_id}/associations
POST /engagements/v1/engagements
  Body: { engagement: { type: 'EMAIL', timestamp: <epoch_ms> }, metadata: { subject: 'Renewal outreach: {policy_name}', body: '<email body snippet>' } }

// Update chase status property
PATCH /crm/v3/objects/contacts/{contact_id}
  Body: { properties: { renewal_chase_status: 'Chase 1 Sent', last_renewal_outreach_date: '<ISO date>' } }

Slack receives two categories of automated message: expiry and outreach status notifications from the Renewal Tracker Agent, and the structured quote comparison summary from the Quote Comparison Agent. Messages are posted to a designated compliance channel. Exception flags (material coverage changes) use Slack's Block Kit to make the alert visually distinct.

// Post comparison summary
POST https://slack.com/api/chat.postMessage
  Headers: Authorization: Bearer {SLACK_BOT_TOKEN}
  Body: { channel: '{SLACK_COMPLIANCE_CHANNEL_ID}', blocks: [ { type: 'section', text: { type: 'mrkdwn', text: '*Renewal Summary: {policy_name}*\nPremium delta: {delta}%\nCoverage flags: {flags}' } } ] }

// Exception flag (material change detected)
  Add block: { type: 'section', text: { type: 'mrkdwn', text: ':warning: *Material coverage change detected. Human review required before DocuSign is triggered.*' } }

DocuSign manages the formal approval envelope sent to the CFO or designated approver. The envelope contains the comparison summary document and the broker quote. On completion, DocuSign fires a Connect webhook to the orchestration layer, which triggers the broker acceptance email and the Xero bill creation step.

// Create and send envelope
POST {DOCUSIGN_ACCOUNT_BASE_URI}/v2.1/accounts/{account_id}/envelopes
  Body: { templateId: '{DOCUSIGN_TEMPLATE_ID}', templateRoles: [ { email: '{approver_email}', name: '{approver_name}', roleName: 'Approver' } ], status: 'sent', documents: [ { documentBase64: '<base64_summary>', name: 'Comparison Summary - {policy_name}.pdf', documentId: '1' } ] }

// Inbound Connect event validation
POST /webhooks/docusign-connect
  Validate: HMAC-SHA256( DOCUSIGN_CONNECT_HMAC_KEY, raw_body ) == X-DocuSign-Signature-1
  On match and status == 'completed': extract envelopeId, trigger downstream steps

Xero receives a draft bill creation request once DocuSign sign-off is confirmed. The bill is assigned to the correct supplier (insurer) and account code. No payment is initiated by the automation; the draft bill enters the standard Xero accounts payable review queue for the Accounts Manager.

// Create draft bill
POST https://api.xero.com/api.xro/2.0/Invoices
  Headers: Authorization: Bearer {access_token}, Xero-tenant-id: {XERO_TENANT_ID}
  Body: { Type: 'ACCPAY', Contact: { ContactID: '{XERO_CONTACT_IDS[insurer_name]}' }, Date: '<invoice_date>', DueDate: '<due_date>', Status: 'DRAFT',
    LineItems: [ { Description: 'Insurance premium: {policy_name} ({coverage_type})', Quantity: 1, UnitAmount: {premium_amount}, AccountCode: '{XERO_INSURANCE_ACCOUNT_CODE}' } ] }

// Credential store: all keys required before go-live

// Notion
NOTION_API_TOKEN=<internal_integration_token>
NOTION_POLICY_DB_ID=<database_guid>

// Google Workspace
GMAIL_SERVICE_ACCOUNT_KEY_JSON=<base64_encoded_service_account_json>
GMAIL_DELEGATE_ADDRESS=renewals@[YourCompany.com]
GMAIL_INTAKE_ADDRESS=renewals@[YourCompany.com]
GDRIVE_QUOTE_FOLDER_ID=<drive_folder_id>
GDRIVE_OUTREACH_TEMPLATE_ID=<google_doc_id>
GDRIVE_ACCEPTANCE_TEMPLATE_ID=<google_doc_id>
GCLOUD_PUBSUB_TOPIC=<projects/{project_id}/topics/{topic_name}>

// HubSpot
HUBSPOT_PRIVATE_APP_TOKEN=<hubspot_pat>
HUBSPOT_PORTAL_ID=<portal_id>
HUBSPOT_CHASE_STATUS_PROP=renewal_chase_status
HUBSPOT_OUTREACH_DATE_PROP=last_renewal_outreach_date

// Slack
SLACK_BOT_TOKEN=xoxb-<token>
SLACK_COMPLIANCE_CHANNEL_ID=C<channel_id>
SLACK_WORKSPACE_ID=T<workspace_id>

// DocuSign
DOCUSIGN_INTEGRATION_KEY=<client_id_guid>
DOCUSIGN_RSA_PRIVATE_KEY=<base64_pem_private_key>
DOCUSIGN_USER_GUID=<impersonated_user_guid>
DOCUSIGN_ACCOUNT_BASE_URI=https://na4.docusign.net  // or regional URI from /oauth/userinfo
DOCUSIGN_TEMPLATE_ID=<envelope_template_guid>
DOCUSIGN_CONNECT_HMAC_KEY=<connect_hmac_secret>

// Xero
XERO_CLIENT_ID=<oauth_client_id>
XERO_CLIENT_SECRET=<oauth_client_secret>
XERO_REFRESH_TOKEN=<refresh_token>  // must be updated on each refresh
XERO_TENANT_ID=<organisation_guid>
XERO_INSURANCE_ACCOUNT_CODE=<e.g. 625>
XERO_CONTACT_IDS={"Insurer A": "<xero_contact_guid>", "Insurer B": "<xero_contact_guid>"}

// Inbound webhook endpoint (hosted by orchestration layer)
DOCUSIGN_CONNECT_INBOUND_URL=https://<orchestration_host>/webhooks/docusign-connect
GMAIL_PUBSUB_PUSH_ENDPOINT=https://<orchestration_host>/webhooks/gmail-intake