ChartPull reads your company directory from Google Workspace to build your org chart. Here is exactly what it reads, how the sync works, and how to manage it.
Admin account required
To connect ChartPull to your Google Workspace, you must sign in with a Google Workspace admin account (someone with super admin or user management privileges in your Google Admin console). Personal Gmail accounts (like yourname@gmail.com) will not work because they do not have access to a company directory.ChartPull requests a single, read-only OAuth scope from Google: admin.directory.user.readonly
This scope allows ChartPull to read — but never write to or modify — your Google Workspace user directory. Specifically, ChartPull reads the following fields for each user:
Read-only means read-only
ChartPull cannot modify, delete, or add users in your Google Workspace. It cannot read emails, calendar events, Drive files, or anything outside the user directory. The scope is classified as “sensitive” (not “restricted”) by Google, which means it has been reviewed and approved through Google’s OAuth verification process.Sign in with your admin account
Visit chartpull.com and click "Get started free." Choose your Google Workspace admin account (e.g. admin@yourcompany.com). If you are not a Google Workspace admin, ask your IT team to do this step.
Authorise directory access
Google will show a consent screen listing the permission ChartPull is requesting: "View users in your organisation." Click "Allow." This is the only permission ChartPull needs.
Wait for the initial sync
ChartPull immediately begins pulling your employee data. For a company with 1,000 employees, this takes about 30-60 seconds. You will see a progress indicator. For very large organisations (5,000+), it may take up to 2 minutes.
Verify your org chart
Once the sync completes, your org chart appears. Spot-check a few people to make sure their titles, departments, and managers look correct. If something is wrong, the issue is in your Google Workspace directory, not ChartPull.
When you authorise ChartPull, Google issues an OAuth refresh token that ChartPull stores to keep your data in sync. This token is encrypted at rest using AES-256 encryption before being written to the database. Only ChartPull’s server-side code can decrypt it — the token is never exposed to the browser or included in API responses.
Token health monitoring
ChartPull runs a 12-hour token validation cron that checks the health of every stored Google connection. Each connection is classified as one of three states:You can add multiple Google Workspace connections for redundancy. If one connection’s token becomes invalid, ChartPull will continue syncing through the remaining healthy connections while notifying you to fix the broken one.
After the initial full sync, ChartPull automatically re-syncs your directory data every 6 hours. When someone joins, leaves, or changes roles in your Google Workspace, ChartPull will pick up those changes on the next sync cycle.
The 6-hour re-sync runs in the background with no action required from you. Employee data is also cached for 15 minutes in ChartPull, so the chart you see is always based on data that is at most 15 minutes old from the last sync.
Manual employees are not affected by sync. If you have added employees manually (not from Google Workspace), those records are preserved exactly as-is during every sync cycle. The sync only updates employees that originated from Google.
The accuracy of your org chart depends entirely on the quality of your Google Workspace directory data. Here are the most common issues and how to fix them.
If an employee does not have a manager set in Google Workspace, they will appear as a “floating” node at the top level of the org chart. To fix this, go to Google Admin Console > Directory > Users, find the employee, and set their manager field.
If you want to disconnect ChartPull from your Google Workspace, you can do so from two places:
Data retention after disconnection
When you disconnect, ChartPull deletes the cached employee data within 24 hours. Your account settings, user roles, and billing configuration are retained so you can reconnect later without starting over.