Integration and API Spec

Integration and API Spec

Probation Period Management

BambooHR is the trigger source for Agent 1 (new employee record detection) and the write-back destination for Agent 3 (final probation outcome update). The API uses subdomain-scoped API keys issued per user account. The integration must use a dedicated service account, not a named employee account, so that credential rotation does not depend on HR staff.

// Agent 1 Trigger Poll
GET /api/gateway.php/{BAMBOOHR_SUBDOMAIN}/v1/employees/changed
  ?since={last_run_iso8601}
  &type=inserted
  Authorization: Basic base64(BAMBOOHR_API_KEY:x)

// Agent 3 Outcome Write-back
PATCH /api/gateway.php/{BAMBOOHR_SUBDOMAIN}/v1/employees/{employee_id}
  Body: { "probation_status": "Passed", "probation_outcome": "Confirmed" }

Notion serves as the central probation tracker across all three agents. Agent 1 creates rows, Agent 2 reads milestone dates and writes chase log entries, and Agent 3 reads the logged outcome and closes the row. All Notion access goes through a single internal integration token scoped to the HR workspace.

// Agent 1 creates a new tracker row
POST /v1/pages
  parent: { database_id: NOTION_DB_PROBATION_ID }
  properties: { employee_name, employee_id, manager_email,
    start_date, milestone_4w, milestone_8w, probation_end_date }

// Agent 3 polls for outcome-logged rows
POST /v1/databases/{NOTION_DB_PROBATION_ID}/query
  filter: { and: [ outcome is_not_empty, docusign_sent = false ] }

// Agent 3 closes the row after DocuSign completion
PATCH /v1/pages/{page_id}
  properties: { record_closed: true, docusign_envelope_id: "..." }

Google Workspace covers three distinct integration points: Gmail for sending milestone feedback request emails (Agent 2), Google Docs for populating outcome letter templates (Agent 3), and Google Drive for storing the completed pre-signature letter PDF (Agent 3). A single service account with domain-wide delegation covers all three.

// Agent 2: Send milestone feedback email
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
  Authorization: Bearer {access_token}
  Body: RFC 2822 encoded message with To, Subject, body (HTML)

// Agent 3: Copy template and populate placeholders
POST https://docs.googleapis.com/v1/documents/{GDOC_TEMPLATE_PASS_ID}:copy
  -> returns new_doc_id
POST https://docs.googleapis.com/v1/documents/{new_doc_id}:batchUpdate
  replaceAllText: [ { {{employee_full_name}} -> value }, ... ]

// Agent 3: Export populated doc as PDF
GET https://www.googleapis.com/drive/v3/files/{new_doc_id}/export
  ?mimeType=application/pdf

Slack is used exclusively by Agent 2 (Feedback Chase Agent) to deliver direct message reminders to managers who have not submitted feedback within 48 hours of a milestone email being sent. A secondary escalation message is sent to the HR channel if the manager does not respond after the first Slack reminder.

// Resolve manager email to Slack user ID
GET https://slack.com/api/users.lookupByEmail?email={manager_email}
  Authorization: Bearer SLACK_BOT_TOKEN
  -> returns user.id

// Open DM channel and post reminder
POST https://slack.com/api/conversations.open
  { users: [user_id] } -> returns channel.id
POST https://slack.com/api/chat.postMessage
  { channel: channel_id, text: "Reminder: probation feedback due for {employee_name}" }

// HR escalation if second reminder ignored
POST https://slack.com/api/chat.postMessage
  { channel: SLACK_HR_CHANNEL_ID, text: "Escalation: {manager_name} has not submitted feedback..." }

DocuSign is used by Agent 3 (Outcome and Documentation Agent) to create and send a sequential signing envelope: the manager signs first, then the employee. The automation polls for envelope completion and, on a completed status, retrieves the signed PDF, stores it in Google Drive, and triggers the BambooHR write-back. DocuSign JWT grant is the required auth method as the integration acts on behalf of a service user, not an interactive session.

// JWT token exchange
POST https://account.docusign.com/oauth/token
  grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
  assertion={signed_jwt}
  -> access_token (1 hr expiry)

// Create and send envelope
POST https://{DOCUSIGN_BASE_URI}/restapi/v2.1/accounts/{DOCUSIGN_ACCOUNT_ID}/envelopes
  { status: 'sent', documents: [{documentBase64: pdf_b64}],
    recipients: { signers: [
      { email: manager_email, routingOrder: 1 },
      { email: employee_email, routingOrder: 2 }
    ] } }

// Inbound Connect webhook (validate HMAC before processing)
POST {DOCUSIGN_CONNECT_WEBHOOK_URL}
  Header: X-DocuSign-Signature-1: {hmac_sha256}
  Body: { envelopeId, status: 'completed', ... }

// Retrieve signed document after completion
GET /restapi/v2.1/accounts/{DOCUSIGN_ACCOUNT_ID}/envelopes/{envelope_id}/documents/combined

// Credential store contents (all values injected at runtime as secrets)

// BambooHR
BAMBOOHR_API_KEY                    = <api_key_from_bamboohr_admin>
BAMBOOHR_SUBDOMAIN                  = <your_subdomain>  // e.g. 'yourcompany'
BAMBOOHR_FIELD_PROBATION_END_DATE_ID = <custom_field_id>  // from GET /v1/meta/fields
BAMBOOHR_FIELD_PROBATION_STATUS_ID  = <custom_field_id>
BAMBOOHR_FIELD_PROBATION_OUTCOME_ID = <custom_field_id>

// Notion
NOTION_INTEGRATION_TOKEN            = <secret_xxx_token>
NOTION_DB_PROBATION_ID              = <database_id_from_notion_url>

// Google Workspace
GOOGLE_SERVICE_ACCOUNT_JSON         = <json_key_file_contents>  // base64-encoded recommended
GOOGLE_IMPERSONATION_EMAIL          = hr-automation@yourcompany.com
GDOC_TEMPLATE_PASS_ID               = <google_doc_id>
GDOC_TEMPLATE_EXTEND_ID             = <google_doc_id>
GDOC_TEMPLATE_EXIT_ID               = <google_doc_id>
GDRIVE_OUTCOME_FOLDER_ID            = <google_drive_folder_id>

// Slack
SLACK_BOT_TOKEN                     = xoxb-<bot_token>
SLACK_HR_CHANNEL_ID                 = C<channel_id>  // #hr-escalations

// DocuSign
DOCUSIGN_INTEGRATION_KEY            = <client_id_from_docusign_apps_and_keys>
DOCUSIGN_RSA_PRIVATE_KEY            = <pem_private_key>  // stored as multiline secret
DOCUSIGN_USER_GUID                  = <user_guid_of_hr_service_account>
DOCUSIGN_ACCOUNT_ID                 = <account_id>
DOCUSIGN_BASE_URI                   = na3.docusign.net  // retrieved from userinfo; do not hardcode without verification
DOCUSIGN_CONNECT_HMAC_KEY           = <connect_hmac_secret>
DOCUSIGN_CONNECT_WEBHOOK_URL        = <orchestration_platform_inbound_url>

// Organisation config
ORG_TIMEZONE                        = America/New_York  // replace with actual org timezone
COMPANY_NAME                        = [YourCompany.com]