Getting started
Before you start, explore the Time off API to see how Bob models time off, sites, and calendars.
The Calendar events API exposes read-only company calendar data so integrations (for example Google Calendar or Outlook) can align external systems with Bob instead of maintaining duplicate holiday and closure lists.
Use these endpoints together:
- Search employee calendars — bulk-resolve which holiday calendar applies to each employee (employment override vs site default).
- Search calendar events — read company holidays and closures for a date range, optionally filtered by site or calendar.
Required permissions
The authenticated service user must be allowed to read company calendar configuration and related time off settings. Grant the following in Bob (paths reflect the admin permission UI):
| Data type / method | Permission | Comment |
|---|---|---|
| Search calendar events | Settings > Calendar > Manage company calendar Scope: | If missing, the API returns 403 Forbidden with an explanation. |
| Search employee calendars | Settings > Calendar > Manage company calendar Scopes: | The extra employee_data:read scope is required because this operation reads employee data (the resolved holiday calendar per employee). If missing, the API returns 403 Forbidden. |
To learn more about setting permissions for service users, see API Service Users.
Rate limiting
Rate limits restrict how often your integration can call Bob's APIs within a time window. For background and headers, see Rate limiting.
| Method | Endpoint | Limit per minute |
|---|---|---|
| POST | Search calendar events | 100 |
| POST | Search employee calendars | 100 |
The limit applies per company (not per user). If you exceed it, responses use 429 Too Many Requests; back off using the rate-limit headers described in the rate limiting guide.
Calendar events endpoints
| Resource | Endpoint |
|---|---|
| Search calendar events | Search calendar events |
| Search employee calendars | Search employee calendars |