--- updatedAt: 2026-04-20T19:45:37.000Z agentTools: projectIndex: https://documentation.bamboohr.com/llms.txt --- # Get Webhook Post Fields Returns an object containing the employee fields that can be included in the webhook post body for field-based webhooks. Also includes the related table and page records referenced by those fields. Use the field IDs or aliases from this response in the `postFields` map when creating or updating a field-based webhook. OAuth Scopes: webhooks # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "BambooHR API", "description": "BambooHR API documentation. https://documentation.bamboohr.com/", "version": "1.0" }, "servers": [ { "url": "https://{companyDomain}.bamboohr.com", "variables": { "companyDomain": { "default": "companySubDomain", "description": "Company domain" } } } ], "paths": { "/api/v1/webhooks/post-fields": { "get": { "tags": [ "Webhooks", "Public API" ], "summary": "Get Webhook Post Fields", "description": "Returns an object containing the employee fields that can be included in the webhook post body for field-based webhooks. Also includes the related table and page records referenced by those fields. Use the field IDs or aliases from this response in the `postFields` map when creating or updating a field-based webhook.\n\nOAuth Scopes: webhooks", "operationId": "get-post-fields", "responses": { "200": { "description": "An object with `fields`, `tables`, and `pages` arrays. `fields` contains the postable employee fields with their IDs, aliases, types, and associated page/table IDs. `tables` and `pages` contain the referenced metadata for those associations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebHookPostFieldResponseObject" } } } }, "403": { "description": "Permission denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookError" } } } } }, "security": [ { "basic": [] }, { "oauth": [ "webhooks" ] } ] } } }, "components": { "schemas": { "WebhookError": { "title": "Webhook Standard error", "properties": { "errors": { "oneOf": [ { "$ref": "#/components/schemas/WebhookSubErrorProperty" }, { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubErrorProperty" } } ] } }, "type": "object", "example": { "errors": [ { "error": "You do not have access to webhook ID: 5" }, { "error": "No webhook was found with ID: 7." }, { "error": "Sorry for the inconvenience, please try again later or contact BambooHR" } ] }, "additionalProperties": false }, "WebhookSubErrorProperty": { "properties": { "error": { "type": "string" }, "unknownFields": { "type": "array", "items": { "properties": { "id": { "oneOf": [ { "type": "integer" }, { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" } }, "type": "object" } }, "monitorFields": { "type": "array", "items": { "properties": { "id": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "name": { "type": "string" } }, "type": "object" } }, "duplicatePostString": { "type": "array", "items": { "type": "string" } }, "postFields": { "type": "array", "items": { "properties": { "id": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "name": { "type": "string" } }, "type": "object" } } }, "type": "object", "additionalProperties": false }, "CompanyIntegrationsUpdatedWebhookPayload": { "title": "Company Integrations Updated Webhook Payload", "description": "Webhook payload sent when company integrations are updated.", "properties": { "type": { "description": "The event type identifier", "type": "string", "enum": [ "company-integrations.updated" ], "example": "company-integrations.updated" }, "timestamp": { "description": "ISO 8601 timestamp (UTC) when the event was fired", "type": "string", "format": "date-time", "example": "2025-02-18T15:30:00Z" }, "data": { "description": "Event data containing company information", "properties": { "companyId": { "description": "The company ID", "type": "string", "example": "12345" } }, "type": "object" } }, "type": "object" }, "CompanyUpdatedWebhookPayload": { "title": "Company Updated Webhook Payload", "description": "Webhook payload sent when a company is updated.", "properties": { "type": { "description": "The event type identifier", "type": "string", "enum": [ "company.updated" ], "example": "company.updated" }, "timestamp": { "description": "ISO 8601 timestamp (UTC) when the event was fired", "type": "string", "format": "date-time", "example": "2025-02-18T15:30:00Z" }, "data": { "description": "Event data containing company information", "properties": { "companyId": { "description": "The company ID", "type": "string", "example": "12345" } }, "type": "object" } }, "type": "object" }, "CompanyDeletedWebhookPayload": { "title": "Company Deleted Webhook Payload", "description": "Webhook payload sent when a company is deleted.", "properties": { "type": { "description": "The event type identifier", "type": "string", "enum": [ "company.deleted" ], "example": "company.deleted" }, "timestamp": { "description": "ISO 8601 timestamp (UTC) when the event was fired", "type": "string", "format": "date-time", "example": "2025-02-18T15:30:00Z" }, "data": { "description": "Event data containing company information", "properties": { "companyId": { "description": "The company ID", "type": "string", "example": "12345" } }, "type": "object" } }, "type": "object" }, "EmployeeCreatedWebhookPayload": { "title": "Employee Created Webhook Payload", "description": "Webhook payload sent when a new employee is created.", "properties": { "type": { "description": "The event type identifier", "type": "string", "enum": [ "employee.created" ], "example": "employee.created" }, "timestamp": { "description": "ISO 8601 timestamp (UTC) when the event was fired", "type": "string", "format": "date-time", "example": "2025-02-18T15:30:00Z" }, "data": { "description": "Event data containing employee information", "properties": { "companyId": { "description": "The company ID", "type": "string", "example": "12345" }, "employeeId": { "description": "The employee ID that was created", "type": "string", "example": "100" } }, "type": "object" } }, "type": "object" }, "EmployeeDeletedWebhookPayload": { "title": "Employee Deleted Webhook Payload", "description": "Webhook payload sent when an employee is deleted.", "properties": { "type": { "description": "The event type identifier", "type": "string", "enum": [ "employee.deleted" ], "example": "employee.deleted" }, "timestamp": { "description": "ISO 8601 timestamp (UTC) when the event was fired", "type": "string", "format": "date-time", "example": "2025-02-18T15:30:00Z" }, "data": { "description": "Event data containing employee information", "properties": { "companyId": { "description": "The company ID", "type": "string", "example": "12345" }, "employeeId": { "description": "The employee ID that was deleted", "type": "string", "example": "100" } }, "type": "object" } }, "type": "object" }, "EmployeeUpdatedWebhookPayload": { "title": "Employee Updated Webhook Payload", "description": "Webhook payload sent when an employee is updated.", "properties": { "type": { "description": "The event type identifier", "type": "string", "enum": [ "employee.updated" ], "example": "employee.updated" }, "timestamp": { "description": "ISO 8601 timestamp (UTC) when the event was fired", "type": "string", "format": "date-time", "example": "2025-02-18T15:30:00Z" }, "data": { "description": "Event data containing employee and change information", "properties": { "companyId": { "description": "The company ID", "type": "string", "example": "12345" }, "employeeId": { "description": "The employee ID that was updated", "type": "string", "example": "100" }, "changedFields": { "description": "Array of API aliases for fields that changed and are monitored by this webhook", "type": "array", "items": { "type": "string" }, "example": [ "firstName", "lastName", "department" ] } }, "type": "object" } }, "type": "object" }, "WebHookPostFieldDataObject": { "title": "WebHookPostFieldDataObject", "required": [ "alias", "name", "type", "id", "pageId", "tableId" ], "properties": { "alias": { "description": "Field identifier used in the API", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "description": "Field name", "type": "string" }, "type": { "description": "Field type", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "description": "Field ID. This may be a standard/custom field ID or a synthetic negative ID for calculated fields.", "type": "integer" }, "pageId": { "description": "ID of the page the field belongs to. Calculated fields may use `-1`. Fields without a usable page ID are not available in webhooks.", "type": "integer" }, "tableId": { "description": "ID of the table the field belongs to", "oneOf": [ { "type": "integer" }, { "type": "null" } ] } }, "type": "object" }, "WebHookPostFieldDataObjectCollection": { "title": "WebHookPostFieldDataObjectCollection", "type": "array", "items": { "$ref": "#/components/schemas/WebHookPostFieldDataObject" } }, "WebHookPostFieldPageDataObject": { "title": "WebHookPostFieldPageDataObject", "required": [ "id", "name" ], "properties": { "id": { "description": "Page ID", "type": "integer" }, "name": { "description": "Page Name", "type": "string" } }, "type": "object" }, "WebHookPostFieldPageDataObjectCollection": { "title": "WebHookPostFieldPageDataObjectCollection", "type": "array", "items": { "$ref": "#/components/schemas/WebHookPostFieldPageDataObject" } }, "WebHookPostFieldResponseObject": { "title": "WebHookPostFieldResponseObject", "required": [ "fields", "tables", "pages" ], "properties": { "fields": { "$ref": "#/components/schemas/WebHookPostFieldDataObjectCollection", "description": "List of fields that can be included in the webhook payload. Includes standard, custom, table, and calculated fields; some calculated fields use synthetic negative IDs." }, "pages": { "$ref": "#/components/schemas/WebHookPostFieldPageDataObjectCollection", "description": "Pages referenced by the postable fields in the webhook payload." }, "tables": { "$ref": "#/components/schemas/WebHookPostFieldTableDataObjectCollection", "description": "Tables referenced by the postable fields in the webhook payload." } }, "type": "object" }, "WebHookPostFieldTableDataObject": { "title": "WebHookPostFieldTableDataObject", "required": [ "id", "name" ], "properties": { "id": { "description": "Table ID", "type": "integer" }, "name": { "description": "Table Name", "type": "string" } }, "type": "object" }, "WebHookPostFieldTableDataObjectCollection": { "title": "WebHookPostFieldTableDataObjectCollection", "type": "array", "items": { "$ref": "#/components/schemas/WebHookPostFieldTableDataObject" } } }, "responses": { "WebhookSuccessResponse": { "description": "Webhook received successfully (200-299 status code)." }, "WebhookClientErrorResponse": { "description": "Client error (400-499 status code) - the webhook endpoint intentionally rejected the request. BambooHR will not retry webhooks that return 4xx status codes." }, "WebhookServerErrorResponse": { "description": "Server error (500+ status code). BambooHR will automatically retry this webhook up to 5 times using exponential backoff (5min, 10min, 20min, 40min, 80min intervals)." } }, "securitySchemes": { "oauth": { "type": "oauth2", "description": "OAuth 2.0 authentication", "flows": { "authorizationCode": { "authorizationUrl": "/authorize.php", "tokenUrl": "/token.php", "scopes": { "access_level": "View and manage User Access Levels", "access_level.write": "View and manage User Access Levels", "benchmarking:compensation": "Compensation Benchmarking", "compensation_benchmarks": "Read and write access to compensation benchmarking data including job-location pairs, benchmark values, and benchmark sources.", "compensation_benchmarks.write": "Read and write access to compensation benchmarking data including job-location pairs, benchmark values, and benchmark sources.", "pay_grades_and_bands": "Read access to levels and bands data including compensation level groups, levels, pay bands, and job title assignments.", "pay_grades_and_bands.write": "Read access to levels and bands data including compensation level groups, levels, pay bands, and job title assignments.", "planning_cycles": "Read access to compensation planning cycle data including cycle lists, details, summaries, employees, budgets, approvals, admins, and change communication settings.", "planning_cycles.write": "Read access to compensation planning cycle data including cycle lists, details, summaries, employees, budgets, approvals, admins, and change communication settings.", "background_checks": "Access background check information", "background_checks.write": "Access background check information", "benefit": "Get Benefit Details", "benefit.write": "Get Benefit Details", "company_file": "Company Files", "company_file.write": "Company Files", "company:info": "Company Info", "company:details": "Access to comprehensive company information including profile fields, metadata, and configuration settings", "company:details.write": "Access to comprehensive company information including profile fields, metadata, and configuration settings", "customer_onboarding": "Customer Onboarding workflows and setup", "customer_onboarding.write": "Customer Onboarding workflows and setup", "company:administration": "Company Administration", "company:administration.write": "Company Administration", "data_cleaner": "Allows viewing data cleaning job data.", "data_cleaner.write": "Allows viewing data cleaning job data.", "data_hygiene": "Read access to data hygiene findings.", "data_hygiene.write": "Read access to data hygiene findings.", "hr_benchmarks": "Read access to HR benchmarking topics and company-vs-benchmark data.", "deductions": "Access to employee deductions information", "deductions.write": "Access to employee deductions information", "payroll": "Allows access to payroll related fields", "payroll.write": "Allows access to payroll related fields", "payroll:beneficial_owners": "Access to beneficial ownership certification information for payroll compliance, including business structure, exemption status, and individual beneficial owner details with personal information and ownership percentages", "payroll:beneficial_owners.write": "Access to beneficial ownership certification information for payroll compliance, including business structure, exemption status, and individual beneficial owner details with personal information and ownership percentages", "payroll:legal_entities": "Access to payroll legal entities information, including FEIN and legal entity details", "payroll:retirements": "Access to employee payroll retirements information", "payroll:pay_schedules": "Access to payroll pay schedule information", "payroll:pay_periods": "Access to payroll pay period information", "payroll:earnings": "Access to earnings records within a pay cycle", "payroll:pay_cycles": "Access to pay cycle records", "payroll:pay_stubs": "Access to employee pay stub information including gross pay, net pay, deductions, taxes, and YTD totals", "payroll:pay_stubs.write": "Access to employee pay stub information including gross pay, net pay, deductions, taxes, and YTD totals", "payroll:payrolls": "Access to payroll information including pay dates and processing details", "payroll:ach_returns": "Access to ACH return information including return details and resolution", "payroll:ach_returns.write": "Access to ACH return information including return details and resolution", "payroll:tipped_occupations": "Access to Treasury Tipped Occupation Codes and the codes assigned to each job title, used to report Box 14b on employee W-2s", "payroll:tipped_occupations.write": "Access to Treasury Tipped Occupation Codes and the codes assigned to each job title, used to report Box 14b on employee W-2s", "esignature:instance": "Access eSignature instance data and signing workflows, including viewing instances, completing signing steps, and managing user signatures.", "esignature:instance.write": "Access eSignature instance data and signing workflows, including viewing instances, completing signing steps, and managing user signatures.", "employee:assets": "Assets Assigned to Employee", "employee:assets.write": "Assets Assigned to Employee", "employee:emergency_contacts": "Employee Contacts and Emergency Contacts", "employee:emergency_contacts.write": "Employee Contacts and Emergency Contacts", "employee:vaccination": "Employee COVID-19 Data", "employee:vaccination.write": "Employee COVID-19 Data", "employee:custom_fields": "Employee Custom Fields", "employee:custom_fields.write": "Employee Custom Fields", "employee:custom_fields_encrypted": "Employee Encrypted Custom Fields", "employee:custom_fields_encrypted.write": "Employee Encrypted Custom Fields", "employee:demographic": "Includes Employee Ethnicity and Nationality", "employee:demographic.write": "Includes Employee Ethnicity and Nationality", "employee:dependent": "Employee Dependent Information", "employee:dependent.write": "Employee Dependent Information", "employee:dependent:ssn": "Employee Dependent SSN/SIN", "employee:dependent:ssn.write": "Employee Dependent SSN/SIN", "employee:education": "Employee Education Information", "employee:education.write": "Employee Education Information", "employee:contact": "Employee Contact", "employee:contact.write": "Employee Contact", "employee:identification": "Employee Identification", "employee:identification.write": "Employee Identification", "employee:job": "Employee Job Information", "employee:job.write": "Employee Job Information", "employee:management": "Manage Employees", "employee:management.write": "Manage Employees", "employee:photo": "Employee Photo", "employee:photo.write": "Employee Photo", "employee": "All non-sensitive employee-related information", "employee.write": "All non-sensitive employee-related information", "employee:name": "Includes Any Employee Name Details", "employee:name.write": "Includes Any Employee Name Details", "employee_directory": "Employee Directory", "employee:file": "Employee Files", "employee:file.write": "Employee Files", "employee:compensation": "Employee Payroll Information", "employee:compensation.write": "Employee Payroll Information", "employee:providers": "Allows access to employee provider information", "employee:providers.write": "Allows access to employee provider information", "employee:providers:payroll": "Allows access to employee payroll provider information", "employee:providers:payroll.write": "Allows access to employee payroll provider information", "employee:tabs": "View and manage custom employee tabs.", "employee:tabs.write": "View and manage custom employee tabs.", "sensitive_employee:protected_info": "Employee SSN, SIN, Birthday", "sensitive_employee:protected_info.write": "Employee SSN, SIN, Birthday", "sensitive_employee:address": "Includes Any Employee Address Details", "sensitive_employee:address.write": "Includes Any Employee Address Details", "sensitive_employee:creditcards": "Credit Cards Assigned to Employee", "sensitive_employee:creditcards.write": "Credit Cards Assigned to Employee", "employee:payroll.write": "Employee Payroll Information", "ask_bamboohr:chat_messages": "Read and write chat messages in Ask BambooHR on behalf of the authenticated user", "ask_bamboohr:chat_messages.write": "Read and write chat messages in Ask BambooHR on behalf of the authenticated user", "ask_bamboohr:settings": "View and manage Ask BambooHR feature settings", "ask_bamboohr:settings.write": "View and manage Ask BambooHR feature settings", "ask_bamboohr:policy_documents": "View and manage policy documents used as sources in Ask BambooHR", "ask_bamboohr:policy_documents.write": "View and manage policy documents used as sources in Ask BambooHR", "equity": "Read access to company-level equity settings such as calculation type, valuation, share counts, pricing, and vesting-related configuration.", "equity.write": "Read access to company-level equity settings such as calculation type, valuation, share counts, pricing, and vesting-related configuration.", "field": "Query Lists of Fields, Tables and Lists.", "field.write": "Query Lists of Fields, Tables and Lists.", "goal": "Access performance goals data for employees.", "goal.write": "Access performance goals data for employees.", "performance:assessments": "Access performance assessment data for employees", "performance:assessments.write": "Access performance assessment data for employees", "performance:feedback": "Access performance feedback data for employees", "performance:feedback.write": "Access performance feedback data for employees", "performance:settings": "Access and manage performance management configurations", "performance:settings.write": "Access and manage performance management configurations", "performance:one_on_ones": "Access one on one meeting data for employees", "performance:one_on_ones.write": "Access one on one meeting data for employees", "enps:settings": "View and manage eNPS feature settings", "enps:settings.write": "View and manage eNPS feature settings", "employee_wellbeing:settings": "View and manage Employee Wellbeing feature settings", "employee_wellbeing:settings.write": "View and manage Employee Wellbeing feature settings", "global_employment": "Allows access to data and workflows for Employer of Record (EOR) employees and contractors managed in Remote.", "global_employment.write": "Allows access to data and workflows for Employer of Record (EOR) employees and contractors managed in Remote.", "job_organization": "Manage job organization, including job profiles", "job_organization.write": "Manage job organization, including job profiles", "hiring:job_openings": "Access and manage job openings, pipelines, rules, questions, collaborators, and job board postings", "hiring:job_openings.write": "Access and manage job openings, pipelines, rules, questions, collaborators, and job board postings", "hiring:applications": "Access and manage applications, candidates, interviews, and candidate emails", "hiring:applications.write": "Access and manage applications, candidates, interviews, and candidate emails", "hiring:offers": "Access and manage offers, offer terms, and offer letters", "hiring:offers.write": "Access and manage offers, offer terms, and offer letters", "hiring:checkr": "Access and manage Checkr background checks for candidates", "hiring:checkr.write": "Access and manage Checkr background checks for candidates", "hiring:talent_pools": "Access and manage talent pools, pool candidates, and pool collaborators", "hiring:talent_pools.write": "Access and manage talent pools, pool candidates, and pool collaborators", "hiring:settings": "Access and manage hiring configuration including statuses, candidate sources, and email and offer letter templates", "hiring:settings.write": "Access and manage hiring configuration including statuses, candidate sources, and email and offer letter templates", "offline_access": "Allows the application to reauthenticate to BambooHR with a refresh token", "openid": "Allows the application to authenticate with BambooHR", "recognitions:manage": "Access and manage Rewards and Recognition settings, exclusion rules, and point allocations, and view Rewards and Recognition reports for the company", "recognitions:manage.write": "Access and manage Rewards and Recognition settings, exclusion rules, and point allocations, and view Rewards and Recognition reports for the company", "recognitions:suggestions": "Read and write recognition suggestions for employees, including viewer suggestion pools and one-off or broadcast suggestion writes", "recognitions:suggestions.write": "Read and write recognition suggestions for employees, including viewer suggestion pools and one-off or broadcast suggestion writes", "report": "Allows access to query custom reports and creation of bulk data requests", "report.write": "Allows access to query custom reports and creation of bulk data requests", "tasks": "Manage Employee Tasks", "tasks.write": "Manage Employee Tasks", "calendar:events": "View company calendar events.", "holidays": "View and manage company holidays and view the global holiday catalog.", "holidays.write": "View and manage company holidays and view the global holiday catalog.", "time_off": "Employee Time Off Information", "time_off.write": "Employee Time Off Information", "time_off:requests": "View and manage employee time off requests, including submitting, approving, and denying them.", "time_off:requests.write": "View and manage employee time off requests, including submitting, approving, and denying them.", "time_off:categories": "View and manage time off categories, the types of time off a company offers.", "time_off:categories.write": "View and manage time off categories, the types of time off a company offers.", "time_off:policies": "View and manage time off policies, the rules that control how employees accrue and use time off.", "time_off:policies.write": "View and manage time off policies, the rules that control how employees accrue and use time off.", "time_tracking": "Add and Manage Hours Worked.", "time_tracking.write": "Add and Manage Hours Worked.", "time_tracking:breaks": "View and manage meal and rest break tracking information.", "time_tracking:breaks.write": "View and manage meal and rest break tracking information.", "time_tracking:shift_differentials": "View and manage time tracking shift differentials.", "time_tracking:shift_differentials.write": "View and manage time tracking shift differentials.", "time_tracking:kiosks": "View and manage time tracking kiosks.", "time_tracking:kiosks.write": "View and manage time tracking kiosks.", "time_tracking:time_clocks": "View and manage time tracking time clocks.", "time_tracking:time_clocks.write": "View and manage time tracking time clocks.", "time_tracking:timesheets": "View and manage time tracking timesheets.", "time_tracking:timesheets.write": "View and manage time tracking timesheets.", "time_tracking:project": "View and manage time tracking projects and tasks.", "time_tracking:project.write": "View and manage time tracking projects and tasks.", "time_tracking:configurations": "View and manage time tracking configurations.", "time_tracking:configurations.write": "View and manage time tracking configurations.", "time_tracking:employees": "View and manage employee time tracking enrollment.", "time_tracking:employees.write": "View and manage employee time tracking enrollment.", "time_tracking:imports": "View and manage time tracking imports.", "time_tracking:imports.write": "View and manage time tracking imports.", "scheduling:schedules": "View and manage schedules.", "scheduling:schedules.write": "View and manage schedules.", "scheduling:shifts": "View and manage shifts within schedules.", "scheduling:shifts.write": "View and manage shifts within schedules.", "training": "Get Training Details", "training.write": "Get Training Details", "total_rewards": "Read and write access to Total Rewards data including employee statements, onboarding steps, and custom disclaimers.", "total_rewards.write": "Read and write access to Total Rewards data including employee statements, onboarding steps, and custom disclaimers.", "user": "Get Users List", "user.write": "Get Users List", "user:management": "Manage state of company users", "user:management.write": "Manage state of company users", "webhooks": "Create and Manage Application Specific Webhooks", "webhooks.write": "Create and Manage Application Specific Webhooks", "workflows:external_tasks": "View and manage workflow external tasks.", "workflows:external_tasks.write": "View and manage workflow external tasks.", "workflows:instances": "View and manage workflow instances.", "workflows:instances.write": "View and manage workflow instances.", "workflows:triggers": "View and manage automation triggers.", "workflows:triggers.write": "View and manage automation triggers.", "error_management": "Manage errors and notifications", "error_management.write": "Manage errors and notifications", "public.integration": "Allows access to all authorized scopes for all employees. Must be installed by an admin.", "public.user": "Authorizes the application to perform scoped actions on behalf of the user who authorized the application.", "alerts": "Provides read and write access to alert configurations.", "alerts.write": "Provides read and write access to alert configurations.", "approval_workflows": "Provides read and write access to approval workflow configurations.", "approval_workflows.write": "Provides read and write access to approval workflow configurations.", "compensation_tools": "Read access to the list of available compensation tools and upsell information for the company.", "employee_verifications": "Provides read and write access to employee verification records, including I-9 and E-Verify verification data and partner role assignments.", "employee_verifications.write": "Provides read and write access to employee verification records, including I-9 and E-Verify verification data and partner role assignments.", "esignature": "Provides read access to electronic signature records and requests.", "onboarding": "Provides read access to employee new hire paperwork and onboarding records.", "onboarding.write": "Provides read access to employee new hire paperwork and onboarding records.", "gridlets": "Gridlets", "gridlets.write": "Gridlets", "meta": "Read-only access to public BambooHR meta reference endpoints such as countries, subdivisions, timezones, currencies, and related lookup data used to configure integrations.", "mcp": "Grants access to Model Context Protocol (MCP) endpoints", "insights": "Insight data", "insights.write": "Insight data", "marketplace:catalog": "Read marketplace catalog data, including app categories and solutions.", "marketplace:data_sources": "Read marketplace data source identity, including whether a source is BambooHR or a partner integration." } } } }, "basic": { "type": "http", "scheme": "basic" } } }, "tags": [ { "name": "Webhooks", "description": "The Webhooks API lets you subscribe to real-time notifications when employee or company data changes in BambooHR. Use it to configure webhooks, inspect available fields, and monitor delivery logs. For a full overview of how webhooks work, including security, payload formats, and retry behavior, see the [webhooks documentation](docs/webhooks)." }, { "name": "Webhook Events", "description": "Browse the catalog of available webhook event types." }, { "name": "Public API", "description": "Public API" } ], "webhooks": { "company-integrations.updated": { "post": { "tags": [ "Webhook Events", "Public API" ], "summary": "Company Integrations Updated", "description": "\nTriggered when company integrations are updated.\n\n### Behavior & Constraints\n- **Permission Checking**: This event does **not** enforce permission checking. The webhook will fire for all subscribers regardless of the API token's permissions.\n- **Event Scope**: This event fires when any integration settings are modified for the company, including enabling, disabling, or updating integration configurations.\n", "operationId": "company-integrations-updated-webhook", "requestBody": { "description": "Webhook payload containing company integration update information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyIntegrationsUpdatedWebhookPayload" } } } }, "responses": { "200": { "$ref": "#/components/responses/WebhookSuccessResponse" }, "400": { "$ref": "#/components/responses/WebhookClientErrorResponse" }, "500": { "$ref": "#/components/responses/WebhookServerErrorResponse" } }, "x-team-name": "plat-api" } }, "company.updated": { "post": { "tags": [ "Webhook Events", "Public API" ], "summary": "Company Updated", "description": "\nTriggered when company information or company status changes.\n\n### Behavior & Constraints\n- This event is emitted for general company updates.\n- When the underlying change is a company status change, the emitted event depends on the new status:\n - If the new status is `DELETED` or `CANCELLED`, the system emits `company.deleted` instead.\n - Otherwise the system emits `company.updated`.\n", "operationId": "company-updated-webhook", "requestBody": { "description": "Webhook payload containing information about the company update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyUpdatedWebhookPayload" } } } }, "responses": { "200": { "$ref": "#/components/responses/WebhookSuccessResponse" }, "400": { "$ref": "#/components/responses/WebhookClientErrorResponse" }, "500": { "$ref": "#/components/responses/WebhookServerErrorResponse" } }, "x-team-name": "grease-monkeys" } }, "company.deleted": { "post": { "tags": [ "Webhook Events", "Public API" ], "summary": "Company Deleted", "description": "\nTriggered when a company status change results in the company being considered deleted/closed.\n\n### Behavior & Constraints\n- This event is emitted when the new company status is `DELETED` or `CANCELLED`.\n- For other company updates and status changes, the system emits `company.updated`.\n", "operationId": "company-deleted-webhook", "requestBody": { "description": "Webhook payload containing information about the company deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyDeletedWebhookPayload" } } } }, "responses": { "200": { "$ref": "#/components/responses/WebhookSuccessResponse" }, "400": { "$ref": "#/components/responses/WebhookClientErrorResponse" }, "500": { "$ref": "#/components/responses/WebhookServerErrorResponse" } }, "x-team-name": "grease-monkeys" } }, "employee.created": { "post": { "tags": [ "Webhook Events", "Public API" ], "summary": "Employee Created", "description": "\nTriggered when a new employee is created.\n\n### Behavior & Constraints\n- **Creation Sequence**: When an employee is created, both `employee.created` and `employee.updated` events fire sequentially due to the create-then-initialize pattern.\n- **Data Availability**: The `data` object contains the `companyId` and `employeeId` of the newly created employee.\n- **Permission Checking**: This event does **not** enforce permission checking. The webhook will fire for all subscribers regardless of the API token's field-level permissions.\n\n### Deprecation Notice\n**Note:** This event is the modern replacement for the legacy `employee_with_fields.created` event. While the legacy event is deprecated, it will remain available for the foreseeable future to support existing integrations. We encourage using this new event for all new development.\n\n**Important:** You cannot subscribe to both this new event and the legacy `employee_with_fields` events on the same webhook. Webhooks created without specifying any events will default to the legacy behavior, effectively subscribing to the `employee_with_fields` events automatically.\n", "operationId": "employee-created-webhook", "requestBody": { "description": "Webhook payload containing information about the employee creation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeCreatedWebhookPayload" } } } }, "responses": { "200": { "$ref": "#/components/responses/WebhookSuccessResponse" }, "400": { "$ref": "#/components/responses/WebhookClientErrorResponse" }, "500": { "$ref": "#/components/responses/WebhookServerErrorResponse" } }, "x-team-name": "plat-api" } }, "employee.deleted": { "post": { "tags": [ "Webhook Events", "Public API" ], "summary": "Employee Deleted", "description": "\nTriggered when an employee is deleted.\n\n### Behavior & Constraints\n- **Permission Checking**: This event does **not** enforce permission checking. The webhook will fire for all subscribers regardless of the API token's field-level permissions.\n\n### Deprecation Notice\n**Note:** This event is the modern replacement for the legacy `employee_with_fields.deleted` event. While the legacy event is deprecated, it will remain available for the foreseeable future to support existing integrations. We encourage using this new event for all new development.\n\n**Important:** You cannot subscribe to both this new event and the legacy `employee_with_fields` events on the same webhook. Webhooks created without specifying any events will default to the legacy behavior, effectively subscribing to the `employee_with_fields` events automatically.\n", "operationId": "employee-deleted-webhook", "requestBody": { "description": "Webhook payload containing information about the employee deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeDeletedWebhookPayload" } } } }, "responses": { "200": { "$ref": "#/components/responses/WebhookSuccessResponse" }, "400": { "$ref": "#/components/responses/WebhookClientErrorResponse" }, "500": { "$ref": "#/components/responses/WebhookServerErrorResponse" } }, "x-team-name": "plat-api" } }, "employee.updated": { "post": { "tags": [ "Webhook Events", "Public API" ], "summary": "Employee Updated", "description": "\nTriggered when an employee record is updated and at least one of the monitored fields has changed.\n\n### Behavior & Constraints\n- **Monitoring**: At least one `monitorField` is required when subscribing to this event via `POST /api/v1/webhooks`.\n- **Permissions**: For API-created webhooks, this event will not fire if the webhook creator lacks access to all monitored fields being changed.\n\n### Detailed Description\n- **Creation Sequence**: When an employee is created, both `employee.created` and `employee.updated` events fire sequentially due to the create-then-initialize pattern.\n- **Field Consolidation**: When multiple fields change simultaneously, they may be consolidated into a single event. Currently, custom field updates and standard field updates are grouped separately and may fire as two events.\n- **Effective Dates**: For history-tracked fields (e.g., `jobTitle`, `payRate`), events fire only when changes take effect, not when future-dated changes are created.\n- **Changed Fields**: The `changedFields` array contains the API aliases for fields that changed and are monitored by this webhook. Aliases match those returned by `GET /api/v1/webhooks/monitor_fields`.\n\n### Deprecation Notice\n**Note:** This event is the modern replacement for the legacy `employee_with_fields.updated` event. While the legacy event is deprecated, it will remain available for the foreseeable future to support existing integrations. We encourage using this new event for all new development.\n\n**Important:** You cannot subscribe to both this new event and the legacy `employee_with_fields` events on the same webhook. Webhooks created without specifying any events will default to the legacy behavior, effectively subscribing to the `employee_with_fields` events automatically.\n", "operationId": "employee-updated-webhook", "requestBody": { "description": "Webhook payload containing information about the employee update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeUpdatedWebhookPayload" } } } }, "responses": { "200": { "$ref": "#/components/responses/WebhookSuccessResponse" }, "400": { "$ref": "#/components/responses/WebhookClientErrorResponse" }, "500": { "$ref": "#/components/responses/WebhookServerErrorResponse" } }, "x-team-name": "plat-api" } } }, "x-tagGroups": [ { "name": "Account Information", "tags": [ "Account Information" ] }, { "name": "Alerts", "tags": [ "Alerts" ] }, { "name": "Applicant Tracking", "tags": [ "Applicant Tracking" ] }, { "name": "Benefits", "tags": [ "Benefits" ] }, { "name": "Change Tracking", "tags": [ "Change Tracking" ] }, { "name": "Company Details", "tags": [ "Company", "Company Profile" ] }, { "name": "Compensation", "tags": [ "Compensation", "Compensation Benchmarking", "Compensation Planning", "Pay Grades & Bands", "Total Rewards" ] }, { "name": "Custom Fields", "tags": [ "Custom Fields" ] }, { "name": "Datasets and Reporting", "tags": [ "Custom Reports", "Datasets", "Reports" ] }, { "name": "Employee Details", "tags": [ "Employees", "Photos" ] }, { "name": "Employee Tables", "tags": [ "Employee Tables" ] }, { "name": "Employee Verification", "tags": [ "Employee Verification" ] }, { "name": "Field Metadata", "tags": [ "Field Metadata" ] }, { "name": "Files", "tags": [ "Company Files", "Employee Files" ] }, { "name": "Goals", "tags": [ "Goals" ] }, { "name": "Holidays", "tags": [ "Holidays" ] }, { "name": "Hours", "tags": [ "Hours" ] }, { "name": "Locations", "tags": [ "Locations" ] }, { "name": "Login", "tags": [ "Login" ] }, { "name": "Onboarding", "tags": [ "Onboarding" ] }, { "name": "Scheduling", "tags": [ "Scheduling" ] }, { "name": "Time Off", "tags": [ "Time Off" ] }, { "name": "Time Tracking", "tags": [ "Time Tracking", "Meal & Rest Breaks" ] }, { "name": "Training", "tags": [ "Training" ] }, { "name": "Webhooks", "tags": [ "Webhooks", "Webhook Events" ] } ] } ```