> ## Documentation Index
> Fetch the complete documentation index at: https://www.composer.id/llms.txt
> Use this file to discover all available pages before exploring further.
# BambooHR
> BambooHR (HRIS / HCM): the API posture, publish target and field mapping composerID publishes a decision reference through.
This page records how composerID publishes into BambooHR: the vendor's API posture, the publish target and field mapping, and the documentation each claim rests on. It is for anyone evaluating the connection or building against it.
BambooHR is a mid-market HRIS with a built-in Hiring (applicant tracking) module and an open REST API centred on the Employee record: stock and tenant-defined custom fields, tabular history (job information, employment status, compensation), time off, custom reports and permissioned webhooks on employee field changes. Custom employee fields are created by an administrator in Settings and appear in the API through the fields metadata endpoint, addressed by numeric id, so they are written and read like stock fields. composerID publishes the approved permanent hire onto the Employee record (stamping the Intent ID into a tenant-defined custom text field, by update when Hiring has already created the employee or on the create call when it has not) and records the link to the Hiring job opening on its own side while the role is open.
Category: HRIS / HCM. Coverage status: Specification mapped. Vendor documentation: public developer portal.
## Integration path
How composerID connects to this destination, at a glance.
| Step | Detail |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authentication | API key over HTTP Basic: the key is the username and any string is the password. |
| composerID publishes | Employee (new hire): POST /v1/employees/ (create; id returned in the Location header) or POST /v1/employees/\{id} (update), then rows on the jobInfo and employmentStatus tables |
| Intent ID lands on | `employee` `customField{fieldId}`, written into the destination record |
| Back-sync | Webhooks and polling: some lifecycle events are pushed, the rest are read on a schedule. |
## Vendor documentation
## API posture
| Aspect | Detail |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authentication | API key over HTTP Basic: the key is the username and any string is the password. Keys are generated per user from that user's account settings and inherit that user's access level, so publishing runs as a dedicated service user with the minimum permissions. OpenID Connect and OAuth are offered to Marketplace partner apps; a customer integration uses API keys. |
| Style | REST, JSON or XML selected by the Accept header (or a format query parameter), company-domain-scoped URL path. Updates are POSTs to the resource (POST /v1/employees/\{id}), not PUT. Tabular history lives in named tables on the Employee (jobInfo, employmentStatus, compensation and others listed by GET /v1/meta/tables). |
| Base URL | [https://api.bamboohr.com/api/gateway.php/\\\{companyDomain\\}/v1](https://api.bamboohr.com/api/gateway.php/\\\{companyDomain\\}/v1) |
| Webhooks | Permissioned webhooks are created through the API (POST /v1/webhooks with name, url, monitorFields, postFields, format, frequency and limit; GET /v1/webhooks/monitor\_fields lists what can be monitored). Deliveries are signed HMAC-SHA256 over the body plus timestamp with the privateKey returned on create, carried in X-BambooHR-Signature and X-BambooHR-Timestamp headers (confirm header names and the exact signed string against the webhooks guide at onboarding). Account-level webhooks can also be configured in the UI by an administrator. There is no webhook for Hiring job or application events; those, and any missed employee changes, are polled with GET /v1/employees/changed?since= and the applicant\_tracking reads. |
| Events posture | Webhooks and polling |
| Rate limits | No fixed request rate is published. Throttled or overloaded calls return 429 or 503; back off and retry. A custom report returns every employee in one response, so prefer one report over per-employee GETs when reconciling. Indicative until confirmed at onboarding. |
| Objects | employees (stock fields and tenant custom fields; GET /v1/meta/fields lists both), employee tables (jobInfo, employmentStatus, compensation, emergencyContacts, dependents; GET /v1/meta/tables), employees/changed, employees/directory, reports (saved reports and POST /v1/reports/custom over any fields), time off (requests, balances, policies), files, webhooks, applicant\_tracking (jobs, applications, statuses, locations) |
## Publish target and field mapping
Each object below pairs the canonical intent fields with the destination's own fields and operations. The mapping is indicative until it is confirmed against a tenant at onboarding.
| Mapping | Detail |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Canonical to destination | role\_title (jobTitle), department, division, location, start\_date (hireDate), employment\_status |
| Target | POST /v1/employees/ (create; id returned in the Location header) or POST /v1/employees/\{id} (update), then rows on the jobInfo and employmentStatus tables |
| Requirement | Required |
| Notes | Only firstName and lastName are required by the API; hireDate, jobTitle, department, division and location can be sent on the create. When the tenant hires through the Hiring module BambooHR creates the Employee itself, so composerID updates that record rather than creating a second one. Compensation and status history are separate table rows. Stock field names are on the vendor's list-of-field-names page. |
| Mapping | Detail |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Canonical to destination | intent\_id -> employee custom text field (tenant-created in Settings; numeric id from GET /v1/meta/fields, custom fields carry no alias) |
| Target | Custom field on the Employee record, written on POST /v1/employees/ or POST /v1/employees/\{id}, read back with GET /v1/employees/\{id}?fields=\{fieldId} or included in POST /v1/reports/custom |
| Requirement | Required |
| Notes | Custom fields cannot be created through the API; onboarding names the field (for example composerID), fixes its numeric field id in the connector configuration and confirms the service user can see and edit it. Reverse lookup is a filter over a custom report that includes the field (the report body only filters on lastChanged), not a server-side query. Deep link to the employee page is illustrative until confirmed, since the BambooHR employee id must first be resolved from the Intent ID. |
| Mapping | Detail |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Canonical to destination | job\_opening\_id, title, department, location, status |
| Target | GET /v1/applicant\_tracking/jobs (statusGroups filter), GET /v1/applicant\_tracking/applications |
| Requirement | Read scope only |
| Notes | The public reference exposes no endpoint to create a job opening; Hiring writes are limited to adding an applicant (POST /v1/applicant\_tracking/application) and changing an application status. The opening is raised in the Hiring UI and composerID records the linkage (Intent ID to job id) on its side. Confirm at onboarding that the tenant's plan includes Hiring and that the service user holds Hiring access. |
| Mapping | Detail |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Canonical to destination | employee id, hireDate, employmentStatus, jobTitle, plus the Intent ID custom field in postFields |
| Target | POST /v1/webhooks (monitorFields, postFields, frequency, limit) |
| Requirement | Recommended |
| Notes | Monitor hireDate and employmentStatus and include the Intent ID custom field in postFields so every delivery correlates without a follow-up read. Verify the HMAC-SHA256 signature with the webhook's privateKey before processing; poll GET /v1/employees/changed?since= to backfill anything missed. |
Only the tenant can tell us three things. First, the Intent ID custom field: an administrator creates it in Settings before publishing starts, and its numeric field id (custom fields have no alias) is read from GET /v1/meta/fields and fixed in the connector configuration; the field must sit on a tab the service user can edit. Second, the service user itself: API keys carry the permissions of the user who generated them, so provision a dedicated user with employee create and edit, custom report and webhook rights only, and Hiring read access if the linkage to job openings is wanted. Third, how hires arrive: whether the tenant creates employees from Hiring (composerID updates the record BambooHR made) or expects composerID to create them, and whether the plan exposes applicant\_tracking at all. Reverse lookup from Intent ID to employee runs through a custom report, since the API has no server-side filter on custom fields. Webhook signature details and any numeric rate limit are confirmed against the live tenant at onboarding.
## Next steps
The five ways composerID reaches a destination, and the minimum a destination must offer.
Plan, preflight and publish: how a decision becomes a valid record in a destination.
Every destination composerID documents, with its category and coverage status.