BambooHR

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

BambooHR API documentation (guides)

BambooHR API reference (endpoints)

Webhooks guide

List of field names

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
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.

Employee (new hire)

Create or update the hired worker record

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.

Intent ID correlation

Carry the Intent ID

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.

Job Opening (Hiring)

Link the open role

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.

Employee field webhook

Close the loop on the hire

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

How composerID connects

The five ways composerID reaches a destination, and the minimum a destination must offer.

Publishing

Plan, preflight and publish: how a decision becomes a valid record in a destination.

All destinations

Every destination composerID documents, with its category and coverage status.

⌘I

Get started

Concepts

Guides

Destinations

Upstream connectors

API reference

Endpoints

Manuscript API (Triage)

Manuscript endpoints

Resources

Integration path

Vendor documentation

BambooHR API documentation (guides)

BambooHR API reference (endpoints)

Webhooks guide

List of field names

API posture

Publish target and field mapping

Next steps

How composerID connects

Publishing

All destinations

​Integration path

​Vendor documentation

BambooHR API documentation (guides)

BambooHR API reference (endpoints)

Webhooks guide

List of field names

​API posture

​Publish target and field mapping

​Next steps

How composerID connects

Publishing

All destinations

Integration path

Vendor documentation

API posture

Publish target and field mapping

Next steps