Direct Connections
Direct Connections
Four platforms can be linked to your organization over their API. Importing straight from a linked platform is not available yet: to bring your data across today, export a file from the platform and upload it. Each of these platforms has built-in templates, so the columns map themselves.
| Platform | How you connect |
|---|---|
| BambooHR | API key + your BambooHR subdomain |
| Timetastic | API key |
| Employment Hero (Humi) | API key |
| Zoho People | Sign in with Zoho (OAuth) |
Everything else imports from a file — see Supported Platforms.
Connecting a platform
Go to Settings → Data Import. Under Connect directly, click the platform you want. Only Administrators and Executives can do this.
Credentials are validated the moment you submit them: BookYourPTO calls the platform's API with what you entered and refuses to save a key that doesn't work, so a typo fails immediately rather than at import time. Each platform can be connected once per organization; reconnecting replaces the stored credentials.
BambooHR
You need an API key and your subdomain.
- In BambooHR, open your profile menu and go to API Keys.
- Generate a new key and copy it.
- Your subdomain is the first part of your BambooHR web address — for
acme.bamboohr.com, it'sacme. - In BookYourPTO, click BambooHR, enter the subdomain and paste the key, then Connect & Test.
The test call reads your employee directory, so it also tells you the company name and how many employees it can see.
BambooHR supplies names, work and home email, job title, department, division, location, supervisor, hire and termination dates, employment status, phone numbers and extension, date of birth, gender, marital status, full address, and employee number. Time-off requests come across with type, dates, amount, status and the employee's note.
Timetastic
- In Timetastic, go to Settings → Integrations → API.
- Copy your API key.
- In BookYourPTO, click Timetastic, paste the key, then Connect & Test.
Timetastic supplies name, email, department, start date and annual allowance for each user, plus their holiday bookings with leave type, dates, duration and status.
Employment Hero (Humi)
- Get an API key from Settings → Integrations in Humi, or ask Humi support for API access.
- In BookYourPTO, click Employment Hero (Humi), paste the key, then Connect & Test.
Humi supplies names, work and personal email, job title, department, office, manager email, hire and termination dates, employment type, phone numbers, date of birth, gender, address, province and postal code, and employee number — plus time-off requests with policy name, dates, days, status and notes.
Zoho People
Zoho uses OAuth, so there's no key to copy.
- In BookYourPTO, click Zoho People.
- You're redirected to Zoho to sign in and approve access.
- Approve, and you're returned to the Data Import page with the connection listed.
Zoho People supplies first and last name, nickname, primary and other email, designation, department, location, reporting manager, date of joining and exit, employee type, mobile and work phone with extension, date of birth, gender, marital status, present address, city, state, zip, country and employee ID — plus leave records with type, from and to dates, day count, approval status and reason.
BookYourPTO refreshes the Zoho access token by itself, so the connection keeps working without you signing in again. If it ever expires for good, the connection shows the error and you can reconnect with one click.
Importing from a connection
A connected platform appears at the top of the Data Import page with a green dot. There is no Import now button yet: importing straight from a connected platform is not available, and the page says so on the connection's row.
To import, export the data from the platform and upload the file:
- Export your employee list (and, separately, your time-off report) from the platform.
- On the Data Import page, choose Upload a file and start an import.
- The platform's built-in template maps the columns. Import employees first, then leave history.
See Importing a File.
Disconnecting
Click the unplug icon next to a connection to remove it. This deletes the stored credentials. Data you have already imported stays where it is — disconnecting does not remove any employees or leave records.
When connecting fails
Credentials are tested when you connect, and a failed test shows the platform's reason.
| Message | What it usually means |
|---|---|
API returned 401 / 403 | The key was revoked or lacks permission — regenerate it and reconnect |
API returned 404 | Wrong BambooHR subdomain |
Connection failed / timeout | The platform's API didn't respond in time; try again shortly |
No refresh token. Please reconnect Zoho People. | The Zoho authorization was withdrawn — reconnect |
If a connection can't be made to work, the file route always remains available.
Supported Platforms
The 48 HR, payroll, and time-off platforms whose export layouts BookYourPTO recognizes automatically, plus what to do when your platform isn't listed.
Custom Templates
Save your own column mapping as a named, reusable template, and manage the built-in and custom templates available to your organization.