Integration and API Spec

Integration and API Spec

Org Chart and Headcount Management

Source of truth for all personnel change events. The automation platform receives webhook notifications from BambooHR on every hire, role change, or termination. The REST API is also polled as a fallback if a webhook delivery is missed.

// Inbound webhook payload (abridged)
{
  "employeeId": "1042",
  "action": "Changed",
  "changedFields": ["jobTitle", "department", "supervisorId"],
  "employee": {
    "id": "1042",
    "firstName": "Jane",
    "lastName": "Doe",
    "jobTitle": "Senior Designer",
    "department": "Product",
    "supervisorId": "1018",
    "employmentStatus": "Active",
    "startDate": "2022-03-14"
  }
}
// Fallback GET endpoint
GET https://api.bamboohr.com/api/gateway.php/{subdomain}/v1/employees/{id}?fields=id,firstName,lastName,jobTitle,department,supervisorId,employmentStatus,startDate,terminationDate,salary

Payroll record destination. Agent 1 writes updated employment status, department, cost centre, and compensation data to Gusto after a BambooHR event is confirmed. Salary adjustments above a configurable threshold are routed to a human approval step before any write occurs.

// Write employment update
PUT https://api.gusto.com/v1/employees/{employee_id}
{
  "department": "Product",
  "work_email": "jane.doe@yourcompany.com"
}
// Write compensation update (only after approval if above threshold)
PUT https://api.gusto.com/v1/employees/{employee_id}/jobs/{job_id}/compensations
{
  "rate": "95000.00",
  "payment_unit": "Year",
  "flsa_status": "Exempt"
}

Live headcount tracker. Agent 1 updates the relevant employee row on every confirmed sync. Agent 3 reads the sheet every Monday morning to generate the leadership headcount report. The sheet schema must match the canonical column structure defined below.

// Find row by employee_id
GET https://sheets.googleapis.com/v4/spreadsheets/{HEADCOUNT_SHEET_ID}/values/{HEADCOUNT_TAB_NAME}!A:A
// Update matched row
PUT https://sheets.googleapis.com/v4/spreadsheets/{HEADCOUNT_SHEET_ID}/values/{HEADCOUNT_TAB_NAME}!A{row}:L{row}
Body: [[employee_id, first_name, last_name, job_title, department, employment_status, manager_id, location, start_date, termination_date, fte_status, ISO8601_timestamp]]
// Weekly read for report generation (Agent 3)
GET https://sheets.googleapis.com/v4/spreadsheets/{HEADCOUNT_SHEET_ID}/values/{HEADCOUNT_TAB_NAME}!A2:L

Org chart diagram destination. Agent 2 reads the current document structure after a confirmed Headcount Sync Agent completion, locates the affected employee node, and rewrites title, department, and reporting line (parent shape) via the Lucidchart REST API.

// Locate shape by employee_id custom property
GET /documents/{LUCIDCHART_DOCUMENT_ID}
-> Traverse pages[].shapes[] where customData.employee_id == bamboohr_employee_id
// Update existing shape
PATCH /documents/{documentId}/pages/{pageId}/shapes/{shapeId}
{
  "text": "Jane Doe\nSenior Designer",
  "customData": { "employee_id": "1042", "department": "Product" },
  "parentId": "{supervisor_shape_id}"
}
// Create new shape for new hire
POST /documents/{documentId}/pages/{pageId}/shapes
{
  "type": "employee-box",
  "text": "Jane Doe\nSenior Designer",
  "customData": { "employee_id": "1042", "department": "Product" },
  "parentId": "{supervisor_shape_id}"
}

Stakeholder notification channel. Agent 3 sends formatted change alert messages to configured Slack channels after every confirmed sync event. The Slack App must be installed to the workspace and granted to the channels it posts in.

// Send change notification
POST https://slack.com/api/chat.postMessage
Authorization: Bearer {SLACK_BOT_TOKEN}
{
  "channel": "{SLACK_HR_CHANNEL_ID}",
  "text": "Personnel change recorded",
  "blocks": [
    { "type": "section", "text": { "type": "mrkdwn", "text": "*Jane Doe* has been updated to *Senior Designer* in *Product*, effective 2024-04-16." } },
    { "type": "context", "elements": [{ "type": "mrkdwn", "text": "Source: BambooHR | Synced to: Gusto, Sheets, Lucidchart" }] }
  ]
}

Weekly leadership headcount report delivery. Agent 3 reads the current headcount data from Google Sheets every Monday morning, composes a summary email, and sends it to the leadership distribution list via the Gmail API.

// Send weekly report email
POST https://gmail.googleapis.com/gmail/v1/users/{GMAIL_SENDER_ADDRESS}/messages/send
{
  "raw": "<base64url-encoded RFC 2822 message>"
}
// RFC 2822 message structure
From: {GMAIL_SENDER_ADDRESS}
To: {LEADERSHIP_DISTRIBUTION_EMAIL}
Subject: Weekly Headcount Report - 2024-W16
Content-Type: text/html; charset=utf-8
<body>... dynamically generated headcount summary table ...</body>

// BambooHR
BAMBOOHR_API_KEY=<api-key-from-bamboohr-integration-user>
BAMBOOHR_SUBDOMAIN=<yourcompany>
BAMBOOHR_WEBHOOK_SECRET=<hmac-secret-set-in-bamboohr-webhook-settings>

// Gusto
GUSTO_ACCESS_TOKEN=<oauth-access-token>
GUSTO_REFRESH_TOKEN=<oauth-refresh-token>
GUSTO_COMPANY_ID=<gusto-company-uuid>
SALARY_CHANGE_THRESHOLD_USD=5000

// Google (Sheets + Drive + Gmail)
GOOGLE_SERVICE_ACCOUNT_JSON=<json-key-file-contents>
HEADCOUNT_SHEET_ID=<google-sheets-spreadsheet-id>
HEADCOUNT_TAB_NAME=Headcount
GMAIL_SENDER_ADDRESS=hr@yourcompany.com
LEADERSHIP_DISTRIBUTION_EMAIL=leadership@yourcompany.com
REPORT_TIMEZONE=America/New_York

// Lucidchart
LUCIDCHART_ACCESS_TOKEN=<oauth-access-token>
LUCIDCHART_REFRESH_TOKEN=<oauth-refresh-token>
LUCIDCHART_DOCUMENT_ID=<production-org-chart-document-id>
LUCIDCHART_TEMPLATE_SHAPE_LAYER=Org Nodes

// Slack
SLACK_BOT_TOKEN=xoxb-<slack-bot-token>
SLACK_HR_CHANNEL_ID=C0XXXXXXXXX
SLACK_IT_CHANNEL_ID=C0XXXXXXXXX
SLACK_FINANCE_CHANNEL_ID=C0XXXXXXXXX
SLACK_LEADERSHIP_CHANNEL_ID=C0XXXXXXXXX