Generate an API key in BambooHR under your account profile > API Keys; authenticate using HTTP Basic auth with the API key as the username and any non-empty string as the password.
Base URL follows the pattern https://api.bamboohr.com/api/gateway.php/{companyDomain}/v1/ — replace {companyDomain} with your BambooHR subdomain (not the full URL).
GET /employees/directory to retrieve a summary list of all active employees; the response is XML by default — add header 'Accept: application/json' to receive JSON.
To get full employee fields, GET /employees/{id}?fields=firstName,lastName,workEmail,department,jobTitle — specify fields explicitly as the wildcard 'fields=all' can return large payloads and is rate-limited more aggressively.
Retrieve time-off requests by GETting /time_off/requests?start={YYYY-MM-DD}&end={YYYY-MM-DD}&type=timeOff&status=approved; filter by employee using the 'employeeId' query parameter.
For time-off balances, GET /employees/{id}/time_off/calculator?end={YYYY-MM-DD} which returns accrued and used balances per policy.
Known gotchas
The directory endpoint respects BambooHR's field-level permissions; API keys inherit the permissions of the user who created them — if fields appear missing, the generating user likely lacks access to those fields.
Dates must be in YYYY-MM-DD format throughout; BambooHR silently ignores malformed dates on some endpoints rather than returning an error, causing empty result sets.
BambooHR rate-limits at roughly 100 requests per minute per company; the limit applies company-wide across all API keys, so multiple integrations share the quota.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp