# BambooHR Documentation

> Documentation for BambooHR

## Guides
- [Getting Started With The API](https://documentation.bamboohr.com/docs/getting-started.md): Our open API makes it easy to integrate other applications into BambooHR. Use this guide to get started sharing your data across systems.
- [Postman Collection](https://documentation.bamboohr.com/docs/postman-collection.md): We offer a downloadable version of the BambooHR API as an OpenAPI specification file. This file can be used to generate a Postman Collection or interact with the OpenAPI definition directly in your preferred tools.
- [Technical Overview](https://documentation.bamboohr.com/docs/api-details.md)
- [Field Types](https://documentation.bamboohr.com/docs/field-types.md)
- [Field Names](https://documentation.bamboohr.com/docs/list-of-field-names.md)
- [Table Name & Fields](https://documentation.bamboohr.com/docs/table-name-fields.md)
- [Webhooks](https://documentation.bamboohr.com/docs/webhooks.md)
- [Global Webhooks](https://documentation.bamboohr.com/docs/global-webhooks.md)
- [Permissioned Webhooks](https://documentation.bamboohr.com/docs/permissioned-webhooks.md)
- [Choosing a Payload Type](https://documentation.bamboohr.com/docs/choosing-a-payload-type.md)
- [Event-Based Webhooks](https://documentation.bamboohr.com/docs/event-based-webhooks.md)
- [Field-Based Webhooks](https://documentation.bamboohr.com/docs/field-based-webhooks.md)
- [Official SDKs](https://documentation.bamboohr.com/docs/sdks.md): Official BambooHR SDKs to accelerate your API integration.
- [Planned Changes to the API](https://documentation.bamboohr.com/docs/planned-changes-to-the-api.md)
- [Historical Changes to the API](https://documentation.bamboohr.com/docs/past-changes-to-the-api.md)
- [API Support](https://documentation.bamboohr.com/docs/api-support.md)
- [Give API Feedback](https://documentation.bamboohr.com/docs/give-api-feedback.md)

## API Reference
- [Account Information](https://documentation.bamboohr.com/reference/account-information.md)
- [Get Countries](https://documentation.bamboohr.com/reference/get-countries-options.md): Returns a JSON array of every country in the catalog, or a single country object when `isoCode` is supplied. Each element has `id` (Country ID), `name` (Country Name), and `isoCode` (ISO 3166-1 alpha-2 code or null when unset).  OAuth Scopes: field, meta
- [List states and provinces for a country by Country ID](https://documentation.bamboohr.com/reference/get-states-by-country-id.md): Returns the list of states or provinces for the specified country, sorted alphabetically by abbreviation (`options[].label`). Each item follows StateProvinceSchema: `label` is the subdivision abbreviation (e.g. "UT"), not the full name; `name` is the full subdivision name; `iso` is the ISO 3166-2 code (e.g. "US-UT"). Use a `countryId` from `GET /api/v1/meta/countries/options` (the `id` field on the row for the country) so it matches the countries list.  OAuth Scopes: field
- [List timezones](https://documentation.bamboohr.com/reference/5c5fb0f1211ae1c9451753f92f1053b6.md): Retrieves a paginated list of timezones. Supports pagination, filtering, sorting, and field projection via OData query parameters.
- [List Fields](https://documentation.bamboohr.com/reference/list-fields.md): Returns a list of all employee fields available in the account, including field ID, display name, data type, and whether the field is deprecated. Use this endpoint to discover which field names are valid for use with the Get Employee, Datasets, and other field-based endpoints. The response includes standard BambooHR fields as well as any custom fields configured in the account.  OAuth Scopes: employee, field
- [List List Fields](https://documentation.bamboohr.com/reference/list-list-fields.md): Returns details for all list fields in the account. Each list includes its field ID, alias, options, and whether it is manageable (editable). Lists with the `manageable` attribute set to `yes` can be modified via the PUT endpoint. Lists with the `multiple` attribute set to `yes` are fields that can have multiple values. Options with the `archived` attribute set to `yes` are soft-deleted and included so that historical data can reference the value — filter by `archived: no` to show only active options to end users.  OAuth Scopes: field
- [Update List Field Values](https://documentation.bamboohr.com/reference/update-list-field-values.md): Create, update, or archive options for a list field. To update an existing option, specify its `id`. To create a new option, omit `id`. To archive an option, set `archived` to `yes` — the option is soft-deleted and will continue to appear in GET responses for historical data integrity. To reactivate an archived option, set `archived` to `no`. The `archivedDate` field is server-set when an option is first archived and is not cleared if the option is later reactivated. Options on list fields with `manageable: no` cannot be modified and will return a 405.  OAuth Scopes: field.write
- [List Tabular Fields](https://documentation.bamboohr.com/reference/list-tabular-fields.md): Returns a list of all tabular (table-based) fields available in the account. Each table includes its alias and the fields it contains with their IDs, names, and types. Use this endpoint to discover which table names are valid for the table row endpoints (e.g., jobInfo, compensation, employmentStatus). For fields whose type is `list`, `multilist`, or another option-backed type, the field `id` can be matched to `fieldId` from `list-list-fields` to retrieve the account-level option list.  OAuth Scopes: field
- [List Users](https://documentation.bamboohr.com/reference/list-users.md): Returns all users for the company, optionally filtered by status. Each user entry includes a user ID, associated employee ID, name, email address (resolved in priority order: work, home, account), account status, and last login time when available.  Pass a comma-separated list of status values via the `status` query parameter to filter results. Valid values are `enabled` and `disabled`. If the parameter is omitted or contains only unrecognized values, users of all statuses are returned. Support admin accounts are always excluded from the response.  The response format is determined by the `Accept` request header. Send `Accept: application/json` to receive JSON; omit the header or send any other value to receive XML.  OAuth Scopes: user
- [Get all currency types](https://documentation.bamboohr.com/reference/get-all-currency-types.md): Returns a JSON array of supported currency catalog entries. Each object includes `id`, `code`, `name`, `symbol` (display symbol), and `symbolPosition`—an integer discriminator: `0` = symbol before the amount (prefix) and `1` = after the amount (postfix), matching the values returned in the JSON body.
- [Get company properties](https://documentation.bamboohr.com/reference/get-meta-company.md): Get company properties including ID, name, domain, and base API URL. Provides essential company metadata for API access.  OAuth Scopes: company:info
- [Get timezone by ID](https://documentation.bamboohr.com/reference/baa7162824294d030115568d1d8e6ca7.md): Retrieves a single timezone by its numeric ID. Returns the same timezone resource shape used by the list endpoint.  OAuth Scopes: meta
- [Get All Provinces](https://documentation.bamboohr.com/reference/get-all-provinces.md): Returns a flat list of all states and provinces across every country. Each entry includes a numeric ID, the countryId it belongs to, an abbreviation label (e.g. "UT"), an ISO 3166-2 code (e.g. "US-UT"), and a full name. Use the countryId field to filter client-side.  OAuth Scopes: meta
- [Get timezone by ZIP code](https://documentation.bamboohr.com/reference/10d66d8561dd7dac50ff9c21ef63d83b.md): Retrieves the timezone for a US ZIP code. Returns the same timezone resource shape used by the list endpoint. Only US ZIP codes are supported; valid 5-digit ZIPs that are not present in our reference data return a 404.  OAuth Scopes: meta
- [List alert templates](https://documentation.bamboohr.com/reference/0f0dcb585e5883175b6557c16cf6755a.md): Returns all available alert templates with their IDs, names, and group names. Use the returned IDs when creating or updating company alert configurations.  OAuth Scopes: alerts
- [List alert configurations](https://documentation.bamboohr.com/reference/6d0a073cbf3e97fe0409de42c68fe779.md): Returns all company alert configurations for the authenticated company.  OAuth Scopes: alerts
- [Create an alert configuration](https://documentation.bamboohr.com/reference/a05e93bc2eb9c39a40fbd71e6e07f3c6.md): Creates a new company alert configuration.  OAuth Scopes: alerts.write
- [Get an alert configuration](https://documentation.bamboohr.com/reference/14e66bfb5f075043221ce1e843c97493.md): Returns a single company alert configuration by ID.  OAuth Scopes: alerts
- [Update an alert configuration](https://documentation.bamboohr.com/reference/eb42aa2fa339ba5c08b147fc13c6a79e.md): Updates an existing company alert configuration.  OAuth Scopes: alerts.write
- [Applicant Tracking](https://documentation.bamboohr.com/reference/applicant-tracking.md)
- [Get Job Summaries](https://documentation.bamboohr.com/reference/get-job-summaries.md): Get a list of job opening summaries. The authenticated caller must have access to ATS settings. Results can be filtered by status group and sorted by various fields. By default returns all non-deleted job openings.  OAuth Scopes: hiring:applications
- [Get Job Applications](https://documentation.bamboohr.com/reference/get-applications.md): Get a list of applications. The authenticated caller must have access to ATS settings. Combine as many different optional parameter filters as you like.  OAuth Scopes: hiring:applications
- [Get Job Application Details](https://documentation.bamboohr.com/reference/get-application-details.md): Get the full details of a single application including applicant info, job details, questions and answers, and status history. The authenticated caller must have access to ATS settings.  OAuth Scopes: hiring:applications
- [Create Job Application Comment](https://documentation.bamboohr.com/reference/create-application-comment.md): Add a comment to an application. The authenticated caller must have access to ATS settings. The `type` field defaults to `comment` if omitted.  OAuth Scopes: hiring:applications.write
- [Get Applicant Statuses](https://documentation.bamboohr.com/reference/get-statuses.md): Get a list of applicant statuses configured for the company. The authenticated caller must have access to ATS settings. Returns both system-defined and custom statuses.  OAuth Scopes: hiring:applications
- [Update Applicant Status](https://documentation.bamboohr.com/reference/update-applicant-status.md): Update the status of an application. The authenticated caller must have access to ATS settings. Use the Get Applicant Statuses endpoint to obtain valid status IDs.  OAuth Scopes: hiring:applications.write
- [Get Company Locations](https://documentation.bamboohr.com/reference/get-company-locations.md): Get all company locations available for use when creating a job opening. The authenticated caller must have access to ATS settings. Use the returned location IDs as the `jobLocation` field when calling the Create Job Opening endpoint.  OAuth Scopes: hiring:applications
- [Get Hiring Leads](https://documentation.bamboohr.com/reference/get-hiring-leads.md): Get the list of employees who can be assigned as a hiring lead when creating a new job opening. The authenticated caller must have access to ATS settings. Use the returned `employeeId` values as the `hiringLead` field when calling the Create Job Opening endpoint.
- [Create Candidate](https://documentation.bamboohr.com/reference/create-candidate.md): Create a new candidate application for a job opening. The authenticated caller must have access to ATS settings. On success, returns the new candidate ID. Only fields required by the target job opening's standard questions need to be provided beyond firstName, lastName, and jobId.  OAuth Scopes: hiring:applications.write
- [Create Job Opening](https://documentation.bamboohr.com/reference/create-job-opening.md): Create a new job opening. The authenticated caller must have access to ATS settings. Use the Get Company Locations and Get Hiring Leads endpoints to obtain valid IDs for `jobLocation` and `hiringLead`. On success, returns the new job opening ID.
- [Benefits](https://documentation.bamboohr.com/reference/benefits.md)
- [List Company Benefits](https://documentation.bamboohr.com/reference/list-company-benefits.md): Returns all active (non-deleted) company benefit plans for the account. Each plan includes summary-level fields such as name, benefit category type, associated vendor and deduction IDs, effective date range, and catch-up eligibility flags. Deleted plans are excluded. To retrieve full detail for a specific plan (including SSO URL, description, and ACA fields), use "Get a company benefit".  OAuth Scopes: benefit
- [List Benefit Coverages](https://documentation.bamboohr.com/reference/list-benefit-coverages.md): Returns all benefit coverage levels configured in the company, such as Employee Only, Employee + Spouse, and Employee + Family. The JSON response wraps results under a "Benefit Coverages" key. Each coverage level includes an ID, short name, optional description, sort order, and an associated benefit plan ID (null for company-wide levels). Requires Benefits Administration permissions or owner/admin access.  OAuth Scopes: benefit
- [List Benefit Deduction Types](https://documentation.bamboohr.com/reference/list-benefit-deduction-types.md): Returns all benefit deduction types available in the system. Each deduction type describes a category of payroll deduction (e.g. 401(k), HSA, Section 125) along with its allowable benefit plan types, default deduction code, and optional sub-types. Some deduction types are grouped under a parent with sub-types (e.g. Pre-Tax groups Health, Dental, etc.); in that case the parent entry has a non-empty `subTypes` array. Requires Benefits Administration permissions.  OAuth Scopes: benefit
- [List Employee Benefits](https://documentation.bamboohr.com/reference/list-employee-benefits.md): Returns current and scheduled-future benefit enrollment records, grouped by employee. The response is a JSON object with a single `employeeBenefits` array where each entry contains the internal employee ID, the employee's current pay frequency (null when no pay schedule is set), and an `employeeBenefit` array of per-plan records that includes both the current enrollment record and any scheduled future-change records for that plan. Each record includes enrollment status, deduction date range, currency, occurrences-per-year, and the full employee/employer cost-sharing fields.  A JSON request body with a `filters` object is required, and the `filters` object must contain at least one of `employeeId`, `companyBenefitId`, or `enrollmentStatusEffectiveDate`. Any combination is accepted. Providing no `filters` object or an empty `filters` object returns a 400 validation error. Filtering by `companyBenefitId` or `enrollmentStatusEffectiveDate` returns enrollments for every accessible employee, so the response can contain many entries. Use **List Company Benefits** (`list-company-benefits`) to look up valid `companyBenefitId` values.  Future-enrollment records are silently omitted when the authenticated user lacks permission to view scheduled benefit changes. Current enrollment records continue to be returned. An empty `employeeBenefit` array on a known employee can mean either no enrollments or that the caller cannot view them.  Note: This endpoint accepts filters inside a JSON request body on a `GET` request, which is non-standard. Some HTTP clients, proxies, and gateways may strip request bodies from GET requests, which can produce confusing missing-filter behavior. Callers experiencing validation errors should verify that the request body is being preserved. A query-parameter-based endpoint will be released in the future.  OAuth Scopes: benefit
- [List Member Benefit Events](https://documentation.bamboohr.com/reference/list-member-benefit-events.md): Returns benefit enrollment events for all employees and their dependents over the past year, organized by member. Each entry identifies a member (employee or dependent) and lists their per-plan coverage events (eligibility granted, enrolled, or loss of coverage), sorted chronologically. Requires benefit settings access.  OAuth Scopes: benefit
- [List Employee Dependents](https://documentation.bamboohr.com/reference/list-employee-dependents.md): Returns employee dependents for the company. When `employeeid` is provided, only dependents for that employee are returned. When omitted, all dependents across all employees are returned. The response is a JSON object with a top-level key "Employee Dependents" containing an array of dependent objects. SSN and SIN are returned as masked values (e.g. "xxx-xx-1234"). State and country are returned as full names. Supports both JSON and XML response formats via the Accept header. Requires Benefits Administration permissions.  OAuth Scopes: employee:dependent, employee:dependent:ssn
- [Get Employee Dependent](https://documentation.bamboohr.com/reference/get-employee-dependent.md): Returns the details of a single employee dependent by their dependent ID. The response is a JSON object with a top-level key "Employee Dependents" containing a single-element array. SSN and SIN are returned as masked values (e.g. "xxx-xx-1234"). State and country are returned as full names. Supports both JSON and XML response formats via the Accept header. Requires Benefits Administration permissions.  OAuth Scopes: employee:dependent, employee:dependent:ssn
- [Create Employee Dependent](https://documentation.bamboohr.com/reference/create-employee-dependent.md): Creates a new dependent record for an employee. `employeeId` is required and must reference a valid employee. `relationship` must be a valid relationship type and `gender` must be a valid gender value. `isUsCitizen` and `isStudent` accept "yes" or "no". `state` accepts a state code (e.g. "UT") and `country` accepts an ISO 3166-1 alpha-2 country code (e.g. "US"). `dateOfBirth` must be in YYYY-MM-DD format. SSN and SIN are accepted as plain text and stored encrypted. Accepts both `application/json` and `application/xml` request bodies. The response format mirrors the request `Content-Type` (not the `Accept` header): JSON request bodies receive a JSON response; XML request bodies receive an XML response. A successful creation fires an internal dependent-created event that may trigger downstream benefit enrollment processing.  OAuth Scopes: employee:dependent.write, employee:dependent:ssn.write
- [Update Employee Dependent](https://documentation.bamboohr.com/reference/update-employee-dependent.md): Replaces all fields on an existing employee dependent record. The request body must contain the full desired state of the dependent — omitted fields are written as empty or null, not preserved. `employeeId` is required and must reference a valid employee. `relationship` must be a valid relationship type and `gender` must be a valid gender value. `isUsCitizen` and `isStudent` accept "yes" or "no". `state` accepts a state code (e.g. "UT") and `country` accepts an ISO 3166-1 alpha-2 country code (e.g. "US"). `dateOfBirth` must be in YYYY-MM-DD format. SSN and SIN are accepted as plain text and stored encrypted. Accepts both `application/json` and `application/xml` request bodies. The response format mirrors the request `Content-Type` (not the `Accept` header): JSON request bodies receive a JSON response; XML request bodies receive an XML response. A successful update fires an internal dependent-updated event that may trigger downstream benefit enrollment processing.  OAuth Scopes: employee:dependent.write, employee:dependent:ssn.write
- [List Member Benefits](https://documentation.bamboohr.com/reference/list-member-benefits.md): Returns a paginated list of benefit enrollment records for all members (employees and dependents) in the company for a given calendar year. Each record represents one member and includes the plans they held and the date ranges during which they held each enrollment status. Dependents appear alongside their subscribing employee via subscriberId. Use "List Company Benefits" to get valid planId values.  OAuth Scopes: benefit
- [Get Changed Employee IDs](https://documentation.bamboohr.com/reference/get-changed-employee-ids.md): Returns a list of employee IDs that have changed since the given timestamp. This allows for efficient syncing of employee data — rather than downloading all employees, only those that have changed are returned. A change in ANY individual field in the employee record, as well as any change to the employment status, job info, or compensation tables, will cause that employee to be returned. Each entry includes the employee ID, the type of change (Inserted, Updated, or Deleted), and the last-changed timestamp.  OAuth Scopes: public.integration, public.user
- [Get Changed Employee Table Data](https://documentation.bamboohr.com/reference/get-changed-employee-table-data.md): Returns table data for employees that have changed since the given timestamp. This is an optimization to avoid downloading all table data for all employees. It operates on an employee-last-changed-timestamp, which means that a change in ANY field in the employee record will cause ALL of that employee's table rows to show up via this API. The response includes the table rows grouped by employee ID with their last-changed timestamps.  OAuth Scopes: employee, employee:assets, employee:compensation, employee:custom_fields, employee:custom_fields_encrypted, employee:education, employee:emergency_contacts, employee:job, sensitive_employee:creditcards
- [Delete Company File](https://documentation.bamboohr.com/reference/delete-company-file.md): Permanently removes a company file and its associated storage. The company must have the Files tool enabled; otherwise the file is treated as not found. Read-only file types (e.g. e-signature templates) are silently skipped. No response body is returned on success. Use "Company Files > List Company Files" to obtain file IDs.  OAuth Scopes: company_file.write
- [Get Company File](https://documentation.bamboohr.com/reference/get-company-file.md): Downloads a company file by its ID. The response body is the raw file content. The `Content-Type` header reflects the file's MIME type and `Content-Disposition` is set to `attachment` with the original filename. Access is permitted if the file or its category is shared with employees, shared directly with the requesting user, or the user has view permission on the file section.  OAuth Scopes: company_file
- [Get Company Files and Categories](https://documentation.bamboohr.com/reference/list-company-files.md): Returns all company file categories and the files within each category that the requesting user is permitted to see. The response format is determined by the `Accept` request header: send `application/json` for JSON or omit it (or send `application/xml`) for XML.  OAuth Scopes: company_file
- [Update Company File](https://documentation.bamboohr.com/reference/update-company-file.md): Updates metadata for an existing company file. Supports renaming the file, moving it to a different category, and toggling employee visibility. Accepts JSON or XML. Only fields included in the request body are updated.  OAuth Scopes: company_file.write
- [Upload Company File](https://documentation.bamboohr.com/reference/upload-company-file.md): Uploads a file to a company file category. The request must be a `multipart/form-data` POST. On success, a `Location` header is returned with the URL of the newly created file resource. The file must be under 20MB and use a supported extension. Uploading to read-only categories is not permitted. Uploading to implementation categories is not permitted on companies that have completed implementation.  OAuth Scopes: company_file.write
- [Create Company File Category](https://documentation.bamboohr.com/reference/create-company-file-category.md): Creates one or more company file categories. Accepts a JSON array of category name strings or an equivalent XML document. An empty payload returns 200 without creating anything. Returns 400 if a name is empty or already exists, 403 if the caller lacks permission or the name is reserved, and 500 on an internal error.  OAuth Scopes: company_file.write
- [Get Company Profile Integrations](https://documentation.bamboohr.com/reference/get-company-profile-integrations.md): Returns the list of integration feature identifiers currently enabled for the company. Each identifier is an uppercase string key (e.g. `BAMBOOHR_PAYROLL`, `TIME_TRACKING`, `E_SIGNATURES`) representing a product feature or integration that has been activated on the account. The list reflects the company's current subscription and configuration.  OAuth Scopes: company:details
- [Update company information (phone, address, legal name)](https://documentation.bamboohr.com/reference/patch-company-profile-company-information.md): Updates legal name, phone, and/or address for the company (application/merge-patch+json). String fields must be JSON strings (not numbers). Response matches GET /api/v1/company-profile-data.  OAuth Scopes: company:details.write
- [Update company display name](https://documentation.bamboohr.com/reference/put-company-profile-display-name.md): Updates the company display name. Requires admin permissions and the company:details.write OAuth scope. The display name must be a non-empty string with a maximum length of 255 characters. Upon successful update, the system logs the change and broadcasts an event to notify other services.  OAuth Scopes: company:details.write
- [Get company equity settings](https://documentation.bamboohr.com/reference/db49fb29f9f04d59afad7c01ce860418.md): Retrieves company-level equity settings including calculation type, valuation, shares, pricing, and vesting-related configuration.  OAuth Scopes: equity
- [Update company equity settings](https://documentation.bamboohr.com/reference/c5880b509783cd9d7fce9ddf5d6af1be.md): Updates company-level equity settings including calculation type, valuation, shares, pricing, and vesting-related configuration.  OAuth Scopes: equity.write
- [List available compensation tools](https://documentation.bamboohr.com/reference/9f398e2652ea47a6dc5121ce5184222a.md): Returns the list of available compensation tools/settings for the company, including Levels & Bands, Compensation Benchmarking, Compensation Planning, and Total Rewards. Also returns upsell information if applicable.  OAuth Scopes: compensation_tools
- [List Compensation Benchmarks](https://documentation.bamboohr.com/reference/list-compensation-benchmarks.md): Returns every job/location pair the company tracks for compensation benchmarking. Each entry includes job and location identifiers, the benchmarks attached to that pair, the employees currently assigned to that job and location, and the company's configured internal pay band if one exists. Use the returned `jobDetails.id` and `locationDetails.id` values as the `jobId` and `locationId` inputs for `GET /api/v1/compensation/benchmarks/details`. Top-level `dismiss*Banner` fields reflect UI banner state and are not part of the benchmark data contract.  OAuth Scopes: compensation_benchmarks
- [Get Compensation Benchmark Details](https://documentation.bamboohr.com/reference/get-compensation-benchmark-details.md): Returns detailed benchmark data for a single company job title, optionally scoped to a specific location. The response includes the company pay range derived from current employees, the internal pay band configured for the job (if any), Mercer benchmark details when a Mercer benchmark is linked, every saved benchmark for the job/location (empty when none exist), and per-employee salary and compensation stats. Use `GET /api/v1/compensation/benchmarks` to find valid `jobId` and `locationId` values.  OAuth Scopes: compensation_benchmarks
- [Export Compensation Benchmark Details](https://documentation.bamboohr.com/reference/export-compensation-benchmark-details.md): Returns a CSV export of the compensation benchmark detail view for a single job, optionally scoped to a specific location. Rows include employee-level data (name, location, annualized pay, compa-ratio, range penetration, years of experience) alongside the company's internal pay band for the job. Use `GET /api/v1/compensation/benchmarks` to find valid `jobId` and `locationId` values. When `locationId` is omitted, the export aggregates across all locations for the job.  OAuth Scopes: compensation_benchmarks
- [Create Compensation Benchmark](https://documentation.bamboohr.com/reference/create-compensation-benchmark.md): Creates a new compensation benchmark for a specific company job title (and optionally a specific job location). The `jobTitleId` value comes from `GET /api/v1/compensation/benchmarks` (`jobDetails.id`) or the company's job-title list. When `jobLocationId` is omitted, the benchmark applies to the job title at any location. Returns the saved benchmark wrapped in `savedBenchmark` along with a status `message`.  OAuth Scopes: compensation_benchmarks.write
- [Import Compensation Benchmarks From CSV](https://documentation.bamboohr.com/reference/import-compensation-benchmarks.md): Parses a CSV of compensation benchmarks uploaded as multipart/form-data and returns the parsed rows together with a suggested column-to-field mapping. The response is a preview payload — callers must follow up with the publish step in the UI/API to persist benchmarks. Returns `400` when no `file` part is provided and `422` when the CSV is malformed.  OAuth Scopes: compensation_benchmarks.write
- [Update Compensation Benchmark](https://documentation.bamboohr.com/reference/update-compensation-benchmark.md): Updates an existing compensation benchmark identified by `id`. The `id` of an existing benchmark can be obtained from `GET /api/v1/compensation/benchmarks/details`. Request fields that are omitted or `null` are cleared on the stored benchmark; callers should send the full benchmark payload to preserve values. On success, returns the saved benchmark row wrapped in `savedBenchmark` together with a status `message`.  OAuth Scopes: compensation_benchmarks.write
- [Delete Compensation Benchmark](https://documentation.bamboohr.com/reference/delete-compensation-benchmark.md): Permanently removes the compensation benchmark identified by `id`. The `id` is a numeric benchmark row identifier; non-numeric values are rejected by the handler. Valid values are returned by `GET /api/v1/compensation/benchmarks/details` under `benchmarkValues[].id` and by the create/update endpoints as `savedBenchmark.id`.  OAuth Scopes: compensation_benchmarks.write
- [List Compensation Benchmark Sources](https://documentation.bamboohr.com/reference/list-compensation-benchmark-sources.md): Returns every enabled benchmark source configured for the company. Each source identifies where a benchmark value came from (for example, a specific survey provider) and includes a display color and the count of benchmarks currently attached to that source. Use the returned `id` as the `sourceId` input when creating or updating a benchmark.  OAuth Scopes: compensation_benchmarks
- [Create Compensation Benchmark Source](https://documentation.bamboohr.com/reference/create-compensation-benchmark-source.md): Creates a new benchmark source the company can attach to its benchmarks. The `name` must be non-empty; the reserved name `mercer` (case-insensitive) is rejected because Mercer sources are managed separately. Returns the new source's ID and the trimmed name.  OAuth Scopes: compensation_benchmarks.write
- [Update Compensation Benchmark Sources](https://documentation.bamboohr.com/reference/update-compensation-benchmark-sources.md): Updates the name and sort order of one or more existing benchmark sources in a single call. Every item in `benchmarkSources` must include a non-empty `id` and `name`; any item with the reserved name `mercer` (case-insensitive) is rejected because Mercer sources are managed separately. Use `GET /api/v1/compensation/benchmarks/sources` to obtain the current `id` values. Returns `{ "result": "success" }` when all updates are applied.  OAuth Scopes: compensation_benchmarks.write
- [Delete Compensation Benchmark Source](https://documentation.bamboohr.com/reference/delete-compensation-benchmark-source.md): Deletes a benchmark source together with all benchmarks currently attached to it. The source `id` is taken from the request body. Use `GET /api/v1/compensation/benchmarks/sources` to look up the `id` of the source to delete. Returns `{ "result": "success" }` when the source is removed.  OAuth Scopes: compensation_benchmarks.write
- [List compensation planning cycles](https://documentation.bamboohr.com/reference/b65f246186b41a9783a9397c11c703b4.md): List all compensation planning cycles for the company, including status and employee counts.  OAuth Scopes: planning_cycles
- [Get compensation planning cycle details](https://documentation.bamboohr.com/reference/5c2b55158b0950b1e9211655666645b6.md): Get compensation planning cycle details and currency settings for a cycle.  OAuth Scopes: planning_cycles
- [Get compensation planning cycle summary](https://documentation.bamboohr.com/reference/9bc279d788f6e86b4cd8b2e0d3de91b1.md): Get compensation planning cycle summary (progress, stats).  OAuth Scopes: planning_cycles
- [List employees in compensation planning cycle](https://documentation.bamboohr.com/reference/a6b8da1348a3151fe95adc03aaf64447.md): List employees in the compensation planning cycle (picker data: company roster and membership).  OAuth Scopes: planning_cycles
- [Get compensation planning cycle budgets](https://documentation.bamboohr.com/reference/7efceaee2c010f88244dd01ee81e6e7b.md): Get budget guidelines and breakdown for the compensation planning cycle.  OAuth Scopes: planning_cycles
- [Get compensation planning approval flows](https://documentation.bamboohr.com/reference/4e886b18264480611f380805301c49c4.md): Get approval flows for the compensation planning cycle (grouped by department by default).  OAuth Scopes: planning_cycles
- [List compensation planning cycle admins](https://documentation.bamboohr.com/reference/b3c51254de6918637a971fe4af382a53.md): List compensation planning cycle admins.  OAuth Scopes: planning_cycles
- [Get change communication letter details](https://documentation.bamboohr.com/reference/d6987e300672a00c7cfe59afebb64156.md): Get change communication letter details for the compensation planning cycle.  OAuth Scopes: planning_cycles
- [Get compensation planning cycle worksheet](https://documentation.bamboohr.com/reference/329acecaa6df729733d0752aa9f6b204.md): Get compensation planning worksheet details for the cycle (recommendations, approvals, or overview context). Omit `type` to use the default view for the current user.  OAuth Scopes: planning_cycles
- [Export compensation planning cycle worksheet to CSV](https://documentation.bamboohr.com/reference/593d5bff120edf2a218a92022a682728.md): Download compensation planning worksheet data as a UTF-8 CSV (Excel-friendly BOM). Same data scope as GET worksheet; omit `type` for the default view.  OAuth Scopes: planning_cycles
- [Create compensation planning cycle](https://documentation.bamboohr.com/reference/e2ac4e1535f296cb8901f209e04caa83.md): Create a new compensation planning cycle with default settings.  OAuth Scopes: planning_cycles.write
- [Update compensation planning cycle](https://documentation.bamboohr.com/reference/100b0cf8c5207b35697ff10370fd5fe1.md): Update compensation planning cycle details and currency settings.  OAuth Scopes: planning_cycles.write
- [Delete compensation planning cycle](https://documentation.bamboohr.com/reference/22ad75be25455279e2987c80851af5fc.md): Delete a compensation planning cycle.  OAuth Scopes: planning_cycles.write
- [Add employees to cycle](https://documentation.bamboohr.com/reference/3958585c861325ea7a2cd30a8c74f042.md): Add employees to a compensation planning cycle.  OAuth Scopes: planning_cycles.write
- [Remove employees from cycle](https://documentation.bamboohr.com/reference/89a5068111ec499135c7d6e9a53d5a30.md): Remove employees from a compensation planning cycle.  OAuth Scopes: planning_cycles.write
- [Launch compensation planning cycle](https://documentation.bamboohr.com/reference/3a19f07aa737dc826ba43b9a1c1cd257.md): Launch a compensation planning cycle. Validates all cycle data and sets status to Live.  OAuth Scopes: planning_cycles.write
- [Complete compensation planning cycle](https://documentation.bamboohr.com/reference/f4b431363af6573af46750f32632e88b.md): Complete a compensation planning cycle and finalize employee compensation records.  OAuth Scopes: planning_cycles.write
- [Save budget guidelines](https://documentation.bamboohr.com/reference/dacd313af2106213fc4696175941ce65.md): Save budget guidelines for a compensation planning cycle.  OAuth Scopes: planning_cycles.write
- [Save budget breakdown](https://documentation.bamboohr.com/reference/1d64402ee192568adbd5e3179a91e6e2.md): Save budget breakdown for a compensation planning cycle.  OAuth Scopes: planning_cycles.write
- [Import budget breakdown](https://documentation.bamboohr.com/reference/1d1fc0f164cb51973a0206b8e2fb2d2d.md): Import budget breakdown from structured data and apply to allocations.  OAuth Scopes: planning_cycles.write
- [Add cycle admins](https://documentation.bamboohr.com/reference/c7c32ed5278ac67e2e518bf7484a75dc.md): Add one or more cycle admins by internal employee IDs.  OAuth Scopes: planning_cycles.write
- [Update approval flow](https://documentation.bamboohr.com/reference/cf87b8e09a001b6fb81dfce6c20ab9e3.md): Update an approval flow for a compensation planning cycle. Allows modifying recommenders and approvers for a specific approval flow template.  OAuth Scopes: planning_cycles.write
- [Set final approver](https://documentation.bamboohr.com/reference/5c4aab35a34f5760ec044104b5232bf5.md): Set or update the final approver for all approval flows in a cycle.  OAuth Scopes: planning_cycles.write
- [Remove from approval flow](https://documentation.bamboohr.com/reference/b1e467e0eef72350eec61fcfeaf4e19d.md): Remove an employee from all approval chains for a specific cycle.  OAuth Scopes: planning_cycles.write
- [Save recommendations](https://documentation.bamboohr.com/reference/f3883a522dadbe9e11b34f8b656e3adb.md): Save compensation recommendations for an employee in a cycle.  OAuth Scopes: planning_cycles.write
- [Send recommendations to next stage](https://documentation.bamboohr.com/reference/a05b6d5f564f805d688ff2c1e37c3990.md): Send recommendations to the next approval stage for a specific approval flow template.  OAuth Scopes: planning_cycles.write
- [Remove cycle admin](https://documentation.bamboohr.com/reference/ef7619b0ee4c8dc079aaea870cfbe81b.md): Remove a cycle admin by internal employee ID. Full account admins cannot be removed.  OAuth Scopes: planning_cycles.write
- [Save change comm template](https://documentation.bamboohr.com/reference/c79f9c5950f983e59d2626faa30c00a1.md): Save the change communication email template for a compensation planning cycle.  OAuth Scopes: planning_cycles.write
- [List Reports](https://documentation.bamboohr.com/reference/list-reports.md): Returns a paginated list of saved custom reports available in the account. Each report entry contains an `id` (integer) and a `name` (string). Pass a report's `id` to "Get Report by ID" to execute it and retrieve its data.  Results default to page 1 with 500 records per page (maximum 1000). Out-of-range page numbers are clamped to the nearest valid page rather than returning an error. Invalid or zero values for `page` and `page_size` fall back to their defaults.  The `pagination` object includes `total_records`, `current_page`, `total_pages`, and nullable `next_page`/`prev_page` links. When there is no next or previous page the corresponding value is `null`.  OAuth Scopes: report
- [Get Report by ID](https://documentation.bamboohr.com/reference/get-report-by-id.md): Executes a saved custom report and returns its data using the report's configured fields and filters. The `data` array contains employee record objects whose keys are determined by the fields selected when the report was created — each object is a flat key-value map where keys are field names (e.g. `firstName`, `status`, `hireDate`) and values are strings or `null`. The `aggregations` array is empty unless the report's underlying dataset configuration includes aggregation rules. Use "List Reports" to discover available report IDs.  Response shape: Each element of `data` is a flat key-value object — field values are top-level keys (e.g. `row["firstName"]`). This differs from `get-data-from-dataset-v2`, where field values are nested under a `fields` key (e.g. `row["fields"]["firstName"]`).  There is no schema-only response from this endpoint.  The `pagination.total_records` value is the number of rows produced by the saved report after applying the report's configured filters, not necessarily the total number of employees in the account. Validate output before using in automated pipelines.  Results default to page 1 with 500 records per page (maximum 1000). Out-of-range page numbers are clamped to the nearest valid page. Invalid or zero values for `page` and `page_size` fall back to their defaults.  OAuth Scopes: report
- [List Datasets (v1)](https://documentation.bamboohr.com/reference/list-datasets-v1.md): Deprecated. Use "List Datasets (v1.2)" instead.  Returns the catalog of datasets available for querying via the Datasets API. Each entry includes a machine-readable `name` (used as the `datasetName` path parameter in "Get Fields from Dataset (v1.2)" and "Get Data from Dataset") and a human-readable `label`. Use this endpoint to discover which datasets the current account has access to before building queries.  The response includes `Deprecation` and `Link` headers pointing to the v1.2 successor endpoint.  OAuth Scopes: report
- [Get Fields from Dataset (v1)](https://documentation.bamboohr.com/reference/get-fields-from-dataset-v1.md): Deprecated. Use "Get Fields from Dataset (v1.2)" instead.  Returns a paginated list of field descriptors for the specified dataset. Each field includes its machine-readable `name`, human-readable `label`, `parentType`, `parentName`, and `entityName`. Use the returned field `name` values in the `fields` array when querying data via "Get Data from Dataset". Use "List Datasets (v1.2)" to discover valid dataset names.  Pagination defaults to page 1 with 500 fields per page (maximum 1000). Out-of-range page numbers are clamped to the nearest valid page. The `next_page` and `prev_page` links in the pagination object are absolute URLs.  Error responses (400, 403, 500) return plain-text bodies, not JSON.  OAuth Scopes: report
- [Get Field Options (v1)](https://documentation.bamboohr.com/reference/get-field-options-v1.md): Deprecated. Use "Get Field Options (v1.2)" instead.  Returns the allowed values for one or more fields in a dataset, for use as filter values when querying data via "Get Data from Dataset". Pass field names in the `fields` array of the request body; the response is an object keyed by field name, where each value is an array of `{id, value}` option objects. Optionally supply `filters` to narrow the returned options (e.g. only options that exist for active employees) and `dependentFields` when one field's options depend on another field's selected value.  Unrecognised field names may produce a `500` response with a plain-text body rather than structured JSON.  OAuth Scopes: field
- [Get Data from Dataset (v1)](https://documentation.bamboohr.com/reference/get-data-from-dataset-v1.md): Deprecated. Use "Get Data from Dataset (v2)" instead.  Retrieves records from the specified dataset using the fields, filters, sorting, grouping, and aggregations supplied in the request body. Provide field names in the `fields` array; use "Get Fields from Dataset (v1.2)" to discover available names. The response contains paginated rows under `data`, an `aggregations` array (empty when none requested), and a `pagination` block with page navigation links. Results default to page 1 with 500 records per page (maximum 1000).  Use "Get Field Options (v1.2)" to retrieve valid filter values. Filter fields do not need to appear in the `fields` list. Future hires have a status of `Inactive`; include it in your status filter to retrieve them. For `options`-type fields using `includes`/`does_not_include`, pass the filter value as an array enclosed in square brackets, for example `["Full-Time", "Part-Time"]`.  When any requested fields are historical table fields, pass their entity names in `showHistory`; entity names are returned by "Get Fields from Dataset (v1.2)". Grouping (`groupBy`) currently supports only one field; when active, `data` becomes an object keyed by group value instead of an array. Sort priority follows the order of objects in `sortBy`. Aggregations accept a `defaultAggregation` applied to every field and/or per-field `overridingAggregations`.  **Aggregations by field type:** text: count; date: count, min, max; int: count, min, max, sum, avg; bool: count; options: count; govIdText: count.  **Filter operators by field type:** text: contains, does_not_contain, equal, not_equal, empty, not_empty; date: lt, lte, gt, gte (each accepts a YYYY-MM-DD date string or a relative object `{"duration": "N", "unit": "days|weeks|months|years"}` where duration is a number as a string — lt/lte are measured backward from today, gt/gte forward), equal, not_equal, empty, not_empty, last, next (relative object `{"duration": "N", "unit": "days|weeks|months|years"}`), range (object `{"start": "YYYY-MM-DD", "end": "YYYY-MM-DD"}`); int: equal, not_equal, gte, gt, lte, lt, empty, not_empty; bool: checked, not_checked; options: includes, does_not_include, empty, not_empty; govIdText: empty, not_empty.  OAuth Scopes: report
- [List Datasets (v1.2)](https://documentation.bamboohr.com/reference/list-datasets-v1-2.md): Returns the catalog of datasets available for querying via the Datasets API. Each entry includes a machine-readable `name` (used as the `datasetName` path parameter in "Get Fields from Dataset (v1.2)" and "Get Data from Dataset (v2)") and a human-readable `label`. Use this endpoint to discover which datasets the current account has access to before building queries.  Datasets are queryable reporting datasets for the Datasets API. They are not the same as saved custom reports (`list-reports`), employee tabular table aliases (`list-tabular-fields`), or account list-field definitions (`list-list-fields`).  Note: Compared to "List Datasets (v1)", this version returns RFC 7807 `application/problem+json` error responses and includes an `X-Request-ID` correlation header.  OAuth Scopes: report
- [Get Fields from Dataset (v1.2)](https://documentation.bamboohr.com/reference/get-fields-from-dataset-v1-2.md): Returns a paginated list of field descriptors for the specified dataset. Each field includes its machine-readable `name`, human-readable `label`, parent section type and name, and `entityName`. Use the returned field `name` values in the `fields` array when querying data via "Get Data from Dataset (v2)". Use "List Datasets (v1.2)" to discover valid `datasetName` values. Pagination defaults to page 1 with 500 fields per page (maximum 1000). Out-of-range page numbers are clamped to the nearest valid page. Some datasets, especially `employee`, may return hundreds of fields. This endpoint does not support filtering by parent/entity/type; retrieve all pages and group client-side.  The `employee` dataset field names are fully qualified with their section prefix and differ from the field names used by `list-employees` and `get-employee`. Do not assume a field name from one endpoint works in the other.  For fields whose type is `list`, `multilist`, or another option-backed type, the field `id` can be matched to `fieldId` from `list-list-fields` to retrieve the account-level option list.  Note: Compared to "Get Fields from Dataset (v1)", this version returns RFC 7807 `application/problem+json` error responses and includes an `X-Request-ID` correlation header.  OAuth Scopes: report
- [Get Field Options (v1.2)](https://documentation.bamboohr.com/reference/get-field-options-v1-2.md): Returns the allowed values for one or more fields in a dataset, for use as filter values when querying data via "Get Data from Dataset (v2)". Pass field names in the `fields` array of the request body; the response is an object keyed by field name, where each value is an array of `{id, value}` option objects. Optionally supply `filters` to narrow the returned options (e.g. only options that exist for active employees) and `dependentFields` when one field's options depend on another field's selected value. Use "Get Fields from Dataset (v1.2)" to discover valid field names for a dataset.  Use this endpoint when you already have dataset field names from `get-fields-from-dataset-v1-2` and need valid filter/display options for those specific dataset fields. It is dataset-scoped: field names must be dataset field name values such as `jobInformationDepartment`, not account list aliases such as `department`.   Note: Compared to "Get Field Options (v1)", error responses (`400`, `403`) use RFC 7807 `application/problem+json` format. Unrecognised field names may produce a `500` response with a plain-text body rather than structured JSON.  OAuth Scopes: field
- [Get Data from Dataset (v2)](https://documentation.bamboohr.com/reference/get-data-from-dataset-v2.md): Queries the named dataset and returns the matching rows. The response is a JSON object with `data` (an array of row objects, each wrapping its values under a `fields` object whose keys match the requested field names), `links` (pagination navigation URLs; `prev` and/or `next`, omitted at boundaries), and `meta` (with `page`, `pageSize`, `totalPages`, `totalItems`).  Use this for tabular reporting, custom field selection across many employees, and OData-style filtering against the full dataset field catalog. For multiple employees, use List Employees (`list-employees`). For the full set of fields on a single employee, use Get Employee (`get-employee`).  Discover valid `datasetName` values via List Datasets (v1.2) (`list-datasets-v1-2`). Discover valid field names for a dataset via Get Fields from Dataset (v1.2) (`get-fields-from-dataset-v1-2`); the field set is dataset-specific.  Field-name vocabulary differs from the dedicated employee endpoints. The `employee` dataset uses fully qualified names such as `jobInformationJobTitle`, `jobInformationDepartment`, `jobInformationReportsTo`, and `employmentStatus`, where the employee endpoints use endpoint-specific shorter names — for example `jobTitleName` on List Employees (`list-employees`), and `jobTitle`, `department`, `supervisor`, and `workEmail` on Get Employee (`get-employee`). Identifier and contact fields also differ: the dataset's internal employee identifier is `eeid` (`get-employee` returns the same value as `id`, and `list-employees` as `employeeId`); the dataset's work-email field is `email` (`get-employee` uses `workEmail`). The dataset also exposes `employeeNumber` — the editable Employee # value, not the internal employee ID. Do not pass `employeeNumber` to employee ID inputs such as `filter[ids]` or `{id}` path parameters; it may fail with `404` or resolve to a different employee whose internal employee ID happens to match. Always source field names from Get Fields from Dataset (v1.2) (`get-fields-from-dataset-v1-2`) — names from the employee endpoints will not necessarily resolve here.  For routine `employee` dataset lookups, a useful starter field set is: `firstName`, `lastName`, `eeid` (internal employee ID), `employeeNumber` (Employee # / editable employee number), `email` (work email), `mobilePhone`, `hireDate`, `employmentStatus`, `jobInformationJobTitle`, `jobInformationDepartment`, `jobInformationLocation`, `jobInformationReportsTo` (supervisor's name), and `supervisorEid` (supervisor's `eeid`). The full catalog (over 450 fields) is discoverable via Get Fields from Dataset (v1.2) (`get-fields-from-dataset-v1-2`) — use it when you need anything beyond this starter set.  Filter expressions use OData-style syntax with comparison operators `eq`, `ne`, `lt`, `le`, `gt`, `ge`, the list-membership operator `in (...)`, and logical operators `and` / `or`. The parser does not support `not in`; use `ne` for the inverse of `eq`, and on options-type fields `ne` already applies set-membership negation under the hood. A single filter expression may use `and` or `or`, but not both; mixed logical expressions return `422` with code `INVALID_FILTER`. Operator support varies by field type: `eq` / `ne` work on text, numeric, date, and options-type (single-select enum) fields like `status`, `employmentStatus`, and `jobInformationDepartment`; ordering operators `lt`, `le`, `gt`, `ge` are supported on numeric and date fields. The list operator `in` is the natural fit on options-type fields (e.g. `status in ('Active','Inactive')`), and is also accepted on text, numeric, and date fields when used with a single value (e.g. `firstName in ('Ashley')`, equivalent to `firstName eq 'Ashley'`); multi-value `in` on non-options fields returns `422`. To check a field's type, see the `type` value returned by Get Fields from Dataset (v1.2). Filter fields do not need to appear in the `fields` array; rows are filtered server-side. String literals in filter expressions are wrapped in single quotes, e.g. `firstName eq 'Ashley'` or `status in ('Active','Inactive')`.  On date fields, the ordering operators also accept a relative-date duration literal in OData v4 / ISO 8601 form, e.g. `hireDate ge duration'P30D'`. The literal resolves against today at query time: with `lt` / `le` it resolves to today minus the duration, with `gt` / `ge` to today plus the duration (so `terminationDate lt duration'P6M'` matches dates before six months ago, and `hireDate ge duration'P30D'` matches dates from 30 days in the future onward). A negative duration reverses the direction — `hireDate ge duration'-P30D'` matches hire dates from 30 days ago onward (i.e. anyone hired in the last 30 days), including any future-dated hires. Exactly one date component is required — `P<n>Y` (years), `P<n>M` (months), `P<n>W` (weeks), or `P<n>D` (days). Combined components (`P1Y6M`), time components (`PT12H`), and duration literals with `eq` / `ne` / `in` return `422` with code `INVALID_FILTER`.  `orderBy` is a comma-separated list of `<field> <asc|desc>` rules. Every field used in `orderBy` must also appear in the `fields` array; omitting it returns a `400` with code `UE-1001`. `orderBy` is optional; with no `orderBy` the row order is unspecified.  Field-level access is enforced server-side based on the authenticated caller's permissions and OAuth scopes. When a caller lacks permission to read a requested field, the field is still returned in each row with an empty value, and its canonical name is listed in that row's `_restrictedFields` array (e.g., `_restrictedFields: ["employee_employeeNumber"]`) — the request is not rejected, and other requested fields still come back. This differs from Get Employee (`get-employee`), which silently omits unauthorized fields with no marker, leaving an absent field ambiguous between "not requested" and "not permitted". Callers without dataset-level access receive `403`, and a dataset the caller cannot see at all returns `404` ("not accessible" rather than disclosing existence).  Bad field names in `fields` or `filter` return `400` with `code: INVALID_ARGUMENT` and the offending name in the `detail` field (e.g., `"Invalid field name: employee_workEmail"`). The reported name carries the internal `<dataset>_` prefix; the actual misspelling is the unprefixed form. Confirm spelling against Get Fields from Dataset (v1.2) (`get-fields-from-dataset-v1-2`). Note: the field name appears in `detail` (singular); the `details` field (plural) remains empty in this error class. (Bad names in `orderBy` hit the must-be-in-`fields` check above first and return `UE-1001` rather than `INVALID_ARGUMENT`.)  Pagination: `page` defaults to `1` and `pageSize` defaults to `100` (maximum `1000`). `meta.totalItems` is the count of rows matching the query across all pages, `meta.totalPages` is `ceil(totalItems / pageSize)`, and `data` contains at most `pageSize` rows for the requested page. `links.next` is present when more pages exist; `links.prev` is present when not on the first page. Errors follow RFC 7807 (`application/problem+json`).  Note: Compared to Get Data from Dataset (v1) (`get-data-from-dataset-v1`), this version uses `filter` and `orderBy` request fields instead of the legacy `filters` and `sortBy` structures, moves pagination inputs to body fields (`page`, `pageSize`) instead of query parameters, returns pagination in `links` / `meta` objects instead of a legacy `pagination` object, and returns RFC 7807 compliant error responses with an `X-Request-ID` correlation header.  OAuth Scopes: report
- [Delete Employee File](https://documentation.bamboohr.com/reference/delete-employee-file.md): Permanently deletes an employee file. This action cannot be undone and removes the file from storage. The special employee ID of 0 resolves to the employee associated with the authenticated caller. Returns 200 even if the file was already deleted (idempotent). Returns 403 if the caller lacks permission or the file belongs to a BambooPayroll-managed section. Returns 404 if the file does not exist for the specified employee or the Files tool is not enabled for the company. Use 'List Employee Files' to obtain file IDs.  OAuth Scopes: employee:file.write
- [Get Employee File](https://documentation.bamboohr.com/reference/get-employee-file.md): Downloads the binary content of an employee file as an attachment. The response Content-Type header reflects the file's stored MIME type (e.g. application/pdf) and includes a Content-Disposition header with the original filename. The special employee ID of 0 resolves to the employee associated with the authenticated caller.  Use "List Employee Files" to discover file IDs and their categories for a given employee. Archived or soft-deleted files are excluded and return 404.  OAuth Scopes: employee:file
- [List Employee Files](https://documentation.bamboohr.com/reference/list-employee-files.md): Lists the file categories and files visible to the caller for the specified employee. This is a metadata listing (names, sizes, permissions); to download a file's content use `get-employee-file`. The response format is controlled by the Accept header: send `application/json` for JSON or omit/send anything else for XML. Only categories and files the caller is permitted to see are included; employees viewing their own profile also see files shared with them. Returns 404 when the employee has no accessible categories.  OAuth Scopes: employee:file
- [Update Employee File](https://documentation.bamboohr.com/reference/update-employee-file.md): Updates metadata for an existing employee file. Supports renaming the file, moving it to a different category, and toggling employee visibility. Accepts JSON or XML; only fields present in the request body are updated. An empty XML document no-ops successfully, while an empty JSON body returns 400. The `categoryId` field is silently ignored when the caller authenticated as the file creator but lacks full file permissions. Moving a file to a new category requires view/edit access to both the current and target category. Returns 403 if the file belongs to a read-only file section. Use 'List Employee Files' to obtain file IDs and category IDs.  OAuth Scopes: employee:file.write
- [Upload Employee File](https://documentation.bamboohr.com/reference/upload-employee-file.md): Uploads a file to an employee's file section. The request must be a `multipart/form-data` POST. On success, a `Location` header is returned with the URL of the newly created file resource. The file must be under 20MB and use a supported extension. Pass `0` as the employee ID to use the employee associated with the authenticated caller. Employees may upload to their own folder if the company has employee document uploads enabled.  OAuth Scopes: employee:file.write
- [Create Employee File Category](https://documentation.bamboohr.com/reference/create-employee-file-category.md): Creates one or more employee file categories (not company file categories). The request body is a JSON array of category name strings or an equivalent XML document with `<category>` elements. Each name must be non-empty and unique among existing employee file categories. An empty array returns 200 without creating anything. On success, returns 201 with no body. The admin user group is automatically granted edit permission on each new category.  OAuth Scopes: employee:file.write
- [Get Employee Table Data](https://documentation.bamboohr.com/reference/get-employee-table-data.md): Returns all rows for a given employee and table combination. The result is not sorted in any particular order. Each row contains the fields defined for that table, subject to field-level permission checks. Fields the caller does not have access to are omitted from the response.  OAuth Scopes: employee, employee:assets, employee:compensation, employee:custom_fields, employee:custom_fields_encrypted, employee:education, employee:emergency_contacts, employee:job, employee:job.write, sensitive_employee:creditcards
- [Create Table Row (v1.1)](https://documentation.bamboohr.com/reference/create-table-row-v1-1.md): Add a new row to the specified employee table using the v1.1 table-row creation endpoint. Submit the new row in JSON or XML. This version is largely compatible with v1 and supports the same tabular employee data use cases.  OAuth Scopes: employee.write, employee:assets.write, employee:compensation.write, employee:custom_fields.write, employee:custom_fields_encrypted.write, employee:education.write, employee:emergency_contacts.write, employee:job.write, sensitive_employee:creditcards.write
- [Update Table Row (v1.1)](https://documentation.bamboohr.com/reference/update-table-row-v1-1.md): Update an existing row in the specified employee table using the v1.1 table-row update endpoint. Submit the field changes in JSON or XML. This version is largely compatible with v1 and is intended for the same tabular employee data use cases.  OAuth Scopes: employee.write, employee:assets.write, employee:compensation.write, employee:custom_fields.write, employee:custom_fields_encrypted.write, employee:education.write, employee:emergency_contacts.write, employee:job.write, sensitive_employee:creditcards.write
- [Delete Employee Table Row](https://documentation.bamboohr.com/reference/delete-employee-table-row.md): Deletes a specific row from an employee's tabular data. The table name identifies which tabular dataset to target (e.g., jobInfo, compensation, customTabularField). Returns `success: true` if the row was deleted, or `success: false` with an error message if the row was not found or could not be deleted. Deletion will fail with a 409 if the row has pending approval changes, or a 412 if the row is tied to an active pay schedule. Per-table field schemas are available as named OpenAPI components (e.g., `JobInfoTableRowRequest`, `CompensationTableRowRequest`). See the components/schemas section of this spec for the full list.  OAuth Scopes: employee.write, employee:assets.write, employee:compensation.write, employee:custom_fields.write, employee:custom_fields_encrypted.write, employee:education.write, employee:emergency_contacts.write, employee:job.write, sensitive_employee:creditcards.write
- [Update Table Row (v1)](https://documentation.bamboohr.com/reference/update-table-row-v1.md): Deprecated. Use **Update Table Row (v1.1)** instead (`update-table-row-v1-1`). Update an existing row in the specified employee table by submitting field name/value pairs for the fields to change in JSON or XML.  OAuth Scopes: employee.write, employee:assets.write, employee:compensation.write, employee:custom_fields.write, employee:custom_fields_encrypted.write, employee:education.write, employee:emergency_contacts.write, employee:job.write, sensitive_employee:creditcards.write
- [Create Table Row (v1)](https://documentation.bamboohr.com/reference/create-table-row-v1.md): Deprecated. Use **Create Table Row (v1.1)** instead (`create-table-row-v1-1`). Add a new row to the specified employee table by submitting field name/value pairs in JSON or XML. Use this endpoint to append records to tabular employee data such as job information or compensation history.  OAuth Scopes: employee, employee.write, employee:assets.write, employee:compensation.write, employee:custom_fields.write, employee:custom_fields_encrypted.write, employee:education.write, employee:emergency_contacts.write, employee:job, employee:job.write, sensitive_employee:creditcards.write
- [List employee verification records for an employee](https://documentation.bamboohr.com/reference/list-employee-verifications-by-employee.md): Returns every employee verification row for the given employee (including archived), newest first. Intended for admin-level API consumers with the employee verifications OAuth scope; callers must have onboarding access and permission to view the employee (same rules as the active-verification employee verification API), except when the OAuth context is the employee themselves.  OAuth Scopes: employee_verifications
- [Get employee verification integration status](https://documentation.bamboohr.com/reference/get-employee-verification-integration.md): Returns the install state and partner metadata for the company's employee verification integration. Scoped to the authenticated OAuth company context. The `enabled` flag reflects whether the partner app is installed and usable; `integrationType` identifies the configured verification partner.  OAuth Scopes: employee_verifications
- [Enable or disable the employee verification integration](https://documentation.bamboohr.com/reference/update-employee-verification-integration.md): Enables or disables the company's employee verification integration. Enabling installs the configured partner app and schedules the daily sync; the company must have a valid US work location before enabling, otherwise a 400 is returned. Disabling tears down the partner app. The call is idempotent: a request to enable when already enabled (or disable when already disabled) returns 200 with the current state. Requires the employee_verifications.write OAuth scope, intended for admin-level API consumers.  OAuth Scopes: employee_verifications.write
- [Send employee verification lifecycle email by user and email type](https://documentation.bamboohr.com/reference/send-employee-verification-lifecycle-email-by-user.md): Accepts a Bamboo `userId` (path) and an `emailType` (body) and queues the corresponding employee verification lifecycle email—the same templates as the in-app auth listener (`signup_survey` after signup, `app_installed` after the integration app is installed). Delivered to the company owner contact with template context for that user id. Not an employee I-9 reminder. Requires the employee verification integration enabled, onboarding edit access, and `employee_verifications.write`.  OAuth Scopes: employee_verifications.write
- [Update an employee verification record](https://documentation.bamboohr.com/reference/update-employee-verification.md): Partial update of a single employee verification row. Any field omitted from the request body is left unchanged. Returns 404 when the verification id does not exist or does not belong to {employeeId}. Most verification updates flow in via partner webhooks; this endpoint exists for admin-level integrations that need to correct or annotate a record out-of-band, and requires onboarding view-and-edit permission on the employee.  OAuth Scopes: employee_verifications.write
- [Get Company Information](https://documentation.bamboohr.com/reference/get-company-information.md): Returns basic profile information for the company, including its legal name, display name, primary address, and contact phone number. For companies using BambooHR Payroll, the legal name and address are sourced from the active payroll client metadata; for all other companies, the data comes from the company's account settings.  OAuth Scopes: company:info
- [Get Employee](https://documentation.bamboohr.com/reference/get-employee.md): Returns a single employee record as a JSON object (or XML when `Accept: application/xml`). The `id` field is always present and is returned as a string; it is the internal employee ID — see the `id` and `employeeNumber` field documentation in the response schema for the distinction between the internal ID and the editable Employee # value. Every other field is included only when explicitly named in the `fields` query parameter. With no `fields` parameter, the response contains only `id` — there is no implicit default field set. Field names come from List Fields (`list-fields`), which also exposes custom-field aliases usable here. Note that the field-name vocabulary differs from the `employee` dataset (queried via Get Data from Dataset (v2) (`get-data-from-dataset-v2`)): this endpoint uses short names (`workEmail`, `jobTitle`, `department`, `supervisor`) where the dataset uses qualified names (`email`, `jobInformationJobTitle`, `jobInformationDepartment`, `jobInformationReportsTo`). By default only currently effective values from historical tables (job title, compensation, employment status, etc.) are returned; pass `onlyCurrent=false` to include future-dated values. Field-level permissions are applied silently: any requested field the authenticated caller cannot view is omitted from the response with no marker — an absent field may indicate either that it was not requested or that the caller lacks permission to view it. This differs from `get-data-from-dataset-v2` for the `employee` dataset, which always returns every requested field but represents inaccessible values as empty and lists the withheld field names in a per-record `_restrictedFields` array. The maximum number of fields per request is 400. Use this for fetching arbitrary fields on a single known employee. For multiple employees, use `list-employees`. For complex filtering or tabular reports, use `get-data-from-dataset-v2`.  OAuth Scopes: employee, employee:assets, employee:compensation, employee:contact, employee:custom_fields, employee:custom_fields_encrypted, employee:demographic, employee:dependent, employee:dependent:ssn, employee:education, employee:emergency_contacts, employee:identification, employee:job, employee:job.write, employee:management, employee:name, employee:photo, employee:vaccination, sensitive_employee:address, sensitive_employee:creditcards, sensitive_employee:protected_info
- [Get Employees Directory](https://documentation.bamboohr.com/reference/get-employees-directory.md): Returns the company's published employee directory: a fieldset definition plus an array of employee records whose keys match the field ids. Coverage is intentionally incomplete — companies can hide individual employees (commonly contractors) from the directory, and those employees are silently absent from the response with no indicator that they exist. The fieldset is also fixed by company directory configuration; callers cannot request additional fields. Use this endpoint only when you specifically want the company's curated directory subset (for example, an org-style listing that respects the company's directory settings). For complete or general-purpose employee listings, batch lookups by ID, or filtering by name/status, use **List Employees** (`list-employees`) instead. For tabular reporting, custom field selection, or analytical queries across many employees, use **Get Data from Dataset (v2)** (`get-data-from-dataset-v2`) instead. Response format follows the `Accept` header: `application/json` returns a JSON object with `fields` and `employees` arrays; `application/xml` (the default when `Accept` is missing or any non-JSON value) returns a `<directory>` document with `<fieldset>` and `<employees>` children. Employee `id` values are internal employee IDs returned as strings in both formats. The response shape varies by caller permission and per-company configuration: when neither company-wide directory sharing nor org-chart sharing is enabled the endpoint returns 403; when only org-chart sharing is enabled the response uses a reduced fieldset (limited to the fields exposed by the org chart); when the resulting directory has no employees the endpoint returns 404 rather than an empty list.  OAuth Scopes: employee_directory
- [Update Employee](https://documentation.bamboohr.com/reference/update-employee.md): Update an employee's fields by submitting a JSON object or XML document containing field name/value pairs. The request body schema lists commonly used fields, but any valid writable employee field name may be used as a key. To discover available field names, call the List Fields endpoint (operationId: list-fields, GET /api/v1/meta/fields).  This endpoint does not upload, replace, or remove the employee profile photo, and does not accept any binary or file uploads in general. Photo-related keys (e.g. `photo`, `photoUrl`) included in the body are silently ignored: the request still returns 200, but no photo change is made. To change a profile photo, use the Upload Employee Photo endpoint (`upload-employee-photo`). AI connectors cannot use that endpoint reliably and should redirect the user to the BambooHR web UI.  Trax Payroll note: If the employee is currently on a pay schedule syncing with Trax Payroll, or is being added to one, the request must include the required payroll-related employee fields: employeeNumber (unless the company has automatic employee numbers enabled), firstName, lastName, dateOfBirth, ssn or ein, gender, maritalStatus, hireDate, address1, city, state, zipcode, country, employmentHistoryStatus, exempt, payType, payRate, payPer, overtimeRate, and location.  OAuth Scopes: employee, employee.write, employee:assets.write, employee:compensation.write, employee:contact.write, employee:custom_fields.write, employee:custom_fields_encrypted.write, employee:demographic.write, employee:dependent.write, employee:dependent:ssn.write, employee:education.write, employee:emergency_contacts.write, employee:identification.write, employee:job, employee:job.write, employee:management.write, employee:name.write, employee:payroll.write, employee:photo.write, employee:vaccination.write, sensitive_employee:address.write, sensitive_employee:creditcards.write, sensitive_employee:protected_info.write
- [List Employees](https://documentation.bamboohr.com/reference/list-employees.md): Lists all employees in the authenticated caller's company as a cursor-paginated employee directory. Use this to list employees, browse the company directory, fetch the employee roster, or batch-lookup multiple employees by ID. The response is a JSON object with `data` (an array of employee records), `meta.total` (count of all employees matching the filter, not just the current page), `meta.page` (cursor pagination state), and `_links` (`self`, plus `next` / `prev` when more pages exist). Each employee record always includes the default identity and job fields, plus any additional fields requested via `fields`. `employeeId` is returned as a string and is the internal employee ID — see the `employeeId` and `employeeNumber` field documentation in the response schema for the distinction between the internal ID and the editable Employee # value. Field values the caller cannot read are returned as `null`, and the names of those suppressed fields are listed on the record in `_restrictedFields`; if the caller cannot read a field used in `filter` or `sort`, the affected employee is dropped from the result set entirely to avoid leaking presence. IDs for `filter[ids]` come from prior responses of this endpoint. For a single employee with the full set of fields, use `get-employee`. For complex filtering, arbitrary sorting, or tabular reports across many fields, use Get Data from Dataset (v2) (`get-data-from-dataset-v2`). Each record includes a `photoUrl` field with a time-limited signed URL. This is the recommended way for AI connectors to display or link to an employee photo, since fetching raw photo bytes through `get-employee-photo` produces base64 payloads too large for an AI model to consume reliably.  OAuth Scopes: employee, employee:job, employee:name, employee_directory, sensitive_employee:protected_info
- [Create Employee](https://documentation.bamboohr.com/reference/create-employee.md): Create a new employee. At minimum, provide a first name and last name in a JSON object or XML document. The request body schema lists commonly used fields, but any valid writable employee field name may be included as a key. To discover available field names, call the List Fields endpoint (operationId: list-fields, GET /api/v1/meta/fields).  This endpoint does not upload, set, or remove the employee profile photo. Photo-related keys (e.g. `photo`, `photoUrl`) included in the body are silently ignored: the request still creates the employee and returns 201, but no photo is attached. After creation, use the Upload Employee Photo endpoint (`upload-employee-photo`) to attach a profile photo. AI connectors cannot use that endpoint reliably and should redirect the user to the BambooHR web UI.  Trax Payroll note: Employees added to a pay schedule synced with Trax Payroll must include the required payroll-related employee fields: employeeNumber (unless the company has automatic employee numbers enabled), firstName, lastName, dateOfBirth, ssn or ein, gender, maritalStatus, hireDate, address1, city, state, zipcode, country, employmentHistoryStatus, exempt, payType, payRate, payPer, overtimeRate, and location.  OAuth Scopes: employee, employee.write, employee:assets.write, employee:compensation.write, employee:contact.write, employee:custom_fields.write, employee:custom_fields_encrypted.write, employee:demographic.write, employee:dependent.write, employee:dependent:ssn.write, employee:education.write, employee:emergency_contacts.write, employee:identification.write, employee:job, employee:job.write, employee:management.write, employee:name.write, employee:payroll.write, employee:photo.write, employee:vaccination.write, sensitive_employee:address.write, sensitive_employee:creditcards.write, sensitive_employee:protected_info.write
- [Delete employee](https://documentation.bamboohr.com/reference/delete-employee.md): Permanently deletes an employee record and all associated data.  OAuth Scopes: employee.write
- [Delete Goal](https://documentation.bamboohr.com/reference/delete-goal.md): Permanently deletes a goal for an employee. The goal must belong to the specified employee. Returns 204 with no response body on success. For natural-language requests that identify a goal by title or partial title, first call `list-goals` with `filter=status-all` and resolve exactly one matching goal. Do not delete if there are multiple matches or no match; ask for clarification or report that the goal was not found.  OAuth Scopes: goal.write
- [Delete Goal Comment](https://documentation.bamboohr.com/reference/delete-goal-comment.md): Deletes a goal comment. The comment must belong to the specified goal, and the goal must belong to the specified employee. Returns 204 with no response body on success. If the user does not provide a comment ID, first call `list-goal-comments` and select a single deletable comment (`canDelete` is true) matching the user's description. If multiple comments match or none are deletable, do not delete; ask for clarification.  OAuth Scopes: goal.write
- [Get Goal Aggregate](https://documentation.bamboohr.com/reference/get-goal-aggregate.md): Returns a single goal with its comments, alignment options, and a list of all persons who are either shared on the goal or have commented on it. Useful for rendering a full goal detail view in a single request.  OAuth Scopes: goal
- [Get Goals Aggregate (v1)](https://documentation.bamboohr.com/reference/get-goals-aggregate-v1.md): Deprecated. Use "Get Goals Aggregate (v1.1)" instead. Provides a list of all goals, type counts, goal comment counts, and employees shared with goals for the given employee. This version of the endpoint will not return any goals with milestones. Milestone functionality for this endpoint begins in version 1.2.  OAuth Scopes: goal
- [Get Goals Aggregate (v1.1)](https://documentation.bamboohr.com/reference/get-goals-aggregate-v11.md): Deprecated. Use "Get Goals Aggregate (v1.2)" instead. Provides a list of all goals, type counts, filter actions, goal comment counts, and employees shared with goals for the given employee. Note: Compared to "Get Goals Aggregate (v1)", this version returns goals in the closed filter and provides filter actions for each filter. This version of the endpoint will not return any goals with milestones. Milestone functionality for this endpoint begins in version 1.2.  OAuth Scopes: goal
- [Get Goals Aggregate (v1.2)](https://documentation.bamboohr.com/reference/get-goals-aggregate-v12.md): Provides a goals dashboard for an employee: goals matching the selected filter, status filter counts/actions, comment counts, and people shared with or commenting on those goals. This v1.2 endpoint includes milestone-based goals in the returned goal list. Use the optional `filter` query parameter to control which statuses are included; use `status-all` when the user asks for a complete dashboard across active, completed, and closed goals. Note: Compared to "Get Goals Aggregate (v1.1)", this version returns goals that contain milestones.  OAuth Scopes: goal
- [Get Goal Filters (v1.2)](https://documentation.bamboohr.com/reference/get-goals-filters-v12.md): Get the number of goals per status for an employee, including goals with milestones. Note: Compared to "Get Goal Filters (v1.1)", this version returns goals with milestones.  OAuth Scopes: goal
- [Get Goal Filters (v1)](https://documentation.bamboohr.com/reference/get-goals-filters-v1.md): Deprecated. Use "Get Goal Filters (v1.1)" instead. Get the number of goals per status for an employee. Returns a count of goals in each status (In Progress, Completed) for the specified employee. Goals with milestones are excluded from counts in this version.  OAuth Scopes: goal
- [Get Goal Filters (v1.1)](https://documentation.bamboohr.com/reference/get-goals-filters-v11.md): Deprecated. Use "Get Goal Filters (v1.2)" instead. Get the number of goals per status for an employee. Note: Compared to "Get Goal Filters (v1)", this version includes actions.  OAuth Scopes: goal
- [List Goals](https://documentation.bamboohr.com/reference/list-goals.md): Returns goals for an employee. Use this endpoint to locate goals by title before updating, commenting on, closing, reopening, or deleting them. Use `filter=status-inProgress` when the user asks for current/active goals, `filter=status-completed` for completed goals, `filter=status-closed` for closed goals, and `filter=status-all` when the user says "all goals", "including closed", or you are resolving a goal by title for a write operation where the status is unknown. If no filter is provided, closed goals are excluded. Results are capped at 50 goals; if a title lookup is ambiguous or absent, do not update or delete a different goal.  OAuth Scopes: goal
- [Create Goal](https://documentation.bamboohr.com/reference/create-goal.md): Create a new goal for an employee. To create a simple goal without milestones, omit the `milestones` field; the goal's progress can then be changed with `update-goal-progress`. To create a milestone-based goal, provide `milestones` as a non-empty array of `{ "title": string }` objects; the goal's percent complete is then derived from milestone completion and should be changed via `update-goal-milestone-progress`. Sending `milestones: null` is treated as omitted (creates a simple goal).  OAuth Scopes: goal.write
- [Update Goal (v1)](https://documentation.bamboohr.com/reference/update-goal-v1.md): Deprecated. Use "Update Goal (v1.1)" instead. Update a goal. This version will not update a goal to contain milestones, that functionality is added in version 1.1.  OAuth Scopes: goal.write
- [Update Goal Progress](https://documentation.bamboohr.com/reference/update-goal-progress.md): Update the progress percentage of a simple, non-milestone goal. Do not use this endpoint for goals that contain milestones; BambooHR derives percent complete for milestone-based goals from milestone completion and will reject manual percent updates with a 400 response (`UPDATE_GOAL_WITH_MILESTONE_PROGRESS_ERROR`). For milestone-based goals, use `update-goal-milestone-progress` to mark individual milestones complete or incomplete.  OAuth Scopes: goal.write
- [Update Milestone Progress](https://documentation.bamboohr.com/reference/update-goal-milestone-progress.md): Update the progress of a milestone in a goal. Validate the result using returned domain fields such as the milestone's `completedDateTime`, plus the goal's `status` and `percentComplete`; do not rely solely on `lastChangedDateTime` as the confirmation timestamp, because it may not match the HTTP response time or may reflect BambooHR's internal timezone/update semantics.  OAuth Scopes: goal.write
- [Update Goal Sharing](https://documentation.bamboohr.com/reference/update-goal-sharing.md): Replaces the full list of employees this goal is shared with. The provided `sharedWithEmployeeIds` array must include the goal owner's internal employee ID. Returns the updated goal object.  OAuth Scopes: goal.write
- [Get Goal Creation Permission](https://documentation.bamboohr.com/reference/get-goal-creation-permission.md): Determine if the authenticated caller has permission to create a goal for this employee.  OAuth Scopes: goal
- [List Goal Sharing Options](https://documentation.bamboohr.com/reference/list-goal-share-options.md): Provides a list of employees with whom the specified employee\'s goals may be shared.  OAuth Scopes: goal
- [List Goal Comments](https://documentation.bamboohr.com/reference/list-goal-comments.md): Returns comments for a goal, including each comment's ID, author, text, creation time, and edit/delete permissions. Use this endpoint before updating or deleting a comment when the user identifies a comment by text or says "my comment" rather than providing a comment ID.  OAuth Scopes: goal
- [Create Goal Comment](https://documentation.bamboohr.com/reference/create-goal-comment.md): Creates a new comment on a goal. The goal must belong to the specified employee. Returns the newly created comment object including its assigned ID.  OAuth Scopes: goal.write
- [Update Goal Comment](https://documentation.bamboohr.com/reference/update-goal-comment.md): Updates the text of an existing goal comment. The comment must belong to the specified goal, and the goal must belong to the specified employee. Returns the updated comment object. If the user does not provide a comment ID, first call `list-goal-comments` and select a single editable comment (`canEdit` is true) matching the user's description. If multiple comments match or none are editable, do not update; ask for clarification.  OAuth Scopes: goal.write
- [Get Alignable Goal Options](https://documentation.bamboohr.com/reference/get-alignable-goal-options.md): Returns goals that can be used as alignment targets. When a `goalId` query parameter is provided, the currently aligned goal is included in the results even if it would otherwise be excluded. When `goalId` is omitted, returns alignment options for the authenticated caller. This endpoint is permission-sensitive: the caller may be able to view a goal through `list-goals` or `get-goal-aggregate` but still receive 403 here if they lack permission to view alignment options for the selected goal. Treat 403 as "alignment options are permission-restricted," not as proof that the goal ID is invalid.  OAuth Scopes: goal
- [Close Goal](https://documentation.bamboohr.com/reference/close-goal.md): Closes a goal, moving it to the closed status. An optional comment may be included in the request body to record a note at closing time. Returns the updated goal object. Validate the result using the returned `status`, `percentComplete`, and `completionDate` fields; do not rely solely on `lastChangedDateTime` as the confirmation timestamp, because it may not match the HTTP response time or may reflect BambooHR's internal timezone/update semantics. Note: Cascading goals with visible children cannot be closed.  OAuth Scopes: goal.write
- [Reopen Goal](https://documentation.bamboohr.com/reference/reopen-goal.md): Reopens a closed goal, returning it to the in-progress status. Returns the updated goal object. Validate the result using the returned `status` and `percentComplete` fields; do not rely solely on `lastChangedDateTime` as the confirmation timestamp, because it may not match the HTTP response time or may reflect BambooHR's internal timezone/update semantics.  OAuth Scopes: goal.write
- [Update Goal (v1.1)](https://documentation.bamboohr.com/reference/update-goal-v11.md): Update a goal's top-level fields and optionally add or delete milestones. Milestone handling is not a full replace or upsert: objects passed in `milestones` are always added as new milestones, even if their titles match existing milestones. To keep existing milestones unchanged while editing title, description, due date, sharing, or alignment, omit the `milestones` field. To remove milestones, pass their IDs in `deletedMilestoneIds`. There is no field for editing an existing milestone title in place. Note: Compared to "Update Goal (v1)", this version adds milestone updates.  OAuth Scopes: goal.write
- [Hours](https://documentation.bamboohr.com/reference/hours.md)
- [Get Time Tracking Record](https://documentation.bamboohr.com/reference/get-time-tracking-record.md): Retrieves a single time tracking hour record by its ID. Returns the full record details including hours, date, employee, project, task, and shift differential information. The `project` and `shiftDifferential` fields are null when not applicable. For historical compatibility, missing records may surface as an empty/null payload rather than a strict not-found response.  OAuth Scopes: time_tracking
- [Create Hour Record](https://documentation.bamboohr.com/reference/create-time-tracking-hour-record.md): Adds a single hour record. Use this endpoint when creating one record at a time. For bulk imports, use create-or-update-time-tracking-hour-records.  OAuth Scopes: time_tracking.write
- [Create or Update Hour Records](https://documentation.bamboohr.com/reference/create-or-update-time-tracking-hour-records.md): Bulk add/edit hour records. The endpoint can return HTTP 201 even when individual items fail validation; inspect each item's `success` flag and per-item `response.message` for partial failures.  OAuth Scopes: time_tracking.write
- [Update Hour Record](https://documentation.bamboohr.com/reference/update-time-tracking-record.md): Edits an existing hour record by `timeTrackingId`.  OAuth Scopes: time_tracking.write
- [Delete Hour Record](https://documentation.bamboohr.com/reference/delete-time-tracking-hour-record.md): Deletes an hour record by `timeTrackingId` (`id` path parameter). This removes all stored revisions associated with that logical time tracking record. Not-found and invalid-id cases are currently returned as a 400 invalid-argument response for backward compatibility.  OAuth Scopes: time_tracking.write
- [List job locations](https://documentation.bamboohr.com/reference/get-locations.md): Retrieves a paginated list of job locations. Returns active locations by default. Supports pagination via page and pageSize query parameters.  OAuth Scopes: field
- [Create a job location](https://documentation.bamboohr.com/reference/create-location.md): Creates a new job location. Requires a label and address. If remoteLocation is true, address fields are optional.  OAuth Scopes: field.write
- [Get a job location](https://documentation.bamboohr.com/reference/get-location.md): Retrieves a single job location by its ID. Returns the full location resource including address details.  OAuth Scopes: field
- [Update a job location](https://documentation.bamboohr.com/reference/update-location.md): Updates an existing job location.  OAuth Scopes: field.write
- [Delete a job location](https://documentation.bamboohr.com/reference/delete-location.md): Deletes a job location by its ID. Returns 204 No Content on success.  OAuth Scopes: field.write
- [Login](https://documentation.bamboohr.com/reference/login.md)
- [Login](https://documentation.bamboohr.com/reference/user-login.md): Exchanges username, password, and application key for a persistent API key scoped to that user and application. No pre-existing authentication is required; credentials are passed in the request body. On success, returns a persistent API key, the authenticated user ID, the linked employee ID (null when no employee record is associated), and the base API URL to use for subsequent requests.  This endpoint is deprecated. New integrations should prefer OAuth or OpenID Connect instead.  `applicationKey` must correspond to a registered non-mobile application; iOS and Android app keys are explicitly rejected with a 403 (no body). The optional `deviceId` associates the generated key with a specific device.  Response format is determined by the `Accept` request header. Send `Accept: application/json` to receive JSON; omit the header or send any other value to receive XML. Alternatively, set `?format=json` in the query string to force JSON regardless of the `Accept` header.  Note: If the company has SSO enabled and password login is disabled, this endpoint returns HTTP 200 with a plain-text error message rather than a structured error response.
- [Time Tracking](https://documentation.bamboohr.com/reference/time-tracking.md)
- [List Timesheet Entries](https://documentation.bamboohr.com/reference/list-timesheet-entries.md): Returns timesheet entries for all employees, or a filtered subset, within the specified date range. Results include both clock and hour entry types. Dates must fall within the last 365 days and are interpreted in the company timezone.  OAuth Scopes: time_tracking
- [Create or Update Timesheet Clock Entries](https://documentation.bamboohr.com/reference/create-or-update-timesheet-clock-entries.md): Creates or updates timesheet clock entries in bulk. Entries with an existing ID are updated; entries without an ID are created.  OAuth Scopes: time_tracking.write
- [Create or Update Timesheet Hour Entries](https://documentation.bamboohr.com/reference/create-or-update-timesheet-hour-entries.md): Creates or updates timesheet hour entries in bulk. Entries with an existing ID are updated; entries without an ID are created.  OAuth Scopes: time_tracking.write
- [Create Timesheet Clock-In Entry](https://documentation.bamboohr.com/reference/create-timesheet-clock-in-entry.md): Clocks in an employee at the current server time. To record a historical clock-in, provide a `date`, `start` (HH:MM, 24-hour format), and `timezone`. You can optionally associate the entry with `projectId`, `taskId` (requires `projectId`), `breakId`, and a `note`.  OAuth Scopes: time_tracking.write
- [Create Timesheet Clock-Out Entry](https://documentation.bamboohr.com/reference/create-timesheet-clock-out-entry.md): Clocks out a currently clocked-in employee at the current server time. To record a historical clock-out, provide a `date`, `end` (HH:MM, 24-hour format), and `timezone`.  OAuth Scopes: time_tracking.write
- [Delete Timesheet Clock Entries](https://documentation.bamboohr.com/reference/delete-timesheet-clock-entries-via-post.md): Deletes one or more timesheet clock entries by their IDs. Delete operations are idempotent; deleting already-removed entries does not require client retries.  OAuth Scopes: time_tracking.write
- [Delete Timesheet Hour Entries](https://documentation.bamboohr.com/reference/delete-timesheet-hour-entries-via-post.md): Deletes one or more timesheet hour entries by their IDs. Delete operations are idempotent; deleting already-removed entries does not require client retries.  OAuth Scopes: time_tracking.write
- [Create Time Tracking Project](https://documentation.bamboohr.com/reference/create-time-tracking-project.md): Creates a new time tracking project. Returns the created project with its ID and tasks. When `allowAllEmployees` is false, the response also includes the `employeeIds` array of employees who have access.  By default, all employees can log time to the project (`allowAllEmployees` defaults to true) and the project is billable (`billable` defaults to true). Set `hasTasks` to true to enable task-level tracking and provide a `tasks` array — at least one task is required when `hasTasks` is true. Project and task names must be unique and may not exceed 50 characters. When `allowAllEmployees` is false, provide `employeeIds` to restrict access to specific employees.  OAuth Scopes: time_tracking.write
- [Meal & Rest Breaks](https://documentation.bamboohr.com/reference/meal-rest-breaks.md)
- [List Break Policies](https://documentation.bamboohr.com/reference/list-break-policies.md): Returns a paginated list of all break policies. Supports OData v4 filtering. Use includeCounts to include employee and break counts per policy.  OAuth Scopes: time_tracking:breaks
- [Get Break Policy](https://documentation.bamboohr.com/reference/get-break-policy.md): Retrieves a single break policy by its UUID. When includeCounts is enabled, the response includes the number of associated employees and breaks.  OAuth Scopes: time_tracking:breaks
- [Create Break Policy](https://documentation.bamboohr.com/reference/create-break-policy.md): Create a break policy. Breaks and assignments can be optionally included and created at the same time.  OAuth Scopes: time_tracking:breaks.write
- [Update Break Policy](https://documentation.bamboohr.com/reference/update-break-policy.md): Partially updates a break policy identified by its UUID. Only fields provided in the request body are updated. Returns the updated break policy on success.  OAuth Scopes: time_tracking:breaks.write
- [Replace Breaks for Break Policy](https://documentation.bamboohr.com/reference/replace-breaks-for-break-policy.md): Replace all breaks for a break policy. Breaks with an ID will be updated, breaks without an ID will be created. Existing breaks not in the request will be soft-deleted.  OAuth Scopes: time_tracking:breaks.write
- [Sync Break Policy](https://documentation.bamboohr.com/reference/sync-break-policy.md): Performs a full replacement of a break policy and its related data (breaks and employee assignments). Unlike the partial update endpoint, this replaces the entire policy state with the provided payload, removing any breaks or assignments not included in the request.  OAuth Scopes: time_tracking:breaks.write
- [Delete Break Policy](https://documentation.bamboohr.com/reference/delete-break-policy.md): Deletes a break policy by its UUID. Associated breaks and employee assignments are also removed.  OAuth Scopes: time_tracking:breaks.write
- [List Breaks for Break Policy](https://documentation.bamboohr.com/reference/list-break-policy-breaks.md): Returns a paginated list of breaks belonging to the specified break policy. Supports OData v4 filtering.  OAuth Scopes: time_tracking:breaks
- [Get Break](https://documentation.bamboohr.com/reference/get-break.md): Retrieves a single time tracking break by its UUID. Returns the full break details including name, duration, paid status, and availability configuration.  OAuth Scopes: time_tracking:breaks
- [Create Break](https://documentation.bamboohr.com/reference/create-break.md): Creates a new break and associates it with the specified break policy.  OAuth Scopes: time_tracking:breaks.write
- [Update Break](https://documentation.bamboohr.com/reference/update-break.md): Partially updates a time tracking break identified by its UUID. Only fields provided in the request body are updated. Returns the updated break on success.  OAuth Scopes: time_tracking:breaks.write
- [Delete Break](https://documentation.bamboohr.com/reference/delete-break.md): Deletes a time tracking break by its UUID. The break is soft-deleted and removed from any break policies it was associated with.  OAuth Scopes: time_tracking:breaks.write
- [List Break Policy Employees](https://documentation.bamboohr.com/reference/list-break-policy-employees.md): Retrieves employees assigned to a specific break policy. If a policy has no assignments, returns HTTP 200 with an empty `data` array.  OAuth Scopes: time_tracking:breaks
- [List Employee Break Policies](https://documentation.bamboohr.com/reference/list-employee-break-policies.md): Retrieves break policies assigned to a specific employee. Requires permission to view the target employee.  OAuth Scopes: time_tracking:breaks
- [Set Employees for Break Policy](https://documentation.bamboohr.com/reference/set-break-policy-employees.md): Sets the employee assignments for a break policy. This replaces all existing assignments with the provided list.  OAuth Scopes: time_tracking:breaks.write
- [Assign Employees to Break Policy](https://documentation.bamboohr.com/reference/assign-employees-to-break-policy.md): Assigns employees to a break policy. Adds the specified employees to the policy without removing existing assignments.  OAuth Scopes: time_tracking:breaks.write
- [Unassign Employees from Break Policy](https://documentation.bamboohr.com/reference/unassign-employees-from-break-policy.md): Unassigns the specified employees from a break policy. Removes employee assignments from the policy without affecting the policy itself or other assigned employees. Employees can only be unassigned from policies that are not assigned to all employees.  OAuth Scopes: time_tracking:breaks.write
- [List Employee Break Availabilities](https://documentation.bamboohr.com/reference/list-employee-break-availabilities.md): Retrieves break availability information for an employee. Requires permission to view the target employee in addition to time-tracking-break access.  OAuth Scopes: time_tracking:breaks
- [List Break Assessments](https://documentation.bamboohr.com/reference/list-break-assessments.md): Returns a paginated list of break assessments. A break assessment records whether an employee complied with their assigned break policy for a given day, along with any violations. Use the `filter` parameter to scope results by employee, date, result, or other fields. Use `offset` and `limit` for pagination; `limit` defaults to 100 and may not exceed 500.  OAuth Scopes: time_tracking:breaks
- [Get Break Policy Suggestions](https://documentation.bamboohr.com/reference/get-break-policy-suggestions.md): Uses an AI agent to analyze existing break policies and company context, then returns structured meal and rest break policy recommendations ready for form pre-fill.  OAuth Scopes: time_tracking:breaks
- [List Time Tracking Projects](https://documentation.bamboohr.com/reference/list-projects.md): Returns a paginated list of time tracking projects. Supports OData-style `filter` and `sort` query parameters. Pagination is page-based via `page` and `pageSize` (defaults: page 1, pageSize 100, max 500).  OAuth Scopes: time_tracking:project
- [Create Time Tracking Project](https://documentation.bamboohr.com/reference/create-project.md): Creates a new time tracking project. Returns the newly created project resource on success.  OAuth Scopes: time_tracking:project.write
- [Get Time Tracking Project](https://documentation.bamboohr.com/reference/get-project.md): Retrieves a single time tracking project by its ID, including the list of employees assigned to it.  OAuth Scopes: time_tracking:project
- [Delete Time Tracking Project](https://documentation.bamboohr.com/reference/delete-project.md): Deletes a time tracking project by its ID.  OAuth Scopes: time_tracking:project.write
- [Update Time Tracking Project](https://documentation.bamboohr.com/reference/update-project.md): Partially updates a time tracking project identified by its ID. Only fields provided in the request body are updated; omitted fields are left unchanged.  OAuth Scopes: time_tracking:project.write
- [List Time Tracking Project Tasks](https://documentation.bamboohr.com/reference/list-project-tasks.md): Returns a paginated list of tasks for the specified time tracking project. Tasks are filtered by `statuses[]`, which defaults to `active`.  OAuth Scopes: time_tracking:project
- [Create Time Tracking Project Task](https://documentation.bamboohr.com/reference/create-project-task.md): Creates a new task on the specified time tracking project.  OAuth Scopes: time_tracking:project.write
- [Get Time Tracking Task](https://documentation.bamboohr.com/reference/get-task.md): Retrieves a single time tracking task by its ID.  OAuth Scopes: time_tracking:project
- [Delete Time Tracking Task](https://documentation.bamboohr.com/reference/delete-task.md): Deletes a time tracking task by its ID.  OAuth Scopes: time_tracking:project.write
- [Update Time Tracking Task](https://documentation.bamboohr.com/reference/update-task.md): Partially updates a time tracking task identified by its ID. Only fields provided in the request body are updated; at least one field must be provided.  OAuth Scopes: time_tracking:project.write
- [List Time Tracking Shift Differentials](https://documentation.bamboohr.com/reference/list-shift-differentials.md): Returns a paginated list of time tracking shift differentials. Supports OData-style `filter` and `sort` query parameters. Pagination is page-based via `page` and `pageSize` (defaults: page 1, pageSize 20, max 100). Archived rows are excluded by default; include them with `filter=archived eq true`. Soft-deleted rows are never returned.  OAuth Scopes: time_tracking:shift_differentials
- [Create Time Tracking Shift Differential](https://documentation.bamboohr.com/reference/create-shift-differential.md): Creates a new time tracking shift differential.  OAuth Scopes: time_tracking:shift_differentials.write
- [Get Time Tracking Shift Differential](https://documentation.bamboohr.com/reference/get-shift-differential.md): Retrieves a single time tracking shift differential by its ID. Archived shift differentials are returned normally; soft-deleted shift differentials return 404.  OAuth Scopes: time_tracking:shift_differentials
- [Delete Time Tracking Shift Differential](https://documentation.bamboohr.com/reference/delete-shift-differential.md): Deletes a time tracking shift differential by its ID.  OAuth Scopes: time_tracking:shift_differentials.write
- [Update Time Tracking Shift Differential](https://documentation.bamboohr.com/reference/update-shift-differential.md): Partially updates a time tracking shift differential identified by its ID.  OAuth Scopes: time_tracking:shift_differentials.write
- [List new hire packets](https://documentation.bamboohr.com/reference/f44b802c30cdea2b9076b3f82f99c74d.md): Returns a paginated list of new hire packet instances for the company. Each item is a flat summary (no sections, tasks, questions, or GTKY recipients).  OAuth Scopes: onboarding
- [Get new hire packet by id](https://documentation.bamboohr.com/reference/696f0a229cdde60b733568e3c4d043d9.md): Returns a single new hire packet instance with a derived status. Sub-resources (sections, tasks, questions, GTKY) are not included.  OAuth Scopes: onboarding
- [Create new hire packet](https://documentation.bamboohr.com/reference/ec1ba8e76f33960b018d0d7518fe97b5.md): Creates a new hire packet instance (draft) for an employee. Company configuration is applied for default inclusion flags.  OAuth Scopes: onboarding.write
- [Update new hire packet](https://documentation.bamboohr.com/reference/1ab0279d46023eb951a434f24df885f1.md): Updates an existing new hire packet instance. Sent, viewed, and completed timestamps are not changed through this endpoint.  OAuth Scopes: onboarding.write
- [Delete new hire packet](https://documentation.bamboohr.com/reference/caa7fc488bcfaef14125398f2ebb987d.md): Deletes a new hire packet instance by primary key.  OAuth Scopes: onboarding.write
- [Send new hire packet](https://documentation.bamboohr.com/reference/f49b0f1f2fb1ef2c408ba12916ee9baa.md): Sends the new hire packet for that packet's employee (email or onboarding experience workflow, depending on company configuration). The packet must be in draft state.  OAuth Scopes: onboarding.write
- [Cancel new hire packet](https://documentation.bamboohr.com/reference/19c7e26a1347ae7eb22919e9b0595c19.md): Cancels the new hire packet. Completed packets cannot be cancelled.  OAuth Scopes: onboarding.write
- [List employee onboarding experiences](https://documentation.bamboohr.com/reference/0158de7cde2a4c4cf577f0b25070d809.md): Returns onboarding experiences for the employee when the onboarding experience phase-1 and workflow framework company toggles are enabled, and at least one OnboardingExperienceWorkflow execution is running for them. Each item is projected from the employee’s new hire packet instance row for the same public id contract (no embedded NHP payload).  OAuth Scopes: onboarding
- [Create employee onboarding experience](https://documentation.bamboohr.com/reference/288aa996aba16d7a495c62321ea999a9.md): Creates (starts) an onboarding experience workflow for the employee’s existing new hire packet instance. Requires the onboarding experience phase-1 and workflow framework company toggles. Optional sentDateTime may be supplied for workflow idempotency (ISO 8601 or legacy datetime string accepted when non-empty).  OAuth Scopes: onboarding.write
- [Get employee onboarding experience by id](https://documentation.bamboohr.com/reference/847dd061d1d1859e7ce8cb3adfc9faf2.md): Returns a single onboarding experience when the onboarding experience phase-1 and workflow framework company toggles are enabled, the employee has at least one running OnboardingExperienceWorkflow (execution status RUNNING), the path id matches their current new hire packet instance id, and the row belongs to the employee. NHP fields are referenced by id only.  OAuth Scopes: onboarding
- [Get welcome new hires widget](https://documentation.bamboohr.com/reference/044949386f2d655c6a627ef53f9434b7.md): Returns the upcoming-new-hires data that powers the BambooHR home "Welcome New Hires" widget. Items are ordered by most recent hire date first. The list reflects the authenticated user's new-hire-packet and company-directory access — when either is missing the response is an empty list (not 403). Sensitive contact fields (work email, home email) are never returned.  OAuth Scopes: onboarding
- [Update GTKY answer visibility for a new hire packet](https://documentation.bamboohr.com/reference/update-new-hire-packet-gtky-answer-visibility.md): Shows or hides get-to-know-you (GTKY) question answers for the packet. Omit questionIds to toggle all answers (same as the legacy BFF POST /onboarding/questions/visibility/{newHirePacketId} with a visible query flag). Send questionIds to toggle only specific personal questions linked to this new hire packet. Requires the same edit access as other NHP writes. When the employee has a hire date set, updates are rejected once the company-local calendar date is on or after that date (same rule as GET /onboarding/questions/{newHirePacketId}, which redirects to expired in that case). Draft employees without a hire date are not blocked.  OAuth Scopes: onboarding.write
- [Photos](https://documentation.bamboohr.com/reference/photos.md)
- [Get Employee Photo](https://documentation.bamboohr.com/reference/get-employee-photo.md): Returns an employee photo at the requested size. Available sizes are: `original` (full resolution), `large` (340×340), `medium` (170×170), `small` (150×150), `xs` (50×50), and `tiny` (20×20). The response shape is selected via standard HTTP content negotiation. By default the body is the stored image bytes and the `Content-Type` response header matches the body (`image/jpeg`, `image/png`, `image/bmp`, `image/gif`, or `image/tiff`). When the caller sends `Accept: application/json`, the body is a JSON object `{ mimeType, fileBase64 }` with the same image bytes base64-encoded. The JSON variant is not recommended for AI connector use, since the base64 payload is too large for an AI model to consume reliably as text input. For AI connectors that need to display or reference a photo, use the `photoUrl` field returned by `list-employees` instead. It is a time-limited signed URL that avoids transferring image bytes through the AI model's context.  A 404 response covers three distinct cases: (1) the employee exists but has no photo on file (a normal, non-error state), (2) the employee ID does not exist, or (3) the size value is not one of the recognized options. The `x-bamboohr-error-message` response header distinguishes them: `Employee photo not found`, `Employee not found`, or `Size: "<value>" is not a valid size option. Valid sizes are: xs, small, tiny, original, medium and large.`. Treat "Employee photo not found" as a normal "no photo on file" result rather than as a bad employee ID, permission failure, or other error to debug.  OAuth Scopes: employee:photo
- [Upload Employee Photo](https://documentation.bamboohr.com/reference/upload-employee-photo.md): Uploads a new photo for an employee. Accepts a `multipart/form-data` POST with a `file` field carrying raw binary image bytes (typical browser and SDK usage). An `application/json` POST with a `fileBase64` property is also accepted, but it is not recommended for AI connector use. The base64 payload is too large for an AI model to produce reliably in a single tool call. Supported formats: JPEG, PNG, BMP, GIF. Other formats (HEIC, SVG, AVIF, WebP) are rejected with 415. TIFF is accepted by the format gate but some variants may fail downstream. The image must be square within 1 pixel and at least 150×150 pixels. This endpoint does not perform cropping, so if your source image is not square, you must crop it before uploading. Photo upload through this endpoint is not a viable AI connector workflow. For interactive cropping or any AI-initiated photo change, redirect the user to the BambooHR web UI. Maximum file size is 20MB (applies to the decoded bytes for the JSON variant). The photo replaces the employee's current photo for all size variants. Employees may upload their own photo if the company has self-photo uploads enabled.  OAuth Scopes: employee:photo.write
- [Get Company Report](https://documentation.bamboohr.com/reference/get-company-report.md): **Deprecated. Use Custom Reports > Get Report by ID instead.**  Returns the data from an existing saved custom report. Non-admins can find these reports in My Reports. Admins can find them in Custom Reports under the My Reports and Company Reports tabs. The report ID can be found by hovering over the report name in BambooHR and noting the ID in the URL. Standard Reports are not available via this endpoint, and report IDs are company-specific.  The caller must have permission to view or access the report. The `format` query parameter is case-insensitive (`json`, `JSON`, `Json` are all accepted). If `format` is omitted, the output format is inferred from the `Accept` header, but only these exact values are supported: `application/json`, `text/xml`, `text/csv`, `application/pdf`, `application/vnd.ms-excel`. Any other `Accept` value (including `application/xml` and `*/*`) returns 404.  OAuth Scopes: report
- [Request Custom Report](https://documentation.bamboohr.com/reference/request-custom-report.md): **Deprecated. Use Datasets > Get Data from Dataset instead.**  Generates an ad-hoc employee report based on a caller-specified list of fields and optional filters. Returns report data in the requested format (JSON, XML, CSV, XLS, or PDF). The report includes all employees regardless of status (both Active and Inactive), unlike the BambooHR UI which filters to Active employees by default.  The request body may be submitted as JSON or XML. To submit JSON, set `Content-Type: application/json` exactly — any variation such as `application/json; charset=UTF-8` is not recognised as JSON and the body will be parsed as XML instead, which typically results in `400 Malformed XML`. To submit XML, set `Content-Type` to any other value; the body must be a `<report>` document as described in the XML request body schema.  The `format` query parameter is case-insensitive (`json`, `JSON`, `Json` are all accepted). If `format` is omitted, the output format is inferred from the `Accept` header, but only these exact values are supported: `application/json`, `text/xml`, `text/csv`, `application/pdf`, `application/vnd.ms-excel`. Any other `Accept` value (including `application/xml` and `*/*`) will return 404.  Field IDs in the request that are unknown or that the caller does not have permission to view are silently omitted from the report — the endpoint still returns 200. The `filters` object supports `lastChanged` (ISO 8601 date-time to filter employees by last-modified date, with optional `includeNull` control) and `employeeIds` (restrict results to specific internal employee IDs). The maximum number of fields per request is 400.  OAuth Scopes: report
- [List Schedules](https://documentation.bamboohr.com/reference/scheduling-list-schedules.md): Retrieves a paginated list of all schedules for the company. Supports optional OData-style filtering and sorting.  OAuth Scopes: scheduling:schedules, time_tracking
- [Create Schedule](https://documentation.bamboohr.com/reference/scheduling-create-schedule.md): Creates a new schedule for the company. Rejects duplicate schedule data for the same location and configuration.  OAuth Scopes: scheduling:schedules.write, time_tracking.write
- [Get Schedule](https://documentation.bamboohr.com/reference/scheduling-get-schedule.md): Retrieves a specific schedule by its UUID. Schedules organize shifts for employees.  OAuth Scopes: scheduling:schedules, time_tracking
- [Delete Schedule](https://documentation.bamboohr.com/reference/scheduling-delete-schedule.md): Deletes a schedule by its UUID. Unworked shifts will be deleted as a result.  OAuth Scopes: scheduling:schedules.write, time_tracking.write
- [Update Schedule](https://documentation.bamboohr.com/reference/scheduling-update-schedule.md): Partially updates an existing schedule by its UUID. Fields not provided retain their existing values.  OAuth Scopes: scheduling:schedules.write, time_tracking.write
- [List Timezones](https://documentation.bamboohr.com/reference/scheduling-list-timezones.md): Returns a paginated list of timezones available for use when creating or editing schedules. Supports OData-style filtering on the `name` field.  OAuth Scopes: scheduling:schedules, time_tracking
- [Get Shift](https://documentation.bamboohr.com/reference/scheduling-get-shift.md): Retrieves a single shift by its UUID. Returns the full shift object including recurrence settings, assigned employee IDs, and status. Returns 404 if the shift does not exist or has been deleted.  OAuth Scopes: scheduling:shifts, time_tracking
- [Delete Shift](https://documentation.bamboohr.com/reference/scheduling-delete-shift.md): Deletes a shift by its UUID or composite recurrence ID. Use `recurrenceEditOption` to control the scope to delete one or many consecutive recurring shifts  OAuth Scopes: scheduling:shifts.write, time_tracking.write
- [Update Shift](https://documentation.bamboohr.com/reference/scheduling-update-shift.md): Updates a shift by its UUID. Fields not provided will retain their existing values. For published shifts, changes are not applied directly — they are stored as pending (`unpublishedChanges`) and take effect when the shift is published. `recurrenceEditOption` is required when the shift already has recurrence settings; ALL and FUTURE edits propagate to published sibling occurrences the same way, staging changes rather than applying them immediately. Sibling shifts may be permanently removed if they no longer conform to changed recurrence fields.  OAuth Scopes: scheduling:shifts.write, time_tracking.write
- [List Shifts](https://documentation.bamboohr.com/reference/scheduling-list-shifts.md): Lists shifts matching the given filters. Either provide `ids` (ignores all other filters) or provide `start`, `end`, and at least one of `employeeIds` or `scheduleIds`. The time window must be no longer than 1 month. Defaults to returning planned and published shifts.  OAuth Scopes: scheduling:shifts, time_tracking
- [Create Shift](https://documentation.bamboohr.com/reference/scheduling-create-shift.md): Creates a new shift in the specified schedule.  OAuth Scopes: scheduling:shifts.write, time_tracking.write
- [Publish Shifts](https://documentation.bamboohr.com/reference/scheduling-publish-shifts.md): Publishes one or more planned shifts, making them visible to employees. Shifts with scheduling conflicts are skipped and reported as failures. Returns 200 if all shifts succeed, 207 if some shifts failed due to conflicts, or 409 if all shifts failed due to conflicts.  OAuth Scopes: scheduling:shifts.write, time_tracking.write
- [Get Schedule PDF](https://documentation.bamboohr.com/reference/scheduling-get-schedule-pdf.md): Generates and streams a PDF of the schedule view for the given schedule and date range.  OAuth Scopes: scheduling:schedules
- [List Shift Assessments](https://documentation.bamboohr.com/reference/scheduling-list-shift-assessments.md): Lists shift assessments matching the given filters. A filter is required and must include at least one of: employeeId, shiftId, or a date range bound (gt/ge/lt/le on date). Results are scoped to the assessments the authenticated user may view.  OAuth Scopes: scheduling:shifts
- [Time Off](https://documentation.bamboohr.com/reference/time-off.md)
- [List Time Off Policies](https://documentation.bamboohr.com/reference/list-time-off-policies.md): Returns all non-deleted time off policies for the company, sorted alphabetically by name. Only includes policies whose time off type has not been deleted.  OAuth Scopes: time_off
- [List Time Off Types](https://documentation.bamboohr.com/reference/list-time-off-types.md): Lists the company's active time off types — PTO options, vacation, sick leave, and other time off categories — along with the company's default hours-per-day schedule. Pass `mode=request` to filter to only types the authenticated employee has permission to request. Time off type names are company-configured labels; common terms like "PTO" may not appear verbatim and may be expressed as "Vacation" or another company-specific name. The returned list is also permission-filtered: an admin caller may see types (e.g., "Sick") that a non-admin caller does not, so the set available for a given user depends on the caller's role. If a user's term does not exactly match a returned type name, present the available types as options rather than choosing one heuristically.  OAuth Scopes: time_off
- [Get Time Off Balance](https://documentation.bamboohr.com/reference/get-time-off-balance.md): Returns time off balances for an employee across all assigned categories as of a given date. Each category's balance is calculated by summing all historical balance events (accruals, manual adjustments, used time off, and carry-over events) plus any future accruals and adjustments up to the specified date. To get current balances, pass today's date; to project future balances, pass a future date. Response defaults to XML unless Accept: application/json is provided.  OAuth Scopes: time_off
- [Adjust Time Off Balance](https://documentation.bamboohr.com/reference/adjust-time-off-balance.md): Creates a balance adjustment for an employee's time off type. The adjustment is recorded as an override history item. Cannot adjust balances for discretionary (unlimited) time off types.  OAuth Scopes: time_off.write
- [Create Time Off History Item](https://documentation.bamboohr.com/reference/create-time-off-history.md): Creates a time off history item for an employee. For `used` type entries, a `timeOffRequestId` referencing an approved request is required. For `override` (balance adjustment) entries via the /history path, provide the `amount` and `timeOffTypeId` directly. The `eventType` defaults based on the URI path when omitted.  OAuth Scopes: time_off.write
- [List Time Off Requests](https://documentation.bamboohr.com/reference/list-time-off-requests.md): Returns time off requests within the specified date range. Both `start` and `end` query parameters are required (YYYY-MM-DD). The search is inclusive: requests whose date range overlaps the query window are returned. Results can be filtered by status, employee, time off type, or limited to requests the caller can approve.  OAuth Scopes: time_off
- [Create Time Off Request](https://documentation.bamboohr.com/reference/create-time-off-request.md): Creates a time off request for an employee. The request can be submitted with a status of `approved`, `denied`, or `requested`. Submitting `approved` or `denied` is only honored when the caller is an owner/admin or has view/edit access to the time off type field for the target employee; other callers receive 403. When honored, these statuses record the request directly and suppress approval notifications. Supplying a `previousRequest` ID performs a destructive supersede: the prior request's status is set to `superceded`, all approvals on its workflow are removed and the workflow is marked deleted, and any home-page notifications tied to that workflow are deleted. Accepts both JSON and XML request bodies.  OAuth Scopes: time_off.write
- [Update Time Off Request Status](https://documentation.bamboohr.com/reference/update-time-off-request-status.md): Updates the status of an existing time off request. Valid statuses are `approved`, `denied` (or `declined`), and `canceled`. Owner/admins can approve out of turn by completing all workflow steps at once; other approvers complete only their current step.  OAuth Scopes: time_off.write
- [List Who’s Out](https://documentation.bamboohr.com/reference/list-whos-out.md): Returns a date-sorted list of employees who are out and company holidays for the specified period. Defaults to today through 14 days out when dates are omitted. Results include both `timeOff` entries (employee requests) and `holiday` entries, each identified by `type`. An empty array may mean no one is out, or that no holidays have been configured in the BambooHR company calendar — holidays must be set up there before they appear here. The `filter: off` parameter applies only to employee time-off entries; holidays are independently filtered per-employee based on holiday visibility settings, and that filter is not disabled by `filter: off`.  OAuth Scopes: time_off
- [List Employee Time Off Policies (v1)](https://documentation.bamboohr.com/reference/list-employee-time-off-policies-v1.md): Deprecated. Use **List Employee Time Off Policies (v1.1)** instead (`list-employee-time-off-policies-v1-1`). Returns the time off policies currently assigned to the specified employee, including policy ID, time off type, and accrual start date.  OAuth Scopes: time_off
- [Assign Time Off Policies (v1)](https://documentation.bamboohr.com/reference/assign-time-off-policies-v1.md): Deprecated. Use **Assign Time Off Policies (v1.1)** instead (`assign-time-off-policies-v1-1`). Assigns time off policies to an employee with accruals starting on the specified date. A null start date removes the existing assignment. On success, returns the current list of assigned policies.  OAuth Scopes: time_off.write
- [List Employee Time Off Policies (v1.1)](https://documentation.bamboohr.com/reference/list-employee-time-off-policies-v1-1.md): Returns the time off policies currently assigned to a specific employee, as a list of `{timeOffPolicyId, timeOffTypeId, accrualStartDate}` records. Use this to find which policy governs each time off type for this employee and when their accruals began. This is the per-employee assignment view; use `list-time-off-policies` for the company-wide policy catalog. Includes all policy types (accruing, manual, and unlimited); the v1 form of this endpoint excluded manual and unlimited types — v1.1 includes them.  OAuth Scopes: time_off
- [Assign Time Off Policies (v1.1)](https://documentation.bamboohr.com/reference/assign-time-off-policies-v1-1.md): Assigns time off policies to an employee with accruals starting on the specified date. On success, returns the current list of assigned policies including manual and unlimited policy types.  OAuth Scopes: time_off.write
- [Add Employees to Total Rewards](https://documentation.bamboohr.com/reference/add-total-rewards-employees.md): Add employees to Total Rewards. Each employee will have a Total Rewards profile created and will be notified if they are active users.  OAuth Scopes: total_rewards.write
- [Remove Employees from Total Rewards](https://documentation.bamboohr.com/reference/remove-total-rewards-employees.md): Remove employees from Total Rewards. Their Total Rewards profiles will be deleted.  OAuth Scopes: total_rewards.write
- [Set Total Rewards Onboarding Step Status](https://documentation.bamboohr.com/reference/set-total-rewards-onboarding-step.md): Set a Total Rewards onboarding step to completed or incomplete. Valid step names are defined by the Total Rewards onboarding configuration.  OAuth Scopes: total_rewards.write
- [Set Total Rewards Custom Disclaimer](https://documentation.bamboohr.com/reference/set-total-rewards-custom-disclaimer.md): Set the company-wide Total Rewards custom disclaimer text shown on employee statements.  OAuth Scopes: total_rewards.write
- [Remove Total Rewards Custom Disclaimer](https://documentation.bamboohr.com/reference/remove-total-rewards-custom-disclaimer.md): Remove the company-wide Total Rewards custom disclaimer. After removal, the default disclaimer will be shown on employee statements.  OAuth Scopes: total_rewards.write
- [Get Total Rewards Statement](https://documentation.bamboohr.com/reference/get-total-rewards-statement.md): Returns the full Total Rewards statement for the given employee, including compensation, benefits, bonuses, equity, reimbursements, and time-off data.  OAuth Scopes: total_rewards
- [Check Total Rewards Profile Availability](https://documentation.bamboohr.com/reference/check-total-rewards-profile.md): Check if the given employee has an active Total Rewards profile and the current user has permission to view it. Returns 204 when the employee has a profile and the user is authorized; 404 if the profile does not exist or the user lacks access.  OAuth Scopes: total_rewards
- [Get Printable Total Rewards Statement](https://documentation.bamboohr.com/reference/get-total-rewards-printable-statement.md): Generate and return a PDF printable version of the employee's Total Rewards statement.  OAuth Scopes: total_rewards
- [Training](https://documentation.bamboohr.com/reference/training.md)
- [List Training Types](https://documentation.bamboohr.com/reference/list-training-types.md): Returns all training types for the company as an object keyed by training type ID. Each entry includes the training name, renewable status, renewal frequency, required status, due-date window for new hires, category, link URL, description, and self-completion permission. The authenticated caller must have access to training settings.  OAuth Scopes: training
- [Create Training Type](https://documentation.bamboohr.com/reference/create-training-type.md): Creates a new training type. Only 'name' is required; all other fields are optional. When 'renewable' is true, 'frequency' (months between renewals) must also be provided. The 'dueFromHireDate' field is only valid when 'required' is true. The authenticated caller must have access to training settings.  OAuth Scopes: training.write
- [Update Training Type](https://documentation.bamboohr.com/reference/update-training-type.md): Updates an existing training type. Only provided fields are updated. To remove a category, pass an empty string or null for the category field. Returns 405 when the training type cannot be modified. The authenticated caller must have access to training settings.  OAuth Scopes: training.write
- [Delete Training Type](https://documentation.bamboohr.com/reference/delete-training-type.md): Delete an existing training type. The authenticated caller must have access to training settings. Deleting a training type will only be successful if all employee trainings for this type have been removed prior to this request.  OAuth Scopes: training.write
- [List Training Categories](https://documentation.bamboohr.com/reference/list-training-categories.md): Returns all training categories for the company as an object keyed by category ID. Each entry contains the category ID and name. The authenticated caller must have access to training settings.  OAuth Scopes: training
- [Create Training Category](https://documentation.bamboohr.com/reference/create-training-category.md): Creates a new training category. The 'name' field is required. Returns the created TrainingCategory on success. The authenticated caller must have access to training settings.  OAuth Scopes: training.write
- [Update Training Category](https://documentation.bamboohr.com/reference/update-training-category.md): Updates the name of an existing training category. Returns 409 if a category with the same name already exists. The authenticated caller must have access to training settings.  OAuth Scopes: training.write
- [Delete Training Category](https://documentation.bamboohr.com/reference/delete-training-category.md): Delete an existing training category. The authenticated caller must have access to training settings.  OAuth Scopes: training.write
- [List Employee Training Records](https://documentation.bamboohr.com/reference/list-employee-trainings.md): Returns all training records for the specified employee as an object keyed by training record ID. Use the optional 'type' query parameter to filter by training type ID. Fields such as instructor, credits, hours, and cost are only included when enabled in the company's training settings. The authenticated caller must have permission to view the employee.  OAuth Scopes: training
- [Create Employee Training Record](https://documentation.bamboohr.com/reference/create-employee-training-record.md): Creates a new training record for the specified employee. The 'completed' date (yyyy-mm-dd) and 'type' (training type ID) are required. Optional fields include instructor, hours, credits, notes, and cost. The authenticated caller must have permission to add trainings for the employee.  OAuth Scopes: training.write
- [Update Employee Training Record](https://documentation.bamboohr.com/reference/update-employee-training-record.md): Updates an existing employee training record. The 'completed' date (yyyy-mm-dd) is required; all other fields are optional. Returns the updated TrainingRecord with HTTP 201. Returns 405 when the record cannot be updated. The authenticated caller must have permission to edit trainings for the employee.  OAuth Scopes: training.write
- [Delete Employee Training Record](https://documentation.bamboohr.com/reference/delete-employee-training-record.md): Delete an existing employee training record. The authenticated caller must have permission to view and edit the employee and training type.  OAuth Scopes: training.write
- [Webhooks](https://documentation.bamboohr.com/reference/webhooks.md)
- [Get Webhook Post Fields](https://documentation.bamboohr.com/reference/get-post-fields.md): 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
- [List Webhooks](https://documentation.bamboohr.com/reference/list-webhooks.md): Returns all webhooks owned by the authenticated user. Each entry is a summary with the webhook's ID, name, URL, creation datetime, and last-fired datetime. Returns an empty array when no webhooks exist. Use "Get Webhook" to retrieve the full configuration of a specific webhook, including monitored fields and post fields when applicable, and events.  OAuth Scopes: webhooks
- [Get Webhook](https://documentation.bamboohr.com/reference/get-webhook.md): Returns the full configuration of a single webhook owned by the authenticated user, including its name, URL, format, monitored fields and post fields when applicable, events, creation datetime, and last-sent datetime. Returns 403 if the webhook exists but belongs to a different user, and 404 if the webhook does not exist.  OAuth Scopes: webhooks
- [Create Webhook](https://documentation.bamboohr.com/reference/create-webhook.md): Creates a new webhook for the authenticated user. The webhook will fire when the specified events occur or when any of the monitored fields change.  The `monitorFields` array is required when `events` includes `employee.updated` or `employee_with_fields.updated`. If `events` is omitted, it defaults to `['employee_with_fields.updated', 'employee_with_fields.deleted', 'employee_with_fields.created']`, which means `monitorFields` is required by default. The `format` field is required.  The response includes a `privateKey` that should be used to verify the authenticity of incoming webhook payloads via HMAC-SHA256. This key is only returned at creation time and cannot be retrieved again.  For more details refer to the [webhooks documentation](https://documentation.bamboohr.com/docs/webhooks), including guides for [event-based](https://documentation.bamboohr.com/docs/event-based-webhooks) and [field-based](https://documentation.bamboohr.com/docs/field-based-webhooks) webhooks.  For details on the payloads sent by each event, see the event reference: - [employee.created](https://documentation.bamboohr.com/reference/employee-created-webhook) - [employee.updated](https://documentation.bamboohr.com/reference/employee-updated-webhook) - [employee.deleted](https://documentation.bamboohr.com/reference/employee-deleted-webhook)  OAuth Scopes: webhooks, webhooks.write
- [Update Webhook](https://documentation.bamboohr.com/reference/update-webhook.md): Performs a full replacement update of a webhook — all request body fields overwrite existing values, so omitted optional fields revert to defaults. The `monitorFields` array must be non-empty when the webhook's events include `employee.updated` or `employee_with_fields.updated` (the default event set includes `employee_with_fields.updated`). The private key is not regenerated on update. Use List Webhooks to discover webhook IDs.  OAuth Scopes: webhooks, webhooks.write
- [Delete Webhook](https://documentation.bamboohr.com/reference/delete-webhook.md): Permanently removes a webhook owned by the authenticated user. A webhook can only be deleted by the same credentials that created it; attempting to delete another user's webhook returns 403. Use List Webhooks to find webhook IDs.  OAuth Scopes: webhooks, webhooks.write
- [Employee Created](https://documentation.bamboohr.com/reference/employee-created-webhook.md): Triggered when a new employee is created.  ### Behavior & Constraints - **Creation Sequence**: When an employee is created, both `employee.created` and `employee.updated` events fire sequentially due to the create-then-initialize pattern. - **Data Availability**: The `data` object contains the `companyId` and `employeeId` of the newly created employee. - **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.  ### Deprecation Notice **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.  **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.
- [Employee Updated](https://documentation.bamboohr.com/reference/employee-updated-webhook.md): Triggered when an employee record is updated and at least one of the monitored fields has changed.  ### Behavior & Constraints - **Monitoring**: At least one `monitorField` is required when subscribing to this event via `POST /api/v1/webhooks`. - **Permissions**: For API-created webhooks, this event will not fire if the webhook creator lacks access to all monitored fields being changed.  ### Detailed Description - **Creation Sequence**: When an employee is created, both `employee.created` and `employee.updated` events fire sequentially due to the create-then-initialize pattern. - **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. - **Effective Dates**: For history-tracked fields (e.g., `jobTitle`, `payRate`), events fire only when changes take effect, not when future-dated changes are created. - **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`.  ### Deprecation Notice **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.  **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.
- [Employee Deleted](https://documentation.bamboohr.com/reference/employee-deleted-webhook.md): Triggered when an employee is deleted.  ### Behavior & Constraints - **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.  ### Deprecation Notice **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.  **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.
- [Company Integrations Updated](https://documentation.bamboohr.com/reference/company-integrations-updated-webhook.md): Triggered when company integrations are updated.  ### Behavior & Constraints - **Permission Checking**: This event does **not** enforce permission checking. The webhook will fire for all subscribers regardless of the API token's permissions. - **Event Scope**: This event fires when any integration settings are modified for the company, including enabling, disabling, or updating integration configurations.
- [Company Updated](https://documentation.bamboohr.com/reference/company-updated-webhook.md): Triggered when company information or company status changes.  ### Behavior & Constraints - This event is emitted for general company updates. - When the underlying change is a company status change, the emitted event depends on the new status:   - If the new status is `DELETED` or `CANCELLED`, the system emits `company.deleted` instead.   - Otherwise the system emits `company.updated`.
- [Company Deleted](https://documentation.bamboohr.com/reference/company-deleted-webhook.md): Triggered when a company status change results in the company being considered deleted/closed.  ### Behavior & Constraints - This event is emitted when the new company status is `DELETED` or `CANCELLED`. - For other company updates and status changes, the system emits `company.updated`.
- [List Webhook Logs](https://documentation.bamboohr.com/reference/list-webhook-logs.md): Returns an array of recent delivery log entries for a webhook. Use List Webhooks to find webhook IDs. Logs cover the last 14 days and are limited to 200 entries. The `lastAttempted` and `lastSuccess` fields are usually UTC datetimes in `YYYY-MM-DD HH:MM:SS` format, but may instead contain status strings such as `Webhook Not Found`. Returns an empty array if no deliveries have occurred in the lookback window.  **Rate limiting:** This endpoint is rate-limited. When the rate limit is exceeded the server still returns HTTP 200, but the body is `{"error":{"code":429,"message":"Over rate limit, please try again in 60 seconds"}}` instead of the log array. Callers should check for this shape before processing the response as a log list.  OAuth Scopes: webhooks
- [List Monitor Fields](https://documentation.bamboohr.com/reference/list-monitor-fields.md): Returns the list of employee fields that can be monitored by a webhook. Monitor fields are only applicable to webhooks that use update events (`employee.updated` or `employee_with_fields.updated`). Use the field IDs or aliases from this response in the `monitorFields` array when creating or updating a webhook via Create Webhook or Update Webhook.  OAuth Scopes: webhooks
- [Update Company Industry Codes](https://documentation.bamboohr.com/reference/put-company-industry-codes.md): Updates the industry codes associated with a company.  OAuth Scopes: company:details.write
- [List job titles with employees](https://documentation.bamboohr.com/reference/3af7d1ac36c35008b8ebb93fecbdb35b.md): Get job titles with their associated employees for levels and bands configuration.  OAuth Scopes: pay_grades_and_bands
- [Get compensation level group status counts](https://documentation.bamboohr.com/reference/99b887959832c80eead3a176acc0c2d4.md): Get the count of compensation level groups in each status (draft, published, historic).  OAuth Scopes: pay_grades_and_bands
- [Get levels and bands status](https://documentation.bamboohr.com/reference/6fbb2fe60e374d2204f1222252105945.md): Get the validation status of each step in the levels and bands configuration wizard.  OAuth Scopes: pay_grades_and_bands
- [List compensation level groups and levels](https://documentation.bamboohr.com/reference/db8c61787c931b69afbf9e501be85256.md): Get all compensation level groups and levels with validation errors and warnings.  OAuth Scopes: pay_grades_and_bands
- [Get pay bands for levels](https://documentation.bamboohr.com/reference/fb29d4d4790104b6892a4b6d6db67e19.md): Get pay bands for each compensation level with validation errors and warnings. If percentageRange is null, band type is min-mid-max; otherwise it is percentage-based.  OAuth Scopes: pay_grades_and_bands
- [Get job titles and level assignments](https://documentation.bamboohr.com/reference/4acdbb25aa278f9f94b44b42ef9f1b27.md): Get job titles with their associated compensation levels and all groups/levels. Returns job titles mapped to level IDs and complete group/level hierarchy.  OAuth Scopes: pay_grades_and_bands
- [Get levels and bands review data](https://documentation.bamboohr.com/reference/12c40475623893cf0434b3ae69e36975.md): Get consolidated review data for levels and bands with all validation errors and warnings across all steps.  OAuth Scopes: pay_grades_and_bands
- [Get published levels and bands](https://documentation.bamboohr.com/reference/cfacff2b34cf1e65ccd1ab188c5e1d12.md): Get published levels and bands data including compensation level groups, levels, pay bands, and job title assignments.  OAuth Scopes: pay_grades_and_bands
- [List bank holidays](https://documentation.bamboohr.com/reference/get-bank-holidays.md): Returns the list of global bank holiday reference dates (US federal and related bank holidays maintained in BambooHR). This is distinct from company-configured holidays. Optionally filter to holidays whose dates fall in a single calendar year.  OAuth Scopes: meta
- [Save compensation level groups and levels](https://documentation.bamboohr.com/reference/432e469fe5959a6ccd765d02018e7db4.md): Upsert compensation level groups and levels. Creates new groups or levels or updates existing ones. Does not delete existing data not included in the request.  OAuth Scopes: pay_grades_and_bands.write
- [Update pay bands](https://documentation.bamboohr.com/reference/ad7871529b2a9c6612f8dd3c62192c08.md): Bulk update pay bands for compensation levels.  OAuth Scopes: pay_grades_and_bands.write
- [Update job title level assignments](https://documentation.bamboohr.com/reference/2a0b847ceec3a4f9bfe20cf27e10e81a.md): Replace draft job title-to-level assignments with the provided associations.  OAuth Scopes: pay_grades_and_bands.write
- [Publish draft compensation level groups](https://documentation.bamboohr.com/reference/22932a81ba129f22114ccdef397af933.md): Publish all draft compensation level groups and mark any published groups as historic.  OAuth Scopes: pay_grades_and_bands.write
- [Import levels and bands from CSV](https://documentation.bamboohr.com/reference/cdd8659ca89fb38042fd56feab507edf.md): Parse and validate a levels and bands CSV upload and return suggested mappings and validation results.  OAuth Scopes: pay_grades_and_bands.write
- [Delete groups by status or delete one level](https://documentation.bamboohr.com/reference/0da9c9f851462d2e44dfe866b8e67e74.md): Delete compensation level groups when `segment` is `draft`, `published`, or `historic`, or delete a single compensation level when `segment` is a numeric level identifier.  OAuth Scopes: pay_grades_and_bands.write
- [Get Industries](https://documentation.bamboohr.com/reference/get-industries.md): Returns the complete list of industry reference data including codes. Use the returned IDs when creating or updating company profiles.  OAuth Scopes: meta
- [Get country by ID](https://documentation.bamboohr.com/reference/get-meta-country-by-id.md): Returns a single country by catalog id. Response fields match each element of GET /api/v1/meta/countries/options (`id`, `name`, `isoCode` and nullability).  OAuth Scopes: meta
- [Get currency conversion rates](https://documentation.bamboohr.com/reference/get-currency-conversions.md): Returns a snapshot of currency conversion rates for the specified base currency, keyed by ISO 4217 currency code. Rate map keys match the `code` field from GET /api/v1/meta/currency/types. Timestamps are ISO 8601 UTC with a Z offset.  OAuth Scopes: meta
- [API Support](https://documentation.bamboohr.com/reference/api-support.md)

## Pages
- [Using OpenID Connect to Authenticate and Retrieve an API Key](https://documentation.bamboohr.com/authenticate-integration.md)
- [OpenID Connect Login API](https://documentation.bamboohr.com/openid-connect-login-api.md)
- [Single Sign-On (SSO) with OpenID Connect](https://documentation.bamboohr.com/single-sign-on-sso-with-openid-connect.md)