Google Contacts Sync
Google Contacts sync keeps your customers in ContractorScope AI and your Google Contacts (the address book on your phone and in Gmail) in step with each other. Add a customer or change a name, phone number, or email in ContractorScope AI and it shows up in Google; edit a synced customer in Google and the change comes back. Usually within the hour.
What Syncs
- Name, phone number, and email of each customer.
- Customers that are not archived and have a phone number or an email are copied to Google Contacts and placed in a Google label called ContractorScope AI.
- Your ContractorScope AI contacts are copied into the ContractorScope AI label in Google Contacts and kept in step both ways every hour: a change to a synced customer in Google also reaches ContractorScope AI. Contacts that exist only in Google are never added to ContractorScope AI, even if you add them to the label. If you later add a customer with the same phone number or email, the two are linked and stay in step.
- Sync runs every hour. You can also run it yourself with Sync now.
What Never Happens
- Deletes never cross. Deleting a contact in Google does not delete the customer in ContractorScope AI, and deleting a customer in the app never deletes the Google contact. A customer you archive simply leaves the label and comes back when you unarchive it.
- Nothing is removed from a Google phone or email list. New numbers and emails are added next to the old ones; existing ones are never removed or reordered.
- A contact you deleted in Google, or took out of the label, is not brought back or re-added automatically. Admins can bring one back from Unlinked contacts on the Google Contacts card: click Re-link next to the contact and it syncs again on the next run.
- Google edits that reach a customer in ContractorScope AI can flow on to QuickBooks through your normal QuickBooks sync, the same as any other edit to that customer.
Who Can Do What
| Company admin | Other team members | |
|---|---|---|
| See the connection, last run, and counts | Yes | Yes |
| See conflict details (names, numbers, emails) | Yes | No, only how many conflicts there are |
| Connect, preview, turn on sync, Sync now, disconnect | Yes | No |
Connect Your Google Account
- Click Settings in the left sidebar and select Integrations.
- Open Google Contacts and click Connect Google Contacts.
- Sign in to the Google account whose contacts you want to sync and allow access.
You can connect one Google account per company. To use a different one, disconnect the first.
Use the Google account your team already uses for the business. If its email domain is different from your company owner's, ContractorScope AI shows a warning and asks you to type the account's email to confirm before sync is turned on.
Review the Preview First
Right after you connect, nothing is written to Google or to ContractorScope AI. The card shows a preview of what the first sync would do.
The preview takes about a minute to prepare. Until it is ready the card says Preparing your preview and refreshes by itself, and Turn on sync stays off. If an attempt does not finish, the card says why and whether it is being retried (see If Something Looks Off below), and keeps checking. If the preview is taking longer than usual, the card says that instead. Either way it shows a Refresh button; click it to check again now, and if the preview is still missing it starts preparing it again.
If your Google account is very large, the preview is prepared in several steps. When a run reaches its time limit it keeps what it read, and the next run continues where it left off; the card says so, and Refresh continues it right away. Nothing is added to Google or to ContractorScope AI while this happens.
The preview is rebuilt every hour until you turn sync on. If a later attempt does not finish, the card keeps showing the earlier preview, says why the newer one was not refreshed, and says that the preview below is from an earlier run. You can still turn sync on from it; the first sync reads Google fresh. A contact added, or whose phone or email changed, while a large preview is being built may show as Will be created in Google even though it matches an existing Google contact; the first sync after you turn it on links it if it matches.
| Preview line | What it means |
|---|---|
| Will link to existing Google contacts | A customer and a Google contact already match (same phone or email). |
| Will be created in Google | A customer with no match yet. |
| Values that differ | The two sides disagree on a name, phone, or email. Each customer shows the field side by side, In ContractorScope AI and In Google, so you can see exactly what differs. Click Keep ContractorScope AI's or Keep Google's for each one, or use Keep ContractorScope AI's for all / Keep Google's for all. |
| Match several Google contacts | One customer matches more than one Google contact. Each possible match is listed with its name, phone, and email so you can tell which is the right one. Pick it with Use this match. |
Your choices are saved now and applied on the first sync after you turn sync on: the value you keep is written to the other side (ContractorScope AI's goes to Google, Google's goes into ContractorScope AI). Nothing changes until then, and if either value changes before then, your choice is dropped and neither side is changed. When the preview looks right, click Turn on sync.
After Sync Is On
The card shows when the last run happened and how many contacts were linked, created in Google, sent to Google, brought in from Google (edits to contacts that are already linked), skipped, and how many Google-only contacts were left out. Click Sync now to queue a run right away; the numbers update when it finishes. The counts show only what a run actually saved: if a run stopped early, the card shows what it finished, not what it was about to do.
Conflicts
If the same field changes on both sides between two runs, nothing is lost:
- Name: the ContractorScope AI name is kept.
- Phone or email: both values are kept.
Admins can see the recent conflicts, with both values, on the card. If a change made in Google could not be applied in ContractorScope AI (for example, Google holds something that is not a valid phone number), it is listed as a conflict that kept the ContractorScope AI value, and sync stops retrying it.
If Something Looks Off
When a run does not finish, the card says why, in one of three ways:
- "...We are retrying automatically." A temporary problem: Google did not answer in time or was too busy, ContractorScope AI could not check your Google sign-in just now, or something went wrong on our side. It is retried by itself: the next attempt is usually within a few minutes, and if those attempts fail, the next hourly sync tries again. You do not need to do anything. If the message is still showing after a few hours, contact support.
- "The last run could not finish: ..." or "The preview could not be prepared: ..." Trying again will not fix this, and the card says what to do. If it says your Google sign-in has expired or was rejected, or that Google did not allow access to your contacts, click Reconnect Google Contacts and allow access to your contacts when Google asks; if reconnecting does not help, contact support. If it says Google is not allowing access to the account (access blocked), or that Google refused the request (with an error number), contact support and tell them what the card says. For access blocked, sync is not paused and you do not need to reconnect: it keeps trying every hour and starts working again by itself once the cause is fixed. If it says the run ran out of time before it could finish, that usually means a very large Google account, though a slow response from Google can cause it too: the next hourly run tries again, and if it keeps happening, contact support.
- "Your Google account is large, so the last run stopped early." The run reached its time limit after saving some of its work. What it finished is kept, and the next hourly run continues where it left off. You do not need to do anything. While the first preview is being prepared the card says "the preview is being prepared in several steps" instead, and a preview that is being rebuilt says "a newer preview is being prepared in several steps" and keeps showing the earlier one.
- "The preview could not be refreshed" or "The preview was not refreshed because ...". An earlier preview is on screen and a later attempt to rebuild it did not finish. It reads like the messages above and offers Reconnect Google Contacts when that is the fix; the preview below it is from an earlier run and may be out of date.
- Paused: reconnect needed. Sync is paused because it cannot work until you reconnect, so it stops trying. The card says why: Google no longer accepts the saved sign-in (for example, someone disconnected Calendar or Gmail for the same Google account), Google rejected the saved sign-in on two runs in a row, or Google did not allow access to your contacts when you connected (the Google permission screen lets you untick it). Click Reconnect Google Contacts and allow access to your contacts when Google asks; sync resumes where it left off, as a preview if it was still in preview and with sync on if it was on.
- Waiting for Google to catch up. Google can take several minutes to show a contact that was just created. Sync waits instead of creating it twice.
- Sync held back some removals. A very large number of contacts disappeared at once, either from Google or from ContractorScope AI. That usually means a read came back incomplete rather than that you deleted them, so nothing is unlinked that run. The card shows a warning and it is checked again on the next run.
- Match several Google contacts. Two or more customers or Google contacts share the same phone or email, so ContractorScope AI will not guess. Pick the right match in the preview, or tidy the duplicates in Google.
Disconnect
Click Disconnect on the Google Contacts card and confirm. This stops syncing and removes the connection and the sync records ContractorScope AI kept. Your customers stay as they are in ContractorScope AI, and your Google contacts stay as they are in Google.
Disconnecting does not cancel the permission you gave Google, because that permission is shared with your other Google connections (such as Calendar). To remove it completely, go to myaccount.google.com/permissions and remove ContractorScope AI. That also disconnects Calendar and any other Google connection for that account.
Deleting the admin user who connected Google Contacts also removes the Google permission for that Google account. Calendar (and any other Google connection) on that same account stops working until it is reconnected.