Integration and API Spec

Integration and API Spec

Training and Certification Tracking

Used by both agents. Agent 1 (Certification Monitor Agent) reads employee records and certification custom fields daily. Agent 2 (Renewal Intake and Filing Agent) writes updated completion and expiry dates back to the employee profile on submission.

// Agent 1 Read
GET /api/gateway.php/{subdomain}/v1/employees/directory
GET /api/gateway.php/{subdomain}/v1/employees/{id}?fields=cert_type,cert_expiry_date,cert_completion_date,supervisorId
// Agent 2 Write
POST /api/gateway.php/{subdomain}/v1/employees/{id}
Body: { cert_completion_date: "YYYY-MM-DD", cert_expiry_date: "YYYY-MM-DD" }

Used by both agents as the certification tracking log. Agent 1 reads expiry data to cross-reference and writes reminder log entries. Agent 2 writes completion status and updated dates after a successful Typeform submission.

// Agent 1 Read
GET sheets/v4/spreadsheets/{spreadsheetId}/values/CertTracker!A:I
// Agent 1 Write (reminder log)
POST sheets/v4/spreadsheets/{spreadsheetId}/values/ReminderLog!A:F:append
Body: [[employee_id, employee_name, cert_type, reminder_tier, reminder_date, status]]
// Agent 2 Write (status update)
PUT sheets/v4/spreadsheets/{spreadsheetId}/values/CertTracker!G{row}:I{row}
Body: [["Complete", completion_date, drive_file_url]]

Used by Agent 1 only. Sends personalised, tiered reminder emails to employees at the 90-day, 60-day, and 30-day marks, and an overdue notice after the sequence completes.

// Agent 1 Send
POST https://gmail.googleapis.com/gmail/v1/users/{userId}/messages/send
Body (MIME, base64url encoded):
  To: {employee_email}
  From: {sender_address}
  Subject: Action required: {cert_type} renewal due in {days_remaining} days
  Content-Type: multipart/alternative
    text/plain: {template_plaintext}
    text/html:  {template_html}

Used by Agent 1 only. Sends a direct message to the relevant manager each time a reminder email is dispatched to an employee, and sends an escalation notification when an employee remains non-compliant after the 30-day reminder.

// Resolve manager Slack ID
GET https://slack.com/api/users.lookupByEmail?email={supervisor_email}
Response: { ok: true, user: { id: "U01XXXXXXX" } }
// Send direct message
POST https://slack.com/api/chat.postMessage
Body: {
  channel: "{manager_slack_id}",
  text: "Certification reminder sent to {employee_name} ({cert_type}, expires {cert_expiry_date})"
}

Used by Agent 2 only. The employee-facing submission form captures employee ID, certification name, completion date, new expiry date, and a certificate file upload. A webhook fires to the orchestration layer on each new response.

// Inbound webhook payload (simplified)
{
  "event_id": "uuid",
  "event_type": "form_response",
  "form_response": {
    "form_id": "{form_id}",
    "token": "{response_token}",
    "answers": [
      { "field": { "id": "{f_employee_id}" }, "text": "EMP-042" },
      { "field": { "id": "{f_cert_type}" }, "choice": { "label": "First Aid Level 2" } },
      { "field": { "id": "{f_completion_date}" }, "date": "2025-05-14" },
      { "field": { "id": "{f_new_expiry_date}" }, "date": "2027-05-14" },
      { "field": { "id": "{f_file_upload}" }, "file_url": "https://api.typeform.com/responses/files/..." }
    ]
  }
}

Used by Agent 2 only. Receives the downloaded certificate file and saves it to the correct named folder, applying a consistent file-naming convention derived from the employee ID, certification type, and completion date.

// Create subfolder if not exists
POST https://www.googleapis.com/drive/v3/files
Body: { name: "{cert_type_slug}", mimeType: "application/vnd.google-apps.folder",
        parents: ["{employee_folder_id}"] }
// Upload certificate file (multipart)
POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart
Metadata part: { name: "{filename}.pdf", parents: ["{subfolder_id}"] }
Media part: {binary file content, mimeType: application/pdf}
// Response
{ id: "{file_id}", webViewLink: "https://drive.google.com/file/d/{file_id}/view" }

// Credential store — key : description

// BambooHR
BAMBOOHR_SUBDOMAIN         : Company subdomain (e.g. yourcompany)
BAMBOOHR_API_KEY           : API key for service account user
BAMBOOHR_FIELD_ID_CERT_TYPE          : Numeric ID of cert_type custom field
BAMBOOHR_FIELD_ID_COMPLETION_DATE    : Numeric ID of cert_completion_date custom field
BAMBOOHR_FIELD_ID_EXPIRY_DATE        : Numeric ID of cert_expiry_date custom field
BAMBOOHR_FIELD_ID_DRIVE_URL          : Numeric ID of cert_drive_url custom field (optional)

// Google (Sheets, Drive, Gmail — shared service account)
GOOGLE_SERVICE_ACCOUNT_JSON          : Full JSON key file content for service account
GOOGLE_SHEETS_SPREADSHEET_ID         : ID of the master certification tracking spreadsheet
GOOGLE_SHEETS_TAB_CERTTRACKER        : Sheet tab name (default: CertTracker)
GOOGLE_SHEETS_TAB_REMINDERLOG        : Log tab name (default: ReminderLog)
GOOGLE_SHEETS_TAB_PROCESSEDTOKENS    : Idempotency tab name (default: ProcessedTokens)
GOOGLE_DRIVE_ROOT_FOLDER_ID          : ID of the root /Certificates folder in Drive
GMAIL_SENDER_ADDRESS                 : Sending email address (e.g. hr@[YourCompany.com])
GMAIL_SENDER_DISPLAY_NAME            : Display name (e.g. HR Compliance — [YourCompany.com])

// Email templates (stored as multiline strings or template IDs)
EMAIL_TEMPLATE_90D                   : Full HTML+plaintext template for 90-day reminder
EMAIL_TEMPLATE_60D                   : Full HTML+plaintext template for 60-day reminder
EMAIL_TEMPLATE_30D                   : Full HTML+plaintext template for 30-day reminder
EMAIL_TEMPLATE_OVERDUE               : Full HTML+plaintext template for overdue notice

// Typeform
TYPEFORM_PAT                         : Personal Access Token
TYPEFORM_FORM_ID                     : ID of the certificate submission form
TYPEFORM_FORM_URL                    : Public URL injected into reminder emails
TYPEFORM_WEBHOOK_SECRET              : Shared secret for HMAC-SHA256 signature validation
TYPEFORM_FIELD_ID_EMPLOYEE_ID        : Field ID for employee ID answer
TYPEFORM_FIELD_ID_CERT_TYPE          : Field ID for certification type answer
TYPEFORM_FIELD_ID_COMPLETION_DATE    : Field ID for completion date answer
TYPEFORM_FIELD_ID_NEW_EXPIRY_DATE    : Field ID for new expiry date answer
TYPEFORM_FIELD_ID_FILE_UPLOAD        : Field ID for file upload answer

// Slack
SLACK_BOT_TOKEN                      : OAuth Bot token (xoxb-...)
SLACK_ESCALATION_CHANNEL_ID          : Channel ID for overdue and error alerts

// Drive file naming
DRIVE_CERT_TYPE_SLUG_MAP             : JSON map of cert type labels to filename slugs
                                       e.g. { "First Aid Level 2": "FirstAidL2" }