Integration and API Spec

Integration and API Spec

Contractor Management Automation

Trigger source for Agent 1. The form captures all contractor onboarding fields. The orchestration layer polls or receives a webhook push from the Google Forms / Google Sheets response sheet on each new submission.

// Input
New row in Google Sheets response sheet
// Key fields extracted
contractor_name, contractor_email, abn_or_tax_id,
agreed_rate_usd, engagement_start_date, engagement_end_date,
document_insurance_expiry, document_wwcc_expiry,
bank_bsb, bank_account_number,
file_upload_insurance_cert (Drive URL), file_upload_wwcc (Drive URL)
// Output
Structured JSON object passed to Agent 1 processing steps

Central contractor database used by all three agents. Agent 1 creates records; Agent 2 reads agreed rate and updates payment status; Agent 3 reads expiry date fields to determine alert eligibility.

// Agent 1 Input (create record)
contractor_name, contractor_email, abn_or_tax_id, agreed_rate_usd,
engagement_start_date, engagement_end_date, drive_folder_url,
xero_supplier_id, document_insurance_expiry, document_wwcc_expiry
// Agent 2 Input (read + update)
GET record by contractor_email -> agreed_rate_usd
PATCH record -> fld_payment_status = 'Bill Created' | 'Pending Review'
// Agent 3 Input (read for daily poll)
GET records WHERE document_insurance_expiry <= TODAY+30
  OR document_wwcc_expiry <= TODAY+30
// Output
Record ID returned on create (stored for subsequent PATCH calls)

Compliance document storage used by Agent 1. Files submitted via Google Forms are moved or copied into a named contractor folder. Folder URL is written back to Airtable.

// Input
file_upload_insurance_cert (Google Drive file ID from Forms response)
file_upload_wwcc (Google Drive file ID from Forms response)
contractor_name, engagement_start_date
// Actions
1. Create folder: {contractor_name}_{engagement_start_date} under GDRIVE_CONTRACTORS_ROOT_FOLDER_ID
2. Copy file insurance_cert to new folder, rename to {contractor_name}_InsuranceCert_{expiry}
3. Copy file wwcc to new folder, rename to {contractor_name}_WWCC_{expiry}
// Output
drive_folder_url -> passed to Airtable record write (fld_drive_folder_url)

Used by Agent 1 to create a supplier (contact) record and by Agent 2 to create a bill once an invoice is approved. Requires an OAuth 2.0 connection authorised by the Finance Manager.

// Agent 1: Create Supplier
POST /api.xro/2.0/Contacts
Body: { Name: contractor_name, EmailAddress: contractor_email,
  BankAccountDetails: bank_bsb + '-' + bank_account_number,
  TaxNumber: abn_or_tax_id }
Response: ContactID -> stored to Airtable fld_airtable_xero_supplier_id

// Agent 2: Create Bill
POST /api.xro/2.0/Invoices
Body: { Type: 'ACCPAY', Contact: { ContactID: xero_supplier_id },
  Date: invoice_date, DueDate: invoice_date + XERO_BILL_DUE_DAYS,
  LineItems: [{ Description: invoice_description,
    UnitAmount: invoice_amount, AccountCode: XERO_EXPENSE_ACCOUNT_CODE }],
  Status: 'AUTHORISED' }
Response: InvoiceID -> stored to Airtable fld_payment_status = 'Bill Created'

Used by Agents 1, 2, and 3 for team notifications, invoice approval routing with interactive buttons, and compliance expiry alerts. Requires a Slack App with bot token and interactive components enabled.

// Agent 1: Team notification
POST chat.postMessage
channel: SLACK_CHANNEL_CONTRACTORS
blocks: [ text: 'New contractor active: {contractor_name}',
  fields: [Start: engagement_start_date, Rate: agreed_rate_usd,
           Hiring Manager: hiring_manager_name] ]

// Agent 2: Invoice approval request
POST chat.postMessage
channel: SLACK_APPROVER_USER_ID (DM)
blocks: [ text: 'Invoice approval required: {contractor_name} - ${invoice_amount}',
  actions: [ { type: button, text: 'Approve', action_id: 'approve_invoice_{invoice_id}' },
             { type: button, text: 'Query',   action_id: 'query_invoice_{invoice_id}'  } ] ]

// Agent 3: Compliance expiry alert
POST chat.postMessage
channel: SLACK_CHANNEL_COMPLIANCE
blocks: [ text: '{contractor_name} - {document_type} expires in {days_remaining} days.',
  text: 'Re-upload link: {drive_reupload_url}' ]

# Google Workspace
GOOGLE_OAUTH_CLIENT_ID          = '<from Google Cloud Console>'
GOOGLE_OAUTH_CLIENT_SECRET      = '<from Google Cloud Console>'
GOOGLE_OAUTH_REFRESH_TOKEN      = '<generated after consent flow>'
GFORMS_RESPONSE_SHEET_ID        = '<Google Sheet ID from Forms response link>'
GDRIVE_CONTRACTORS_ROOT_FOLDER_ID = '<Drive folder ID for contractor docs>'

# Airtable
AIRTABLE_PAT                    = '<Personal Access Token from airtable.com/account>'
AIRTABLE_BASE_ID                = '<from Airtable API docs for target base>'
AIRTABLE_TABLE_CONTRACTORS      = '<Table ID, not display name>'

# Xero
XERO_CLIENT_ID                  = '<from Xero Developer portal>'
XERO_CLIENT_SECRET              = '<from Xero Developer portal>'
XERO_ACCESS_TOKEN               = '<refreshed automatically; bootstrap manually>'
XERO_REFRESH_TOKEN              = '<60-day rolling token>'
XERO_TENANT_ID                  = '<Xero organisation tenant ID>'
XERO_PAYMENT_ACCOUNT_ID         = '<Bank account ID from GET /BankAccounts>'
XERO_EXPENSE_ACCOUNT_CODE       = '600'  # confirm with Finance Manager
XERO_DEFAULT_CURRENCY           = 'USD'
XERO_BILL_DUE_DAYS              = 14
XERO_TAX_TYPE                   = 'NONE'  # or TAX001 if GST applies
XERO_WEBHOOK_KEY                = '<webhook signing key if Xero webhooks enabled>'

# Slack
SLACK_BOT_TOKEN                 = '<Bot User OAuth Token from Slack App settings>'
SLACK_SIGNING_SECRET            = '<Signing secret from Slack App Basic Information>'
SLACK_CHANNEL_CONTRACTORS       = '<channel ID, e.g. C0123456789>'
SLACK_CHANNEL_INVOICES          = '<channel ID for invoice routing>'
SLACK_CHANNEL_COMPLIANCE        = '<channel ID for compliance alerts>'
SLACK_APPROVER_USER_ID          = '<Slack user ID of Hiring Manager approver>'

# Orchestration
WEBHOOK_INBOUND_SECRET          = '<HMAC secret for validating inbound webhook calls>'
INVOICE_INBOX_EMAIL             = 'invoices@[YourCompany.com]'
INVOICE_INBOX_IMAP_PASSWORD     = '<app password for IMAP access>'
COMPLIANCE_ALERT_LEAD_DAYS      = 30
APPROVAL_TIMEOUT_HOURS          = 4