BambooHR (platform)
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.
The public API facts composerID's adapter relies on. Tenant-specific details (custom fields, picklists, approval chains) are confirmed during connection and folded into the MappingProfile.
| 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. |
|---|---|
| API 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 |
| 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) |
| Events / 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. |
| 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. |
“Docs confidence” describes how deterministic our mapping templates can be before we connect to a tenant. Even with public docs, implementations vary, especially around custom fields, approval flows and object extensions.
Deterministic mapping
Common Workforce Model fields map to known API fields. Best for standard objects (requisitions, assignments, timesheets, POs).
Tenant discovery
composerID can scan tenant configuration (custom fields, picklists, required fields) where the platform permits it, then generate a tenant‑specific MappingProfile.
Enrichment loop
If the target platform requires a field the Intent record doesn't yet have, composerID emits an enrichment_request back to the intake layer.
An opinionated baseline. The platform adapter enforces additional requirements via preflight. “Tenant required” fields are discovered during connection and added to the MappingProfile.
| Object | Canonical fields | Platform target | Required status | Notes |
|---|---|---|---|---|
| Employee (new hire) Create or update the hired worker record |
role_title (jobTitle), department, division, location, start_date (hireDate), employment_status | POST /v1/employees/ (create; id returned in the Location header) or POST /v1/employees/{id} (update), then rows on the jobInfo and employmentStatus tables | Required | 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 |
intent_id -> employee custom text field (tenant-created in Settings; numeric id from GET /v1/meta/fields, custom fields carry no alias) | 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 | Required | 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 |
job_opening_id, title, department, location, status | GET /v1/applicant_tracking/jobs (statusGroups filter), GET /v1/applicant_tracking/applications | Read scope only | 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 |
employee id, hireDate, employmentStatus, jobTitle, plus the Intent ID custom field in postFields | POST /v1/webhooks (monitorFields, postFields, frequency, limit) | Recommended | 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. |
Idempotency & drift: publish + reconcileExpand
Publish operations are idempotent using a deterministic key {intent_id}-{intent_version}-{target_system}. Because humans can change records inside the platform, composerID supports reconciliation: it compares the platform record snapshot to the canonical intent and flags drift.
Real deployments rely on program-specific custom fields (for compliance, approvals, GL coding, rate rules or supplier constraints). composerID is designed to generate tenant‑specific mappings rather than forcing you to redesign your intake.
How scanning works
High-level flow
What gets produced
Portable artefacts
Important: where this platform is tenant-definedExpand
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.
Use this page alongside the API + Schemas docs to implement: destination connection, preflight validation, publish, webhook back-sync and reconciliation.