Integration and API Spec

Integration and API Spec

Employee Onboarding Automation

Acts as the master trigger source for the entire automation and as the final record store for provisioning confirmation logs. The orchestration layer subscribes to BambooHR's outgoing webhook on the employee status field.

// Webhook payload (inbound to orchestration layer)
{
  "employeeId": "string",
  "firstName": "string",
  "lastName": "string",
  "jobTitle": "string",
  "department": "string",
  "supervisorId": "string",
  "startDate": "YYYY-MM-DD",
  "workEmail": "string",
  "salary": "number",
  "employmentType": "string"
}

// Write-back on provisioning complete
PATCH /v1/employees/{employeeId}
{ "onboarding_status": "provisioned", "provisioning_date": "ISO8601" }

Used exclusively by Agent 1 (Document Agent) to populate role-specific offer letter templates and send them for e-signature. The completion webhook from DocuSign triggers the Gmail information pack step.

// Create envelope from template
POST /v2.1/accounts/{accountId}/envelopes
{
  "templateId": "DOCUSIGN_TEMPLATE_MAP[jobTitle]",
  "templateRoles": [{
    "email": "hire.workEmail",
    "name": "hire.firstName + ' ' + hire.lastName",
    "roleName": "New Hire",
    "tabs": {
      "textTabs": [
        { "tabLabel": "hire_first_name", "value": "hire.firstName" },
        { "tabLabel": "hire_last_name",  "value": "hire.lastName"  },
        { "tabLabel": "hire_job_title",  "value": "hire.jobTitle"  },
        { "tabLabel": "hire_salary",     "value": "hire.salary"    },
        { "tabLabel": "hire_start_date", "value": "hire.startDate" }
      ]
    }
  }],
  "status": "sent"
}

// Connect event inbound (envelope completed)
{ "event": "envelope-completed", "envelopeId": "string", "completedDateTime": "ISO8601" }

Used by Agent 1 (Document Agent) to send the information pack and document-chase reminders, and by Agent 3 (Onboarding Coordinator Agent) to send the day-one welcome email. All outbound mail is sent from the HR Manager's delegated mailbox.

// Send via Gmail API
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
Authorization: Bearer GMAIL_ACCESS_TOKEN
{
  "raw": "<base64url-encoded RFC 2822 message>"
}

// Message headers required
From: GMAIL_SENDER_ADDRESS
To: hire.workEmail
Subject: <template-specific subject string>
Content-Type: multipart/alternative

Used exclusively by Agent 2 (Provisioning Agent) to create the new hire's Google account, assign the correct organisational unit, and add them to department Google Groups.

// Create user
POST https://admin.googleapis.com/admin/directory/v1/users
{
  "primaryEmail": "hire.firstName.hire.lastName@GWS_PRIMARY_DOMAIN",
  "name": { "givenName": "hire.firstName", "familyName": "hire.lastName" },
  "password": "<generated-temp-password>",
  "changePasswordAtNextLogin": true,
  "orgUnitPath": "GWS_OU_MAP[hire.department]"
}

// Add to group
POST https://admin.googleapis.com/admin/directory/v1/groups/{groupKey}/members
{ "email": "hire.workEmail", "role": "MEMBER" }

Used by Agent 2 (Provisioning Agent) to invite the new hire to the Slack workspace and add them to the correct channels, and by Agent 3 (Onboarding Coordinator Agent) to send the structured hiring manager briefing.

// Invite user to workspace (by email)
POST https://slack.com/api/users.admin.invite
Authorization: Bearer SLACK_BOT_TOKEN
{ "email": "hire.workEmail", "channel_ids": ["C000GENERAL"] }

// Add to additional channels
POST https://slack.com/api/conversations.invite
{ "channel": "SLACK_CHANNEL_MAP[hire.department][n]", "users": "slack_user_id" }

// Post manager briefing
POST https://slack.com/api/chat.postMessage
{ "channel": "supervisor_slack_user_id", "text": "SLACK_TEMPLATE_MANAGER_BRIEF(rendered)" }

Used exclusively by Agent 3 (Onboarding Coordinator Agent) to duplicate the role-appropriate onboarding page template and personalise it with the new hire's details before sharing the URL with the hire and their manager.

// Create new page in database
POST https://api.notion.com/v1/pages
Notion-Version: 2022-06-28
Authorization: Bearer NOTION_TOKEN
{
  "parent": { "database_id": "NOTION_ONBOARDING_DB_ID" },
  "properties": {
    "hire_name":       { "title": [{ "text": { "content": "hire.firstName + hire.lastName" } }] },
    "hire_role":       { "rich_text": [{ "text": { "content": "hire.jobTitle" } }] },
    "hire_start_date": { "date": { "start": "hire.startDate" } },
    "hire_manager":    { "rich_text": [{ "text": { "content": "hire.supervisorName" } }] }
  }
}

// Response: capture page URL
{ "id": "<new-page-id>", "url": "https://www.notion.so/<new-page-id>" }

// Credential store contents (all values injected at runtime, never hardcoded)

// BambooHR
BAMBOOHR_API_KEY=<api-key>
BAMBOOHR_SUBDOMAIN=<subdomain>
BAMBOOHR_WEBHOOK_SECRET=<shared-secret-for-hmac>

// DocuSign
DOCUSIGN_CLIENT_ID=<oauth-client-id>
DOCUSIGN_CLIENT_SECRET=<oauth-client-secret>
DOCUSIGN_ACCOUNT_ID=<account-id>
DOCUSIGN_BASE_URI=<https://na4.docusign.net>
DOCUSIGN_ACCESS_TOKEN=<token>          // rotated automatically
DOCUSIGN_REFRESH_TOKEN=<token>         // rotated automatically
DOCUSIGN_CONNECT_SECRET=<hmac-secret>
DOCUSIGN_TEMPLATE_MAP={"Software Engineer":"tpl-abc123","Account Manager":"tpl-def456"}

// Gmail / Google Identity
GMAIL_CLIENT_ID=<oauth-client-id>
GMAIL_CLIENT_SECRET=<oauth-client-secret>
GMAIL_ACCESS_TOKEN=<token>             // rotated automatically
GMAIL_REFRESH_TOKEN=<token>            // rotated automatically
GMAIL_SENDER_ADDRESS=hr@[YourCompany.com]
GMAIL_TEMPLATE_INFO_PACK=<html-string-with-placeholders>
GMAIL_TEMPLATE_CHASE_REMINDER=<html-string-with-placeholders>
GMAIL_TEMPLATE_DAY_ONE_WELCOME=<html-string-with-placeholders>

// Google Workspace Admin SDK
GWS_SERVICE_ACCOUNT_KEY=<base64-encoded-service-account-json>
GWS_ADMIN_EMAIL=admin@[YourCompany.com]
GWS_PRIMARY_DOMAIN=[YourCompany.com]
GWS_OU_MAP={"Engineering":"/Engineering","Sales":"/Sales","HR":"/HR"}
GWS_GROUP_MAP={"Engineering":"eng-team@[YourCompany.com]","Sales":"sales-team@[YourCompany.com]"}
GWS_KEY_CREATED_DATE=<ISO8601>         // monitored for 90-day rotation

// Slack
SLACK_BOT_TOKEN=xoxb-<token>
SLACK_WORKSPACE_ID=<workspace-id>
SLACK_CHANNEL_MAP={"Engineering":["C012AB3DE","C000GENERAL"],"Sales":["C098XY1ZA","C000GENERAL"]}
SLACK_USER_MAP={"bhr-supervisor-001":"U012SLACK1","bhr-supervisor-002":"U034SLACK2"}
SLACK_HR_FALLBACK_CHANNEL=C00HRFALLBK
SLACK_TEMPLATE_MANAGER_BRIEF=<message-string-with-placeholders>

// Notion
NOTION_TOKEN=ntn-<internal-integration-token>
NOTION_ONBOARDING_DB_ID=<database-id>
NOTION_TEMPLATE_PAGE_ID=<template-page-id>