Integration and API Spec

Integration and API Spec

Contractor and Freelancer Management

Used by both agents as the system of record for contractor profiles, agreed rates, milestone data, and invoice approval decisions. Agent 1 creates and updates contact records. Agent 2 reads rate data and writes approval outcomes.

// Input (Agent 1)
POST /crm/v3/objects/contacts
{ firstname, lastname, email, phone, contractor_type, agreed_rate_usd, hs_lifecycle_stage: 'contractor' }

// Input (Agent 2 — read)
GET /crm/v3/objects/contacts/{contactId}?properties=agreed_rate_usd,compliance_status,invoice_approval_status

// Output (Agent 2 — write approval result)
PATCH /crm/v3/objects/contacts/{contactId}
{ invoice_approval_status: 'approved' | 'queried', last_invoice_amount_usd: <number> }

Used by Agent 1 to send the correct contractor agreement template, monitor envelope status, and confirm completion. Envelope completion triggers the Gusto payee creation step.

// Input — send envelope
POST /restapi/v2.1/accounts/{accountId}/envelopes
{ templateId, templateRoles: [{ roleName: 'Contractor', name, email, tabs: { textTabs: [ contractor_full_name, agreed_rate_usd, engagement_start_date ] } }], status: 'sent' }

// Inbound webhook payload (Connect)
{ envelopeId, status: 'completed' | 'declined' | 'voided', completedDateTime, recipientStatuses: [ ... ] }

// Output — envelope ID stored to HubSpot
PATCH /crm/v3/objects/contacts/{contactId} { docusign_envelope_id: <envelopeId> }

Used by Agent 1 to create contractor-specific folders, file compliance documents submitted by contractors, and apply a timestamped naming convention for audit purposes.

// Input — create contractor subfolder
POST https://www.googleapis.com/drive/v3/files
{ name: '{contractor_id}', mimeType: 'application/vnd.google-apps.folder', parents: [GDRIVE_ROOT_FOLDER_ID] }

// Input — move and rename filed document
PATCH https://www.googleapis.com/drive/v3/files/{fileId}
{ name: '{YYYY-MM-DD}_{contractor_id}_{document_type}', addParents: '{complianceFolderId}', removeParents: '{intakeFolderId}' }

// Output — file metadata stored to HubSpot contact note
{ gdrive_file_id, gdrive_file_url, filed_at_utc, document_type }

Used by both agents for internal HR alerts (document chase notifications, onboarding status) and for invoice approval routing with interactive approve/query buttons delivered to the approving manager.

// Input — HR alert (document chase)
POST https://slack.com/api/chat.postMessage
{ channel: SLACK_HR_CHANNEL_ID, text: 'Reminder: {contractor_name} has not submitted {missing_docs}. Day {n} of chase sequence.' }

// Input — invoice approval Block Kit message
{ channel: '{manager_slack_user_id}', blocks: [ section(contractor_name, invoice_amount_usd, due_date), actions([ { type: 'button', action_id: 'invoice_approve', text: 'Approve' }, { type: 'button', action_id: 'invoice_query', text: 'Query', style: 'danger' } ]) ] }

// Inbound action payload
{ action_id: 'invoice_approve' | 'invoice_query', value: { contractor_id, hubspot_contact_id, invoice_amount_usd, xero_draft_bill_id } }

Used by Agent 2 to create approved contractor bills, assign expense categories, attach the invoice PDF, and schedule the payment run.

// Input — create bill (ACCPAY invoice)
POST https://api.xero.com/api.xro/2.0/Invoices
{ Type: 'ACCPAY', Contact: { ContactID: xero_contact_id }, Date: today_iso, DueDate: today_plus_XERO_PAYMENT_DUE_DAYS, LineItems: [ { Description: invoice_description, Quantity: 1, UnitAmount: invoice_amount_usd, AccountCode: XERO_CONTRACTOR_ACCOUNT_CODE } ], Status: 'AUTHORISED' }

// Input — attach PDF
POST https://api.xero.com/api.xro/2.0/Invoices/{InvoiceID}/Attachments/{filename}
Content-Type: application/pdf  |  body: <pdf binary>

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

Used by Agent 1 to create the contractor as a payee after DocuSign completion, and by Agent 2 to optionally trigger a payment run once the Xero bill is authorised.

// Input — create contractor payee
POST /v1/companies/{GUSTO_COMPANY_UUID}/contractors
{ type: 'Individual', first_name, last_name, email, start_date }

// Input — add bank account (separate call)
POST /v1/contractors/{contractorUuid}/bank_accounts
{ routing_number, account_number, account_type: 'Checking' | 'Savings' }

// Output
{ uuid: gusto_contractor_uuid, email, start_date, payment_method: 'Direct Deposit' }

# Credential Store — all values injected as environment variables at runtime
# Never log, print, or hardcode any of these values

# HubSpot
HUBSPOT_API_TOKEN=<private-app-token>
HUBSPOT_WEBHOOK_CLIENT_SECRET=<app-client-secret-for-signature-validation>

# DocuSign
DOCUSIGN_INTEGRATION_KEY=<integration-key-uuid>
DOCUSIGN_RSA_PRIVATE_KEY=<rsa-private-key-pem>
DOCUSIGN_ACCOUNT_ID=<docusign-account-uuid>
DOCUSIGN_BASE_URI=https://na4.docusign.net
DOCUSIGN_IMPERSONATION_USER_ID=<admin-user-guid>
DOCUSIGN_CONNECT_HMAC_KEY=<connect-webhook-hmac-key>
DOCUSIGN_TEMPLATE_ID_STANDARD=<template-uuid>
DOCUSIGN_TEMPLATE_ID_NDA_ONLY=<template-uuid>

# Google Drive
GOOGLE_SERVICE_ACCOUNT_JSON=<json-key-file-contents>
GDRIVE_ROOT_FOLDER_ID=<folder-id>
GDRIVE_INTAKE_FOLDER_ID=<folder-id>

# Slack
SLACK_BOT_TOKEN=xoxb-<token>
SLACK_SIGNING_SECRET=<signing-secret>
SLACK_HR_CHANNEL_ID=<channel-id>
SLACK_FINANCE_CHANNEL_ID=<channel-id>

# Xero
XERO_CLIENT_ID=<client-id>
XERO_CLIENT_SECRET=<client-secret>
XERO_ACCESS_TOKEN=<short-lived-token>          # refreshed at runtime
XERO_REFRESH_TOKEN=<60-day-rolling-token>
XERO_TENANT_ID=<organisation-uuid>
XERO_CONTRACTOR_ACCOUNT_CODE=200
XERO_PAYMENT_DUE_DAYS=14

# Gusto
GUSTO_CLIENT_ID=<client-id>
GUSTO_CLIENT_SECRET=<client-secret>
GUSTO_ACCESS_TOKEN=<access-token>              # refreshed every 2 hours
GUSTO_REFRESH_TOKEN=<refresh-token>
GUSTO_COMPANY_UUID=<company-uuid>