This guide walks you through connecting your Zoho People account to Peoplebox, enabling employee data to stay automatically synchronized between the two systems.
1. Overview
The Zoho People integration allows Peoplebox to pull your employee directory directly from Zoho People. Once connected, Peoplebox periodically syncs employee profiles, keeping headcount, reporting structures, departments, and other employee attributes up to date without the need for manual CSV uploads.
The integration reads data from a Zoho People form/view that exposes employee records (the API name is provided during setup, for example, peoplebox_view).
This is a one-directional integration, meaning data flows from Zoho People to Peoplebox only. Peoplebox does not write back to or modify any data in Zoho People.
2. Data synced from Zoho People
Peoplebox syncs the following employee attributes from Zoho People: Employee ID, Full Name, Email, Job Title (Designation), Department, Manager (Reporting Manager), Date of Joining, Date of Exit, Gender, Employment Type, Phone Number (Work Phone), and Location (Work Location). These fields are automatically updated during each sync to help keep employee records in Peoplebox accurate and up to date.
Note: Employees without an email address are not synced, as email is used as the primary identifier for matching employee records between Zoho People and Peoplebox.
3. Prerequisites
Before setting up the Zoho People integration, ensure the following requirements are met:
-
You have admin access to your Zoho People account, which is required to authorize the integration through Zoho's consent screen.
-
You have a Zoho People form/view that contains the employee records to be synced, and you know its API name (for example,
peoplebox_view). -
All active employees have a valid email address populated in Zoho People, as email is used to match employee records during the sync process.
4. How You Connect
Zoho People uses OAuth 2.0 for authentication. The integration is configured by the Peoplebox team on the backend, and there is currently no self-serve setup available within the app. Authorization is granted to Peoplebox's registered Zoho application, allowing Peoplebox to securely access employee data and automatically refresh authentication tokens for ongoing syncs.
The setup process is as follows:
-
The Peoplebox team shares a Zoho authorization link with you.
-
You log in to Zoho People using an administrator account and approve the requested access.
-
Zoho redirects the authorization back to Peoplebox, where the connection is securely established.
-
The Peoplebox team configures the Zoho form/view to be used for syncing employee data and sets up the required field mappings.
-
An initial employee sync is performed, after which the account is included in the regular scheduled sync process.
Note: Once the integration is connected, no further action is required from your side. Peoplebox automatically manages token refreshes and continues syncing data on a scheduled basis.
5. What You Provide
Since the integration setup is handled by the Peoplebox team, only a few details are required from your side:
-
Zoho admin approval: Approve the Zoho authorization link shared by the Peoplebox team. This grants Peoplebox read access to employee data using the required permissions.
-
Form/View API name: Share the API name of the Zoho People form or view that contains the employee records to be synced (for example,
peoplebox_view).
Note: You do not need to generate or share any access tokens manually. The required tokens are securely generated when the authorization request is approved.
6. How Sync Works
-
Sync Frequency: Employee data is synced automatically once daily (around 00:30 UTC) for all active and trial accounts.
-
Directory Coverage: Employee records are fetched in batches to ensure the complete directory is synced, including support for large organizations.
-
Employee Matching: Employees are matched using their email address or employee ID.
-
New Employees: Employees found in Zoho People but not in Peoplebox are automatically added during the next sync.
-
Employee Updates: Changes made in Zoho People, such as updates to job title, department, manager, or phone number, are reflected in Peoplebox after the next sync.
-
Department Sync: Departments are automatically matched or created based on the department values received from Zoho People.
-
Employee Exits: If an employee previously synced from Zoho People is no longer present in the latest Zoho data, Peoplebox marks the employee with an exit date and deactivates the profile to keep active headcount accurate.
-
Audit Logs: Each sync is logged for auditing purposes, including a snapshot of the imported data and a summary of records that were added, updated, or failed during the sync process.
7. Frequently Asked Questions
-
Will existing employees in Peoplebox be affected?
Ans: The sync updates employee records that match by email address or employee ID. New employees found in Zoho People are added automatically, while existing employee records are updated with the latest information from Zoho People. -
What happens if an employee does not have an email address in Zoho People?
Ans: Employees without an email address are skipped during the sync process. To ensure all employees are synced correctly, make sure every active employee has a valid email address in Zoho People. -
Does Peoplebox write any data back to Zoho People?
Ans: No. The integration is read-only from Zoho People's perspective. Data flows only from Zoho People to Peoplebox. -
Do I need to re-authorize the integration periodically?
Ans: No. Peoplebox automatically refreshes access tokens as needed. Re-authorization is only required if the authorization is revoked or expires on the Zoho People side. -
Can I trigger a manual sync?
Ans: Yes. If you need a sync outside the regular schedule, please contact Peoplebox Support. -
Is our Zoho People data secure?
Ans: Yes. Connection credentials are stored securely, and authentication tokens are managed automatically as part of the integration process. -
What happens if the integration authorization is revoked or expires?
Ans: If the integration authorization is revoked, expired, or otherwise becomes invalid, please contact your Peoplebox account manager or Peoplebox Support to re-authorize the connection. Syncing will resume once the connection has been re-established.