Integration and API Spec

Integration and API Spec

Employee Satisfaction and Pulse Surveys

Provides the authoritative active employee list at the start of each survey cycle. The automation queries the Employees endpoint, filters by employment status, and returns a structured list of name, email, department, and hire date fields.

// Endpoint
GET https://{BAMBOOHR_SUBDOMAIN}.bamboohr.com/api/gateway.php/{BAMBOOHR_SUBDOMAIN}/v1/employees/directory
// Query params
fields=id,firstName,lastName,workEmail,department,hireDate,employmentHistoryStatus
// Filter applied in-workflow
employmentHistoryStatus == BAMBOOHR_ACTIVE_STATUS_FILTER AND employeeType != BAMBOOHR_EXCLUDE_TYPE
// Output shape per employee
{ id, firstName, lastName, workEmail, department, hireDate }

Hosts the survey form and provides response data via API after the survey window closes. During the survey window, the automation polls the Responses endpoint to identify non-responders for the reminder step.

// Poll responses endpoint
GET https://api.typeform.com/forms/{TYPEFORM_FORM_ID}/responses
// Query params for incremental poll
?page_size=200&since={SURVEY_OPEN_TIMESTAMP}&fields=hidden,submitted_at,answers
// Inbound webhook payload (per response)
{ form_response: { hidden: { employee_id }, submitted_at, answers: [...] } }
// Signature validation
X-Typeform-Signature: sha256=HMAC(TYPEFORM_WEBHOOK_SECRET, raw_body)

Sends personalised survey invitation emails and the single automated reminder to non-responders. Uses the Gmail API with OAuth 2.0 to send on behalf of the configured HR sending address.

// Send invitation
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
// Message body (RFC 2822, base64url encoded)
To: {workEmail}
Subject: [YourCompany.com] Your voice matters - complete our pulse survey
Body: personalised from INVITE_TEMPLATE_ID with {{ first_name }}, {{ survey_link }}
// survey_link includes hidden field: ?employee_id={bamboohr_id}
// Reminder send follows identical structure using REMINDER_TEMPLATE_ID

Serves as the central data store for the automation: logging invited employees, tracking response and reminder status during the survey window, and holding aggregated scores and trend data after the window closes.

// Append invited employee row
POST /v4/spreadsheets/{GSHEETS_SPREADSHEET_ID}/values/Invited!A:H:append
// Update response_received flag
PUT /v4/spreadsheets/{GSHEETS_SPREADSHEET_ID}/values/Invited!F{row}
// Append response data row
POST /v4/spreadsheets/{GSHEETS_SPREADSHEET_ID}/values/Responses!A:M:append
// Read Scores tab for trend comparison
GET /v4/spreadsheets/{GSHEETS_SPREADSHEET_ID}/values/Scores!A:L

Receives the AI-generated narrative report as a new page in a designated HR database. HR reviews the draft page in Notion before any distribution step fires. The page includes scored data, trend commentary, and flagged department scores below threshold.

// Create report page in database
POST https://api.notion.com/v1/pages
// Headers
Authorization: Bearer {NOTION_INTEGRATION_TOKEN}
Notion-Version: 2022-06-28
// Body (abbreviated)
{ parent: { database_id: NOTION_DATABASE_ID },
  properties: { Title: 'Survey Report: {cycle_date}', Status: 'Draft',
    eNPS_Score: {avg_enps}, Response_Rate: {response_rate_pct},
    Flagged_Departments: [{dept_name}] },
  children: [ heading_block, ...paragraph_blocks (AI narrative, split at 2000 chars) ] }

Posts two types of messages: a mid-cycle response rate alert to the HR channel, and a post-approval report link to the leadership channel. Both use a Slack bot app with incoming webhook URLs or the Slack Web API chat.postMessage method.

// Mid-cycle HR alert
POST https://slack.com/api/chat.postMessage
{ channel: SLACK_HR_CHANNEL_ID,
  text: 'Pulse survey update: {response_rate_pct}% responded as of {now}. Survey closes {survey_close_date}.' }
// Post-approval leadership notification
{ channel: SLACK_LEADERSHIP_CHANNEL_ID,
  text: 'Survey report ready for {cycle_date}. Review here: {notion_report_url}' }

// ============================================================
// CREDENTIAL STORE CONTENTS
// All values encrypted at rest. Never log or expose in workflow output.
// ============================================================

// BambooHR
BAMBOOHR_API_KEY            = <api_key_from_bamboohr_admin>
BAMBOOHR_SUBDOMAIN          = <yourcompany>
BAMBOOHR_ACTIVE_STATUS_FILTER = 'Active'
BAMBOOHR_EXCLUDE_TYPE       = 'Contractor'

// Typeform
TYPEFORM_ACCESS_TOKEN       = <personal_access_token_or_oauth_token>
TYPEFORM_CLIENT_ID          = <oauth_app_client_id>
TYPEFORM_CLIENT_SECRET      = <oauth_app_client_secret>
TYPEFORM_FORM_ID            = <target_survey_form_id>
TYPEFORM_WORKSPACE_ID       = <workspace_id>
TYPEFORM_WEBHOOK_SECRET     = <hmac_signing_secret>

// Gmail
GMAIL_CLIENT_ID             = <google_oauth_client_id>
GMAIL_CLIENT_SECRET         = <google_oauth_client_secret>
GMAIL_REFRESH_TOKEN         = <oauth_refresh_token_for_sending_account>
GMAIL_SENDING_ADDRESS       = hr-surveys@yourcompany.com
GMAIL_REPLY_TO              = hr@yourcompany.com
INVITE_TEMPLATE_ID          = <orchestration_platform_template_id_invite>
REMINDER_TEMPLATE_ID        = <orchestration_platform_template_id_reminder>

// Google Sheets
GSHEETS_SERVICE_ACCOUNT_KEY = <json_key_file_content_base64_encoded>
GSHEETS_SPREADSHEET_ID      = <target_spreadsheet_id>

// Notion
NOTION_INTEGRATION_TOKEN    = <secret_integration_token>
NOTION_DATABASE_ID          = <hr_survey_reports_database_id>
NOTION_LOW_SCORE_THRESHOLD  = 6
NOTION_REPORT_TEMPLATE_PAGE_ID = <optional_template_page_id>

// Slack
SLACK_BOT_TOKEN             = <xoxb_bot_token>
SLACK_HR_CHANNEL_ID         = <hr_operations_channel_id>
SLACK_LEADERSHIP_CHANNEL_ID = <leadership_channel_id>
SLACK_HR_WEBHOOK_URL        = <optional_incoming_webhook_url_hr>
SLACK_LEADERSHIP_WEBHOOK_URL = <optional_incoming_webhook_url_leadership>

// AI / LLM
AI_MODEL_ENDPOINT           = <llm_api_endpoint>
AI_API_KEY                  = <llm_api_key>

// Schedule and configuration
SURVEY_SCHEDULE_CRON        = '0 8 1 * *'  // monthly; override for weekly pulse
SURVEY_WINDOW_DAYS          = 7
SURVEY_CLOSE_DATETIME       = <set_at_workflow_start_time_plus_SURVEY_WINDOW_DAYS>

// Environment
ENV                         = 'sandbox'  // switch to 'production' at go-live