Integration and API Spec

Integration and API Spec

Policy Acknowledgement Tracking

Used by Agent 1 (Policy Distribution Agent) to fetch the active employee list and by Agent 3 (Completion and Archiving Agent) to attach signed PDFs to employee document folders. Authentication uses a per-subdomain API key issued from the BambooHR admin console.

// Input to BambooHR (Agent 1)
GET /v1/employees/directory?fields=id,firstName,lastName,workEmail,department,supervisorId,status
Headers: { Authorization: 'Basic <base64(BAMBOOHR_API_KEY:x)>', Accept: 'application/json' }

// Output from BambooHR (Agent 1)
{ employees: [ { id, firstName, lastName, workEmail, department, supervisorId, status } ] }

// Input to BambooHR (Agent 3 - document upload)
POST /v1/employees/{employeeId}/files
Headers: { Authorization: 'Basic <base64(BAMBOOHR_API_KEY:x)>', Content-Type: 'multipart/form-data' }
Body: { file: <signed_pdf_binary>, fileName: '<policyName>_<version>_<employeeId>.pdf', category: 'Policy Acknowledgements' }

Central to all three agents. Agent 1 creates and sends bulk envelopes from a pre-approved template. Agent 2 polls envelope status for pending signers. Agent 3 listens for the envelope-completed webhook event and retrieves the signed PDF. All DocuSign calls target the eSignature REST API v2.1.

// Input to DocuSign (Agent 1 - create envelope)
POST /v2.1/accounts/{DOCUSIGN_ACCOUNT_ID}/envelopes
Body: {
  templateId: DOCUSIGN_TEMPLATE_ID,
  status: 'sent',
  templateRoles: [
    { email: employee.workEmail, name: employee.fullName, roleName: 'Signer',
      tabs: { textTabs: [{ tabLabel: 'recipientName', value: employee.firstName }] } }
  ]
}

// Output from DocuSign Connect webhook (Agent 3 inbound)
{
  event: 'envelope-completed',
  envelopeId: '<uuid>',
  status: 'completed',
  completedDateTime: '<iso8601>',
  recipients: { signers: [{ email, name, signedDateTime }] }
}

Used exclusively by Agent 2 (Reminder and Escalation Agent) to send day-5 reminder emails to employees who have not yet signed their DocuSign envelope. Emails are sent from the HR Manager's authorised Google Workspace account using the Gmail API.

// Input to Gmail API (Agent 2)
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
Headers: { Authorization: 'Bearer <access_token>', Content-Type: 'application/json' }
Body: {
  raw: base64url(
    'From: GMAIL_FROM_ADDRESS\r\n' +
    'Reply-To: GMAIL_REPLYTO_ADDRESS\r\n' +
    'To: employee.workEmail\r\n' +
    'Subject: Reminder: Please sign the [policyName] acknowledgement\r\n' +
    'Content-Type: text/html; charset=utf-8\r\n\r\n' +
    GMAIL_REMINDER_TEMPLATE_HTML (with placeholders resolved)
  )
}

Used by Agent 2 (Reminder and Escalation Agent) on day 10 to send direct messages to non-signing employees and separate DMs to their line managers. Operates via a dedicated Slack App installed in the organisation's workspace with a bot token.

// Step 1: Resolve Slack user ID by email (Agent 2)
GET https://slack.com/api/users.lookupByEmail?email={employee.workEmail}
Headers: { Authorization: 'Bearer SLACK_BOT_TOKEN' }
Response: { ok: true, user: { id: 'U012AB3CD', profile: { real_name, email } } }

// Step 2: Send DM to employee (Agent 2)
POST https://slack.com/api/chat.postMessage
Body: {
  channel: employee.slackUserId,
  text: SLACK_EMPLOYEE_MSG_TEMPLATE (resolved)
}

// Step 3: Send DM to line manager (Agent 2)
POST https://slack.com/api/chat.postMessage
Body: {
  channel: manager.slackUserId,
  text: SLACK_MANAGER_MSG_TEMPLATE (resolved)
}

Used by all three agents as the central cycle tracking log. Agent 1 seeds the sheet at the start of each cycle. Agent 2 reads it to determine reminder and escalation targets and writes status updates. Agent 3 marks rows as signed with timestamps and generates the completion report tab.

// Agent 1: Seed cycle tracking tab
POST https://sheets.googleapis.com/v4/spreadsheets/{GSHEETS_TRACKING_SPREADSHEET_ID}/values/{tabName}!A1:K1:append
Body: { values: [['employeeId','firstName','lastName','workEmail','department','supervisorId',
         'envelopeId','status','sentDate','signedDate','escalationDate']], valueInputOption: 'USER_ENTERED' }

// Agent 2: Read pending rows
GET https://sheets.googleapis.com/v4/spreadsheets/{GSHEETS_TRACKING_SPREADSHEET_ID}/values/{tabName}!A:K

// Agent 3: Update row on signature
POST https://sheets.googleapis.com/v4/spreadsheets/{GSHEETS_TRACKING_SPREADSHEET_ID}/values:batchUpdate
Body: { valueInputOption: 'USER_ENTERED', data: [{ range: '{tabName}!H{rowIndex}:J{rowIndex}',
  values: [['Signed', completedDateTime, '']] }] }

// Credential store entries (orchestration platform secret manager)
// All values are environment-specific; production and sandbox use separate entries

// BambooHR
BAMBOOHR_API_KEY          = '<api-key-from-bamboohr-admin>'
BAMBOOHR_SUBDOMAIN        = '<your-subdomain>'          // e.g. 'acme' for acme.bamboohr.com

// DocuSign
DOCUSIGN_INTEGRATION_KEY  = '<oauth-app-client-id>'
DOCUSIGN_ACCOUNT_ID       = '<docusign-account-uuid>'
DOCUSIGN_USER_ID          = '<docusign-user-uuid-for-jwt-grant>'
DOCUSIGN_PRIVATE_KEY_PEM  = '<rsa-private-key-pem-block>'
DOCUSIGN_TEMPLATE_ID      = '<envelope-template-uuid>'
DOCUSIGN_CONNECT_HMAC_SECRET = '<hmac-secret-from-connect-config>'
DOCUSIGN_BASE_URL         = 'https://na4.docusign.net/restapi'  // update per account region

// Google (shared for Gmail and Google Sheets)
GOOGLE_CLIENT_ID          = '<google-oauth-client-id>'
GOOGLE_CLIENT_SECRET      = '<google-oauth-client-secret>'
GMAIL_OAUTH_REFRESH_TOKEN = '<refresh-token-for-hr-gmail-account>'
GMAIL_FROM_ADDRESS        = 'hr@[YourCompany.com]'
GMAIL_REPLYTO_ADDRESS     = 'hr-manager@[YourCompany.com]'
GMAIL_REMINDER_TEMPLATE_HTML = '<versioned-html-string-stored-here>'
GOOGLE_SERVICE_ACCOUNT_JSON  = '<service-account-key-json-as-string>'
GSHEETS_TRACKING_SPREADSHEET_ID = '<google-sheets-file-id>'

// Slack
SLACK_BOT_TOKEN           = 'xoxb-<slack-bot-token>'
SLACK_EMPLOYEE_MSG_TEMPLATE  = '<versioned-message-string>'
SLACK_MANAGER_MSG_TEMPLATE   = '<versioned-message-string>'
SLACK_ESCALATION_CHANNEL     = 'C0123456789'  // channel ID, not name

// Cycle-level configuration (set per run, not shared secrets)
POLICY_NAME               = '<set at workflow trigger time>'
POLICY_VERSION            = '<set at workflow trigger time>'
CYCLE_DEADLINE_DATE       = '<ISO 8601 date set at trigger time>'
REMINDER_SEND_TIMEZONE    = 'America/New_York'  // update to HR team timezone
REMINDER_DAY_5_OFFSET     = 5
REMINDER_DAY_10_OFFSET    = 10