Zoho Books and BambooHR integration

What moves between them

Employee data flows from BambooHR into Zoho Books. When a BambooHR webhook fires for employee.created, employee.updated, or employee.deleted, ml-connector pulls the full employee record from BambooHR and upserts it as a contact in Zoho Books under the same email address. Employment status changes (active, terminated, inactive) update the contact record so expense allocation and project tracking reflect the current workforce. Reference data such as department and job title sync bidirectionally so both systems name roles consistently. The sync runs in near real-time triggered by BambooHR webhooks plus a periodic reconciliation check to catch any missed events.

How ml-connector handles it

ml-connector stores both credential sets encrypted and routes Zoho Books calls to the correct regional base URL determined by the OAuth region credential. For each incoming BambooHR webhook, ml-connector verifies the SHA-256 HMAC signature against the webhook secret, fetches the full employee record from BambooHR's /employees endpoint using the per-subdomain OAuth token, and upserts the contact into Zoho Books with organization_id as a required query parameter. Email addresses are used as the matching key since both systems expose them. Employment status in BambooHR (active, terminated, inactive) maps to a contact status field in Zoho Books. BambooHR tokens refresh automatically when they near the 1-hour expiry. Since BambooHR webhooks send lightweight payloads, ml-connector always fetches the full employee record to ensure all fields are current. Zoho Books has no built-in idempotency key support, so ml-connector deduplicates using BullMQ jobId. Webhook history is kept in the audit trail for replay if a downstream call fails.

A real-world example

A mid-sized professional services firm uses Zoho Books for invoicing and expense management and BambooHR for time-off, benefits, and payroll. Before the integration, when a new consultant was hired, the admin had to manually add them as a contact in Zoho Books and assign them a cost code for expense tracking. When a consultant left, the contact record lingered or had to be manually deactivated. With BambooHR and Zoho Books connected, each hire in BambooHR automatically creates a contact in Zoho Books ready for expense allocation. Terminations update the status so expense reports and cost accounting reflect only active staff. The manual contact-keeping task is eliminated.

What you can do

• •Sync employee records from BambooHR into Zoho Books contacts whenever employees are created, updated, or terminated.
• •Use employment status from BambooHR to set contact status in Zoho Books so expense allocation only includes active staff.
• •Map employee email, name, job title, and department across both systems for consistent people data.
• •Verify webhook signatures with SHA-256 HMAC and fetch full employee details for each webhook event.
• •Handle regional Zoho Books base URLs and per-subdomain BambooHR OAuth tokens, with automatic token refresh and a full audit trail on every sync.

Questions

Which direction does employee data flow between Zoho Books and BambooHR?

Data flows from BambooHR into Zoho Books. Employee records are synced as contacts in Zoho Books so they are available for expense allocation and project tracking. Reference data such as department and job title sync bidirectionally to keep both systems consistent. Zoho Books has no people-management capabilities, so there is no reverse sync of contacts back to BambooHR.

What employee fields are synced and how is employment status handled?

ml-connector syncs email, first name, last name, job title, and department from BambooHR to Zoho Books. Employment status in BambooHR (active, terminated, inactive) maps to a contact status field in Zoho Books so terminated employees are marked inactive and do not receive new expense allocations. When employment status changes, ml-connector updates the Zoho Books contact immediately.

How does the integration handle Zoho Books regional URLs and BambooHR's per-subdomain authentication?

Each Zoho Books organization specifies its region (US, EU, India, Australia, Japan, Canada, China, Saudi Arabia), and ml-connector routes all calls to the correct regional base URL. BambooHR uses per-customer subdomains in both the API endpoint and the OAuth token URL, so ml-connector accepts both the subdomain and OAuth credentials and directs all requests to the right customer instance. Token refresh is automatic when tokens approach their 1-hour expiry.