Synchronize selected Google Contacts into IllyVoIP

A custom backend can read selected Google Contacts with the People API and upsert the intended records into IllyVoIP. Treat this as a controlled one-way integration unless you deliberately implement conflict resolution. It is not an automatic native Google Contacts connection in the Portal.

1. Authorise the intended Google account

Configure your Google Cloud project and OAuth consent for the People API. Request the minimum read access needed, normally the Google contacts.readonly OAuth scope for this read-only source workflow. Follow Google’s current verification and token requirements for your app’s users. Store refresh/access tokens and the IllyVoIP API key on the backend, scoped to the correct customer.

Decide which contacts are eligible and which system owns each field. Do not run a competing writer over contacts already managed by another CRM without a policy. Prepare a dry-run report before any write, including the intended name, selected number, matching identity and fields that would change.

2. Read a complete baseline

Use GET /v1/people/me/connections on the HTTPS host people.googleapis.com with the authorised bearer token. Request only the required personFields, such as names, phoneNumbers, emailAddresses and metadata. Set requestSyncToken=true for the initial sync and use a deliberate supported page size.

1. Process the returned connections and follow every nextPageToken.
2. Keep the same relevant request parameters while paging; do not change the field set mid-stream.
3. Select one intended name and telephone number using your documented rule. Skip records requiring review instead of guessing a country code or selecting a random phone field.
4. Commit the new nextSyncToken only after the final page and all corresponding contact work are durably recorded.

3. Map stable identities to IllyVoIP

Use the Google person’s resourceName as part of the stable source identity. Include a durable connection/account identity in your mapping so two Google accounts cannot collide. For example, your chosen external_source can identify the Google connection, while external_id holds the person resource name. Keep the returned IllyVoIP contact ID alongside that mapping.

Names, email addresses and phone numbers can change; they are not reliable replacement keys. If an existing IllyVoIP contact might correspond to the Google person, review the match before attaching the mapping. A substring search result is not proof of unique identity, and a merge must not be guessed from a shared family phone number.

4. Build complete intended contact updates

Read GET /api/v1/contacts/workspace to understand the actual IllyVoIP custom fields, company and sharing choices. Submit contact writes to POST /api/v1/contacts using the private X-Api-Key header. The request includes a name and stable external identity, plus the complete fields your integration intends to preserve.

IllyVoIP upsert is not a generic partial PATCH. Omitted phone, email, company, sharing or custom fields can be cleared or reset. For an existing contact, combine the current record with your field-ownership policy before submitting. Preserve fields owned by Portal users deliberately, and avoid simultaneous writes that can overwrite each other.

For a new contact, the identity portion can look like this; add the reviewed phone/email and required workspace fields before sending:

{
  "external_source": "google_contacts_connection_a",
  "external_id": "people/EXAMPLE_RESOURCE",
  "name": "Example Contact",
  "custom_fields": {}
}

5. Apply incremental changes and explicit deletion policy

Use the saved sync token for later changes, preserving the matching request parameters. Google can return a person whose metadata.deleted is true. Decide whether that should delete a mapped IllyVoIP contact, detach the mapping or create a review item. Never delete a contact shared with another workflow just because one source removed it.

Sync tokens expire after seven days from the full sync. Handle the documented expired-token response by rebuilding a complete baseline; do not interpret it as an empty address book. Do not infer deletion from a partial page, a failed request, a changed selection filter or an incomplete new baseline. Google’s incremental feed also has propagation delay and is not a reliable immediate read-after-write check.

6. Verify the integration before scheduling it

Test duplicate pages, an expired token, a deleted person, a renamed contact, multiple phone fields and an IllyVoIP validation rejection. Resume from durable checkpoints without creating a new external ID. Start with a small authorised contact set, verify saved fields and visibility in the Portal, and retain a private reconciliation report. Importing contact data does not grant permission for subsequent SMS or calls.

Related guides

• Sync CRM contacts into IllyVoIP with the Contacts API
• Organize your contacts
• Organize companies and contact fields

Reference

Current instructions and technical reference: Google People API contact sync, Google contact-list request and sync tokens.

Reviewed 12 October 2026 against the current IllyVoIP controls, implementation and applicable references. Available options depend on account permissions and service state.