--- updatedAt: 2026-05-13T22:58:00.000Z agentTools: projectIndex: https://documentation.bamboohr.com/llms.txt --- # Create Shift Creates a new shift in the specified schedule. OAuth Scopes: scheduling:shifts.write, time_tracking.write # 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/scheduling/shifts": { "post": { "tags": [ "Scheduling", "Public API" ], "summary": "Create Shift", "description": "Creates a new shift in the specified schedule.\n\nOAuth Scopes: scheduling:shifts.write, time_tracking.write", "operationId": "scheduling-create-shift", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Scheduling-CreateSchedulingShiftRequest-V1" } } } }, "responses": { "201": { "description": "Successfully created a shift.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Scheduling-SchedulingShift-V1" } } } }, "403": { "description": "Forbidden - user does not have permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsResponse" } } } }, "404": { "description": "Not Found - the referenced schedule does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsResponse" } } } }, "422": { "description": "Invalid request data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsResponse" } } } } }, "security": [ { "basic": [] }, { "oauth": [ "scheduling:shifts.write" ] }, { "oauth": [ "time_tracking.write" ] } ] } } }, "components": { "schemas": { "Scheduling-CreateSchedulingShiftRequest-V1": { "description": "Fields required to create a scheduling shift.", "required": [ "scheduleId", "status", "color", "timezone", "start", "end" ], "properties": { "scheduleId": { "description": "The ID of the schedule the shift belongs to.", "type": "string", "format": "uuid", "example": "0199de9b-6bcb-77e7-941d-3caf74b9a372" }, "name": { "description": "The name of the shift.", "example": "Morning Shift", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "description": "The status of the shift.", "enum": [ "planned", "published" ] }, "color": { "description": "6 character color hex code.", "type": "string", "maxLength": 6, "minLength": 6, "example": "00FFAA" }, "timezone": { "description": "The timezone for the shift. Defaults to schedule timezone.", "example": "America/Denver" }, "capacity": { "description": "The expected headcount for the shift. If null, has no restrictions.", "default": null, "example": 1, "oneOf": [ { "type": "integer", "maximum": 999, "minimum": 1 }, { "type": "null" } ] }, "claimable": { "description": "Whether employees can claim this shift. A claimable shift must have a capacity: a request that would leave the shift claimable with a null capacity is rejected with a 422. Not gated by any release toggle.", "type": "boolean", "default": false, "example": false }, "claimsRequireApproval": { "description": "Whether a claim on this shift requires manager approval. Defaults to the schedule's claimsRequireApprovalDefault when omitted.", "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "employeeIds": { "description": "What employees are assigned to this shift?", "type": "array", "items": { "type": "integer" }, "default": [] }, "start": { "description": "UTC timestamp of the start of the shift.", "type": "string", "format": "date-time", "example": "2025-01-01T06:00:00Z" }, "end": { "description": "UTC timestamp of the end of the shift.", "type": "string", "format": "date-time", "example": "2025-01-01T14:00:00Z" }, "recurrenceRule": { "description": "The recurrence rule. Follows the iCalendar RFC 5545 RRULE syntax.", "example": "FREQ=WEEKLY;INTERVAL=1", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "recurrenceDtstart": { "description": "The UTC start time for a recurring shift (anchor point for the recurrence rule).", "example": "2024-01-01T09:00:00Z", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "recurrenceDtend": { "description": "The UTC end time for a recurring shift.", "example": "2024-12-01T17:00:00Z", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "recurrenceUntil": { "description": "The UTC datetime when the recurrence series stops generating new occurrences (UNTIL in RRULE).", "example": "2024-12-31T23:59:59Z", "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "type": "object" }, "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" }, "Scheduling-SchedulingShift-V1": { "description": "A shift for scheduling", "required": [ "id", "scheduleId", "status", "color", "start", "end", "timezone", "claimable", "claimsRequireApproval" ], "properties": { "id": { "description": "The ID of the shift. This can be the UUIDv7 of the shift instance, or a composite ID (_) for uninstantiated recurring shifts.", "type": "string", "readOnly": true, "example": "019aa09f-0712-74cb-9186-8ad0eb6038dc_20240101T093000" }, "scheduleId": { "description": "The ID of the schedule the shift belongs to.", "type": "string", "format": "uuid", "example": "0199de9b-6bcb-77e7-941d-3caf74b9a372" }, "name": { "description": "The name of the shift.", "example": "Morning Shift", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "description": "The status of the shift.", "enum": [ "planned", "published", "cancelled", "deleted" ] }, "color": { "description": "6 character color hex code.", "type": "string", "example": "00FFAA" }, "capacity": { "description": "The expected headcount for the shift. Null when capacity is not tracked for this shift.", "example": 1, "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "claimable": { "description": "Whether employees can claim this shift.", "type": "boolean", "example": false }, "claimsRequireApproval": { "description": "Whether a claim on this shift requires manager approval before it takes effect.", "type": "boolean", "example": true }, "start": { "description": "UTC timestamp of the start of the shift.", "example": "2025-01-01T06:00:00Z", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "end": { "description": "UTC timestamp of the end of the shift.", "example": "2025-01-01T14:00:00Z", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "timezone": { "description": "The timezone for the shift.", "type": "string", "example": "America/Denver" }, "recurrenceRule": { "description": "The recurrence rule. Follows the iCalendar RFC 5545 RRULE syntax.", "example": "FREQ=WEEKLY;INTERVAL=1", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "recurrenceId": { "description": "The stable identifier for a recurrence, which is the original start of shift according to recurrence rules. Null for non-recurring shifts.", "example": "20240101T090000", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "recurrenceDtstart": { "description": "The UTC start time for a recurring shift and the anchor point for the recurrence rule. Null for non-recurring shifts.", "example": "2024-01-01T09:00:00Z", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "recurrenceDtend": { "description": "The UTC end time for a recurring shift. Null for non-recurring shifts.", "example": "2024-12-31T23:59:59Z", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "recurrenceUntil": { "description": "The UTC datetime when the recurrence series stops generating new occurrences (UNTIL in RRULE). Null for non-recurring shifts.", "example": "2024-12-31T23:59:59Z", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "employeeIds": { "description": "The list of employee IDs currently assigned.", "type": "array", "items": { "type": "integer" }, "example": [ 10, 20 ] }, "unpublishedChanges": { "description": "The pending changes that have not been published.", "oneOf": [ { "type": "object" }, { "type": "null" } ] }, "createdAt": { "description": "UTC timestamp when the shift was created", "type": "string", "format": "date-time", "readOnly": true, "example": "2025-01-01T06:00:00Z" }, "updatedAt": { "description": "UTC timestamp when the shift was last updated", "readOnly": true, "example": "2025-01-01T06:00:00Z", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "deletedAt": { "description": "UTC timestamp when the shift was deleted", "readOnly": true, "example": "2025-01-01T06:00:00Z", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "type": "object" }, "ProblemDetailsResponse": { "description": "problem fields shared by problem responses and record-level errors.", "properties": { "type": { "description": "Problem type URI identifying the error category", "type": "string" }, "title": { "description": "Short, human-readable summary of the problem type", "type": "string" }, "status": { "description": "HTTP status code for the error", "type": "integer" }, "detail": { "description": "Detailed, human-readable explanation specific to this occurrence of the problem", "type": "string" }, "instance": { "description": "URI reference that identifies the specific occurrence of the problem", "type": "string" }, "code": { "description": "Application-specific error code", "type": "string" }, "fields": { "type": "object", "example": { "amount": "must by > 0" }, "additionalProperties": { "type": "string" } } }, "type": "object" } }, "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": "Scheduling", "description": "Manage employee work schedules and shifts." }, { "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" ] } ] } ```