--- updatedAt: 2026-08-25T20:19:06.000Z agentTools: projectIndex: https://documentation.bamboohr.com/llms.txt --- # List Time Tracking Kiosks Returns a paginated list of time tracking kiosks. Deleted kiosks are never returned. Supports an OData-style `filter`, an `orderBy` sort expression, and `select` sparse fieldsets. Results are sorted by name ascending when `orderBy` is omitted; name ordering is case-insensitive. Pagination is page-based via `page` and `pageSize` (defaults: page 1, pageSize 20, max 100). OAuth Scopes: time_tracking:kiosks # 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/time-tracking/kiosks": { "get": { "tags": [ "Time Tracking", "Public API" ], "summary": "List Time Tracking Kiosks", "description": "Returns a paginated list of time tracking kiosks. Deleted kiosks are never returned. Supports an OData-style `filter`, an `orderBy` sort expression, and `select` sparse fieldsets. Results are sorted by name ascending when `orderBy` is omitted; name ordering is case-insensitive. Pagination is page-based via `page` and `pageSize` (defaults: page 1, pageSize 20, max 100).\n\nOAuth Scopes: time_tracking:kiosks", "operationId": "list-time-tracking-kiosks", "parameters": [ { "name": "filter", "in": "query", "description": "OData v4 filter expression. Filterable fields: `name`, `lastUsed`, `createdAt`, `updatedAt`. Example: `name eq 'Front Desk Kiosk'`.", "required": false, "schema": { "type": "string" } }, { "name": "orderBy", "in": "query", "description": "Sort expression like `name asc, createdAt desc`. Allowed fields: `name`, `lastUsed`, `createdAt`, `updatedAt`. Defaults to `name asc`.", "required": false, "schema": { "type": "string" } }, { "name": "select", "in": "query", "description": "Comma-separated list of properties to return (sparse fieldsets).", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "The page to retrieve. Defaults to 1.", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "pageSize", "in": "query", "description": "The number of kiosks per page. Defaults to 20, minimum 10, maximum 100.", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 10 } } ], "responses": { "200": { "description": "A paginated list of kiosks.", "content": { "application/json": { "schema": { "title": "TimeTracking-PaginatedTimeTrackingKiosksResponse-V1", "type": "object", "allOf": [ { "$ref": "#/components/schemas/TimeTracking-PagePaginatedResponseData-V1" }, { "properties": { "data": { "$ref": "#/components/schemas/TimeTracking-TimeTrackingKioskCollection-V1", "description": "The kiosks on the current page." } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized. Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsResponse" } } } }, "403": { "description": "Forbidden. Insufficient permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsResponse" } } } }, "422": { "description": "Invalid query parameters (e.g., invalid `page`, `pageSize`, `filter`, `orderBy`, or `select`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsResponse" } } } } }, "security": [ { "basic": [] }, { "oauth": [ "time_tracking:kiosks" ] } ] } } }, "components": { "schemas": { "TimeTracking-PagePaginatedResponseData-V1": { "description": "Pagination envelope shared by page-based paginated Time Tracking endpoints.", "properties": { "meta": { "description": "Pagination metadata.", "required": [ "page", "pageSize", "totalPages", "totalItems" ], "properties": { "page": { "type": "integer", "example": 2 }, "pageSize": { "type": "integer", "example": 20 }, "totalPages": { "type": "integer", "example": 4 }, "totalItems": { "type": "integer", "example": 68 } }, "type": "object" }, "_links": { "description": "Pagination links. Keys are omitted when there is no previous/next page.", "properties": { "prev": { "description": "Link object for the previous page. Omitted on the first page.", "properties": { "href": { "type": "string" } }, "type": "object" }, "next": { "description": "Link object for the next page. Omitted on the last page.", "properties": { "href": { "type": "string" } }, "type": "object" } }, "type": "object" } }, "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" }, "TimeTracking-TimeTrackingKioskCollection-V1": { "description": "Collection of time tracking kiosks.", "type": "array", "items": { "$ref": "#/components/schemas/TimeTracking-TimeTrackingKiosk-V1" } }, "TimeTracking-TimeTrackingKiosk-V1": { "description": "A time tracking kiosk. A kiosk is a shared device employees use to clock in and out.", "properties": { "id": { "description": "The unique identifier for the time tracking kiosk.", "type": "string", "format": "uuid", "readOnly": true, "example": "a3f1c2d4-5b6e-4f70-8a91-2c3d4e5f6a7b" }, "name": { "description": "The name of the kiosk.", "type": "string", "maxLength": 255, "example": "Front Desk Kiosk" }, "lastUsed": { "description": "ISO 8601 timestamp when the kiosk last recorded a clock entry. Null when the kiosk has never been used.", "readOnly": true, "example": "2026-07-29T18:52:50Z", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "description": "ISO 8601 timestamp when the kiosk was created.", "readOnly": true, "example": "2026-01-29T18:52:50Z", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updatedAt": { "description": "ISO 8601 timestamp when the kiosk was last updated. Null when the kiosk has never been updated.", "readOnly": true, "example": "2026-02-09T17:56:06Z", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "deletedAt": { "description": "ISO 8601 timestamp when the kiosk was deleted. Null for active kiosks.", "readOnly": true, "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": "Time Tracking", "description": "The Time Tracking API integrates directly with BambooHR timesheets, letting you manage clock entries, hour entries, and time tracking projects.\n\nIf you only need to add hours for time off accrual calculations and payroll purposes, see the [Hours API](#tag/hours) instead.\n\n**Who has permissions to use the API?**\n\nPermissions follow the same structure as Time Tracking. If a user has access to view an employee's timesheet, they also have permission to retrieve their timesheet entries via the API." }, { "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" ] } ] } ```