Integration and API Spec

Integration and API Spec

Payroll Processing Automation

REST API v2. Used by the Timesheet Collection Agent (Agent 1) to retrieve approved shift records for the closed pay period, and by the Reconciliation Agent (Agent 2) to cross-reference scheduled versus worked hours.

// Endpoint used
GET /api/v2/resource/Timesheet
  ?search={"select":["EmployeeId","Date","StartTime","EndTime","TotalTime","ApprovalStatus","LeaveId"]}
  &search={"where":[{"field":"Date","type":"ge","data":"{{period_start}}"}]}
// Output fields consumed downstream
timesheet.EmployeeId -> maps to EMPLOYEE_ID_MAP[deputy_employee_id]
timesheet.TotalTime  -> gross_hours (decimal hours)
timesheet.LeaveId    -> leave_flag (boolean, non-null = leave applied)
timesheet.ApprovalStatus -> filter: pass only 'Approved'

Slack Web API (Bot). Used by Agent 1 to post exception reports to the finance channel when missing or unapproved timesheets are found, and by Agent 3 to post the final payroll confirmation message after Gusto submission.

// Exception report message (Agent 1)
POST https://slack.com/api/chat.postMessage
{
  "channel": "{{SLACK_FINANCE_CHANNEL_ID}}",
  "text": "Payroll exception report — {{period_label}}",
  "blocks": [ ...Block Kit exception list... ]
}
// Confirmation message (Agent 3)
{
  "channel": "{{SLACK_FINANCE_CHANNEL_ID}}",
  "text": "Payroll submitted to Gusto — {{period_label}} | Total: {{total_payroll_usd}}",
  "blocks": [ ...Block Kit confirmation... ]
}

Gmail API v1 via Google Workspace OAuth. Used by Agent 1 to send automated timesheet deadline reminder emails to managers and by Agent 3 to send the approval request email to the business owner.

// Approval email send (Agent 3)
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
{
  "raw": base64url(MIMEMessage{
    To: {{OWNER_EMAIL}},
    Subject: "{{APPROVAL_SUBJECT_PREFIX}} {{period_label}} — Action required",
    Body: approval_template.txt rendered with {
      period_label, total_gross_pay, employee_count,
      sheets_url, approval_token
    }
  })
}
// Approval signal poll (Agent 3)
GET https://gmail.googleapis.com/gmail/v1/users/me/messages
  ?q=from:{{OWNER_EMAIL}} subject:{{APPROVAL_SUBJECT_PREFIX}} after:{{sent_unix_ts}}

Google Sheets API v4 via Service Account. Used exclusively by Agent 2 (Reconciliation and Calculation Agent) to write the payroll summary, read deduction and leave rule configuration, and maintain the per-run audit log.

// Write payroll summary rows (Agent 2)
POST https://sheets.googleapis.com/v4/spreadsheets/{{GSHEETS_SPREADSHEET_ID}}/values
  /PayrollSummary!A{{row_start}}:M{{row_end}}:append
// Read deduction rules (Agent 2)
GET https://sheets.googleapis.com/v4/spreadsheets/{{GSHEETS_SPREADSHEET_ID}}/values
  /DeductionRules!A:F
// Append audit log entry (Agent 2)
POST .../AuditLog!A:H:append
  { run_id, period_label, employee_count, total_gross, status, timestamp, triggered_by }

QuickBooks Online Accounting API v3 (Intuit Developer Platform). Used by Agent 2 to stage general ledger journal entries for the payroll expense after the payroll summary is complete.

// Stage journal entry (Agent 2)
POST https://quickbooks.api.intuit.com/v3/company/{{QBO_REALM_ID}}/journalentry
  ?minorversion=65
{
  "DocNumber": "PAYROLL-{{period_label}}",
  "TxnDate": "{{period_end_date}}",
  "Line": [
    { "Amount": {{total_gross}}, "DetailType": "JournalEntryLineDetail",
      "JournalEntryLineDetail": { "PostingType": "Debit",
        "AccountRef": { "value": "{{QBO_PAYROLL_EXPENSE_ACCOUNT_ID}}" } } },
    { "Amount": {{total_gross}}, "DetailType": "JournalEntryLineDetail",
      "JournalEntryLineDetail": { "PostingType": "Credit",
        "AccountRef": { "value": "{{QBO_PAYROLL_LIABILITY_ACCOUNT_ID}}" } } }
  ]
}

Gusto Partner API v1 (Gusto Developer Platform). Used exclusively by Agent 3 (Approval and Submission Agent) to push finalised employee hours and pay data after the business owner's approval is confirmed.

// Update employee hours on existing payroll run (Agent 3)
PUT https://api.gusto.com/v1/companies/{{GUSTO_COMPANY_ID}}/payrolls
  /{{payroll_run_id}}/employees/{{gusto_employee_id}}
{
  "employee_id": "{{gusto_employee_id}}",
  "fixed_compensations": [],
  "hourly_compensations": [
    { "name": "Regular Hours", "hours": "{{regular_hours}}" },
    { "name": "Overtime",       "hours": "{{overtime_hours}}" }
  ]
}
// Response: updated payroll_run object; check status == 'unprocessed' before PUT

// ── Deputy ────────────────────────────────────────────────
DEPUTY_SUBDOMAIN              = "yourcompany.au.deputy.com"
DEPUTY_CLIENT_ID              = "<oauth_client_id>"
DEPUTY_CLIENT_SECRET          = "<oauth_client_secret>"
DEPUTY_ACCESS_TOKEN           = "<current_access_token>"
DEPUTY_REFRESH_TOKEN          = "<refresh_token>"

// ── Slack ─────────────────────────────────────────────────
SLACK_BOT_TOKEN               = "xoxb-<token>"
SLACK_FINANCE_CHANNEL_ID      = "C04XXXXXYZ"

// ── Gmail ─────────────────────────────────────────────────
GMAIL_SENDER_ADDRESS          = "payroll-auto@yourcompany.com"
GMAIL_ACCESS_TOKEN            = "<current_access_token>"
GMAIL_REFRESH_TOKEN           = "<refresh_token>"
GMAIL_CLIENT_ID               = "<google_oauth_client_id>"
GMAIL_CLIENT_SECRET           = "<google_oauth_client_secret>"
OWNER_EMAIL                   = "owner@yourcompany.com"
APPROVAL_SUBJECT_PREFIX       = "[PAYROLL APPROVAL]"

// ── Google Sheets ─────────────────────────────────────────
GSHEETS_SPREADSHEET_ID        = "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms"
GSHEETS_SERVICE_ACCOUNT_KEY   = "<base64_encoded_service_account_json>"

// ── QuickBooks Online ─────────────────────────────────────
QBO_REALM_ID                  = "<company_id>"
QBO_CLIENT_ID                 = "<intuit_client_id>"
QBO_CLIENT_SECRET             = "<intuit_client_secret>"
QBO_ACCESS_TOKEN              = "<current_access_token>"
QBO_REFRESH_TOKEN             = "<refresh_token>"
QBO_PAYROLL_EXPENSE_ACCOUNT_ID = "<account_id>"
QBO_PAYROLL_LIABILITY_ACCOUNT_ID = "<account_id>"

// ── Gusto ─────────────────────────────────────────────────
GUSTO_COMPANY_ID              = "<gusto_company_uuid>"
GUSTO_CLIENT_ID               = "<gusto_oauth_client_id>"
GUSTO_CLIENT_SECRET           = "<gusto_oauth_client_secret>"
GUSTO_ACCESS_TOKEN            = "<current_access_token>"
GUSTO_REFRESH_TOKEN           = "<refresh_token>"

// ── Orchestration / Schedule ──────────────────────────────
PAYROLL_SCHEDULE_CRON         = "1 0 1,15 * *"
EMPLOYEE_ID_MAP_SHEET_TAB     = "DeductionRules"
RUN_CONTEXT_TTL_HOURS         = 72