Integration and API Spec

Integration and API Spec

Leave and Absence Management

Used by Agent 1 (Leave Intake and Balance Agent) to read employee leave balances and by Agent 3 (Post-Approval Sync Agent) to deduct approved days and update the leave record. All calls use the BambooHR REST API v1 against the company-specific subdomain.

// Balance read (Agent 1)
GET https://{BAMBOOHR_SUBDOMAIN}.bamboohr.com/api/gateway.php/{BAMBOOHR_SUBDOMAIN}/v1/employees/{employee_id}/time_off/calculator/
  -> returns: accrued, used, scheduled, balance per leave type

// Balance deduction (Agent 3)
POST https://{BAMBOOHR_SUBDOMAIN}.bamboohr.com/api/gateway.php/{BAMBOOHR_SUBDOMAIN}/v1/employees/{employee_id}/time_off/requests/
  body: { start, end, timeOffTypeId, amount, status: 'approved', note }
  -> returns: request ID, updated balance

Used by Agent 1 to scan the shared team calendar for coverage conflicts during the requested leave dates, and by Agent 3 to create an all-day absence event on approval. A Google Cloud service account with domain-wide delegation is the recommended auth method to avoid per-user OAuth consent flows.

// Conflict check (Agent 1)
GET https://www.googleapis.com/calendar/v3/calendars/{GOOGLE_TEAM_CALENDAR_ID}/events
  params: timeMin={leave_start}T00:00:00Z, timeMax={leave_end}T23:59:59Z, singleEvents=true
  -> returns: list of overlapping events with attendees

// Event creation (Agent 3)
POST https://www.googleapis.com/calendar/v3/calendars/{GOOGLE_TEAM_CALENDAR_ID}/events
  body: { summary: '{employee_name} - {leave_type}', start: { date }, end: { date }, description: 'Approved via Leave Management automation' }
  -> returns: event.id stored for audit log

Used by Agent 2 (Approval Routing Agent) to deliver a structured approval request to the line manager with interactive approve and decline buttons, and by Agent 3 (Post-Approval Sync Agent) to send a confirmation DM to the employee and a notice to the team channel. Requires a custom Slack app installed to the workspace.

// Approval request (Agent 2)
POST https://slack.com/api/chat.postMessage
  headers: Authorization: Bearer {SLACK_BOT_TOKEN}
  body: { channel: '{manager_slack_id}', blocks: [ header, section(employee, dates, leave_type, balance), actions(approve_button, decline_button) ] }
  -> returns: ts (message timestamp, stored as PENDING_APPROVAL_TS for correlation)

// Interaction callback received (Agent 2 webhook handler)
POST {SLACK_INTERACTIVITY_WEBHOOK_URL}
  payload: { type: 'block_actions', actions: [{ action_id: 'approve|decline', value: '{request_id}' }], user: { id, name } }
  -> validated by HMAC-SHA256 against SLACK_SIGNING_SECRET

// Employee DM and team channel post (Agent 3)
POST https://slack.com/api/chat.postMessage  (x2: employee DM and team channel)

Used by Agent 2 as a fallback notification channel when a leave request is declined due to insufficient balance or a coverage conflict. The Gmail send is triggered on the decline path only and delivers a formatted outcome email to the employee's work address.

// Decline notification (Agent 2, decline branch only)
POST https://gmail.googleapis.com/gmail/v1/users/{GMAIL_SENDER_ADDRESS}/messages/send
  headers: Authorization: Bearer {access_token}
  body: { raw: base64url( RFC2822 message: To, From, Subject, Content-Type, HTML body with filled placeholders ) }
  -> returns: message.id stored for audit log

Used exclusively by Agent 3 (Post-Approval Sync Agent) to log approved leave in the payroll system so that any required deductions or accrual adjustments are captured before the next pay run closes. Gusto API access requires enrollment in the Gusto Partner Program or use of a company-level API token.

// Employee lookup (Agent 3)
GET https://api.gusto.com/v1/companies/{GUSTO_COMPANY_UUID}/employees
  params: email={employee_email}
  -> returns: employee.uuid stored as gusto_employee_uuid

// Time-off entry write (Agent 3)
POST https://api.gusto.com/v1/companies/{GUSTO_COMPANY_UUID}/time_off_requests
  body: { employee_uuid: gusto_employee_uuid, time_off_type_uuid: GUSTO_LEAVE_TYPE_MAP[leave_type], start_date, end_date, status: 'approved', days_count }
  -> returns: time_off_request.uuid stored for audit log

// BambooHR
BAMBOOHR_API_KEY              = "<hr-admin-api-key>"
BAMBOOHR_SUBDOMAIN            = "<yourcompany>"
BAMBOOHR_LEAVE_TYPE_ANNUAL    = "<numeric-leave-type-id>"
BAMBOOHR_LEAVE_TYPE_SICK      = "<numeric-leave-type-id>"
BAMBOOHR_LEAVE_TYPE_UNPAID    = "<numeric-leave-type-id>"
BAMBOOHR_LEAVE_TYPE_PARENTAL  = "<numeric-leave-type-id>"

// Google Calendar and Gmail (shared service account)
GOOGLE_SERVICE_ACCOUNT_JSON   = "<base64-encoded-service-account-key-json>"
GOOGLE_TEAM_CALENDAR_ID       = "<team-absence-calendar-id@group.calendar.google.com>"
GOOGLE_CONFLICT_THRESHOLD     = 2
GOOGLE_EVENT_SUMMARY_TEMPLATE = "{employee_name} - {leave_type}"
GMAIL_SENDER_ADDRESS          = "hr-notifications@yourcompany.com"
GMAIL_DECLINE_TEMPLATE_ID     = "<template-ref-or-html-key>"

// Slack
SLACK_BOT_TOKEN               = "xoxb-<token>"
SLACK_SIGNING_SECRET          = "<slack-app-signing-secret>"
SLACK_TEAM_CHANNEL_ID         = "<C0XXXXXXXXX>"
SLACK_APPROVAL_CHANNEL_PREFIX = "leave-approval"
SLACK_INTERACTIVITY_WEBHOOK_URL = "https://automation.yourcompany.com/webhooks/slack-interactions"

// Gusto
GUSTO_CLIENT_ID               = "<oauth-client-id>"
GUSTO_CLIENT_SECRET           = "<oauth-client-secret>"
GUSTO_REFRESH_TOKEN           = "<oauth-refresh-token>"
GUSTO_COMPANY_UUID            = "<gusto-company-uuid>"
GUSTO_LEAVE_TYPE_MAP          = '{"annual":"<gusto-policy-uuid>","sick":"<gusto-policy-uuid>","unpaid":"<gusto-policy-uuid>","parental":"<gusto-policy-uuid>"}'

// Internal
INTERNAL_QUEUE_DSN            = "<queue-connection-string>"
AUDIT_LOG_DSN                 = "<log-store-connection-string>"