.png)
Google Contacts Integration Guide
Integrate Google Contacts with enterprise systems through the Google People REST API, OAuth 2.0, scheduled workflows, pagination, and synchronization tokens.
Google Contacts integration options at a glance
Google Contacts integrations should use the current Google People REST API rather than the deprecated Google Contacts Data API. The API supports JSON operations for listing connections, reading and writing Person resources, managing contact groups, accessing other contacts, and handling contact photos. Martini can consume these endpoints with OAuth 2.0, paginate through results, use HTTP batching where appropriate, and persist synchronization tokens for incremental scheduled synchronization. Because no general Google People webhook mechanism is confirmed, recurring integrations should use scheduler-triggered workflows. Martini can also expose a controlled API for lookups or downstream applications.
| Integration point | Supported by Google Contacts? | Common use cases | How Martini supports it |
|---|---|---|---|
| Google People REST API | Yes | Read connections, create and update contacts, manage contact groups, list other contacts, access directory people, and retrieve or update contact photos. | Martini can consume JSON REST endpoints, map responses, apply business rules, and expose reusable APIs or workflows around the People API. |
| Authentication | Yes | OAuth 2.0 scopes authorize read-only, writable contacts, other-contact, or directory access. API keys may support project identification and quota management but do not authorize private contact data. | Martini can store client credentials and refresh tokens in secrets or environment configuration and use OAuth-protected API requests. |
| Incremental synchronization | Yes | Connections list operations can return synchronization tokens so later runs request changes instead of repeating a full synchronization. | Martini can persist a token after successful processing, resume from it, and trigger a full resynchronization when Google invalidates or expires it. |
| Pagination | Yes | People API list operations use page tokens to retrieve complete result sets. | Martini workflows can loop through pages, transform each response, and distinguish page-token state from synchronization-token state. |
| HTTP batch requests | Limited | Google APIs support grouping multiple HTTP requests, but People API does not provide a separate bulk contact-import model. | Martini can implement controlled batching where appropriate while retaining throttling, idempotency, and per-request error handling. |
| Contact photo operations | Limited | The People API supports contact-photo retrieval and update operations, but it is not a general-purpose contact attachment repository. | Martini can orchestrate media retrieval and updates separately from JSON field mapping, including content-type and storage handling. |
| Webhooks / outbound callbacks | No | No general Google People API webhook mechanism for contact changes was confirmed; documented synchronization relies on polling and tokens. | Martini can use scheduled workflows or an invoked API rather than assuming real-time Google contact events. |
| GraphQL APIs | No | No Google Contacts or Google People GraphQL endpoint was confirmed. | Martini can consume the confirmed REST API instead; no Google Contacts GraphQL integration should be assumed. |
| SOAP APIs | No | No current Google Contacts SOAP interface was confirmed, and the older Google Contacts Data API is deprecated. | Martini should use the Google People REST API for new implementations. |
How Google Contacts exposes data and business events
Google People REST APIs
The Google People API is the current JSON REST interface for Google Contacts. It provides methods for connections, Person resources, contact groups, other contacts, directory people, and contact photos. New integrations should use this API instead of the deprecated Google Contacts Data API.
Martini implementation pattern
Martini authenticates with OAuth 2.0, invokes the relevant People API endpoint, handles pagination and response validation, maps Person or related resources into a canonical model, and writes the result to a target system or returns it through a Martini API.
Implementation sequence
Synchronization tokens
People API connection listing supports synchronization tokens for incremental synchronization. This allows recurring processes to retrieve changes after an initial full load, subject to token validity and the applicable resource method.
Martini implementation pattern
Martini runs a scheduled workflow, loads the last successful token from a persistence store, retrieves all pages of changes, processes them successfully, and commits the new token only after the target writes complete. An invalid token causes a controlled full synchronization.
Implementation sequence
HTTP batch requests
Google APIs support HTTP batching for grouping multiple HTTP requests. This is request batching rather than a dedicated bulk contact-import resource, so implementations still need individual request semantics and error handling.
Martini implementation pattern
Martini groups suitable API calls into controlled batches, limits concurrency according to quota considerations, evaluates each response, and retries only eligible transient failures. Batching should not bypass idempotency or per-record validation.
Implementation sequence
Contact photo operations
The People API provides operations for retrieving and updating contact photos. Photos are media resources and should not be treated as ordinary scalar Person fields or as a general attachment repository.
Martini implementation pattern
Martini orchestrates photo retrieval or update as a separate branch, validates authorization and media requirements, optionally stores or forwards the content, and records the association with the Person resource.
Implementation sequence
Common Google Contacts integration patterns
Pattern 1: Synchronize Google Contacts to Salesforce
When to use this pattern
Use this pattern when personal Google contacts need to be published to Salesforce Contacts or Leads. An initial full load can establish mappings, followed by incremental synchronization using Google synchronization tokens. Because a Person is not a one-to-one match for a Salesforce record, matching and ownership rules are required.
Integration direction
Example Mapping
| Google Contacts Field | Canonical Field | Target Field |
|---|---|---|
| resourceName | sourceContactId | External Contact ID |
| names[0].displayName | fullName | Name |
| emailAddresses[0].value | primaryEmail | |
| phoneNumbers[0].value | primaryPhone | Phone |
Martini implementation pattern
A scheduled Martini workflow retrieves paginated Person resources, applies field selection and normalization, matches by stored resource name or carefully controlled email and phone rules, and upserts Salesforce data. It commits the synchronization token only after successful processing and routes quota, authorization, conflict, and transient failures through retry or reconciliation handling.
Martini capabilities used
- scheduled workflows
- API consumption
- data mapping
- business rules
- idempotency
- error handling
Pattern 2: Publish CRM contacts to Google Contacts
When to use this pattern
Use this pattern when Salesforce or HubSpot remains the source of truth and selected contacts must be created or updated in Google Contacts. The workflow should normalize contact values, preserve source identifiers, and use a writable contacts scope.
Integration direction
Example Mapping
| Google Contacts Field | Canonical Field | Target Field |
|---|---|---|
| Contact.Id | sourceContactId | external mapping/resourceName |
| Contact.FirstName and LastName | name | names |
| Contact.Email | primaryEmail | emailAddresses |
| Contact.Phone | primaryPhone | phoneNumbers |
Martini implementation pattern
Martini consumes the CRM API, validates required fields, transforms the source object into the Google Person structure, and chooses create or update using an integration mapping table. Update masks limit changes to intended fields so unrelated Google data is not overwritten; transient failures are retried and duplicate candidates are quarantined for review.
Martini capabilities used
- API consumption
- data mapping
- transformations
- business rules
- secrets management
- retry handling
Pattern 3: Synchronize Google Workspace directory people
When to use this pattern
Use this pattern when approved employee information from Google Workspace directory resources must be published to ServiceNow, Slack, or an internal directory. Directory people must remain distinct from personal contacts and require appropriate administrative authorization.
Integration direction
Example Mapping
| Google Contacts Field | Canonical Field | Target Field |
|---|---|---|
| Directory person.name | employeeName | Display name |
| Directory person.emailAddresses | workEmail | |
| Directory person.organizations | organization | Department or company |
| Directory person.resourceName | directoryPersonId | External ID |
Martini implementation pattern
A scheduled Martini workflow reads permitted directory data, filters fields according to organizational policy, maps the result to the target API, and applies change detection using directory resource identifiers. It separates authorization failures from transient service errors and records an audit-friendly processing outcome.
Martini capabilities used
- scheduled workflows
- API consumption
- field filtering
- data mapping
- authorization
- monitoring
Pattern 4: Expose a controlled Google contact lookup API
When to use this pattern
Use this pattern when a CRM, support platform, or internal application needs selected Google People data without receiving broad Google access. The calling application supplies a validated email address or phone number, and Martini mediates the lookup and response.
Integration direction
Example Mapping
| Google Contacts Field | Canonical Field | Target Field |
|---|---|---|
| request.email | lookupEmail | People API query criteria |
| request.phone | lookupPhone | People API query criteria |
| Person.names | displayName | API response.name |
| Person.emailAddresses | emailAddresses | API response.emailAddresses |
Martini implementation pattern
Martini exposes an authenticated API, validates and normalizes the lookup input, calls Google People API with minimum required fields, applies authorization and data-minimization rules, and returns a controlled response. Errors such as missing access, no match, quota exhaustion, and transient Google failures receive distinct outcomes.
Martini capabilities used
- API exposure
- API consumption
- validation
- data minimization
- business rules
- error handling
Applications commonly integrated with Google Contacts
Google Contacts can be integrated with adjacent business applications when organizations need to synchronize contact details, support coexistence between productivity platforms, or enrich operational workflows. These patterns require explicit field mapping, ownership rules, authorization, and duplicate-prevention logic rather than assuming that Google Person resources map directly to target records.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Synchronize Google contacts with Salesforce Contacts or Leads while reducing duplicate entry and applying controlled matching rules. | Google Contacts → Martini → Salesforce | A scheduled Martini workflow reads paginated Person resources, uses synchronization tokens after the initial load, maps selected names, emails, phones, organizations, and addresses, and upserts Salesforce records using stable identifiers and retry handling. |
| HubSpot | Move selected contact details between Google Contacts and HubSpot for sales and marketing operations. | HubSpot → Martini → Google Contacts | Martini consumes the HubSpot API, normalizes email addresses and phone numbers, transforms the result into the Google People API Person structure, and creates or updates contacts with the required writable OAuth scope. |
| Microsoft Outlook | Support contact coexistence or migration between Google and Microsoft productivity environments. | Google Contacts → Martini → Microsoft Outlook | Martini retrieves Google Person resources, applies an explicit cross-platform field map and ownership policy, then calls the applicable Microsoft API while recording source identifiers to prevent duplicate creation. |
| Microsoft Exchange Online | Synchronize selected contact information for organizations operating Google Workspace and Microsoft 365 together. | Google Contacts → Martini → Microsoft Exchange Online | A scheduled workflow filters approved contact fields, transforms multi-valued Google data into the Microsoft target model, applies privacy rules, and records processing outcomes for retry or reconciliation. |
| Zendesk | Enrich support-user or requester workflows with approved Google contact information. | Google Contacts → Martini → Zendesk | A Martini API accepts a validated email address or phone number, retrieves permitted People data, returns only required fields to Zendesk, and applies authorization, masking, and error handling. |
| ServiceNow | Publish approved employee or customer contact information into ServiceNow records used by service operations. | Google Workspace → Martini → ServiceNow | Martini reads authorized Directory person data or selected Google contact data, maps work identity fields to ServiceNow, applies change detection, and retries transient API failures. |
| Slack | Support collaboration workflows that need selected Google Workspace directory information. | Google Workspace → Martini → Slack | A scheduled Martini workflow reads permitted directory people, filters the minimum required fields, transforms them for Slack APIs, and enforces administrator-approved access and retry policies. |
| NetSuite | Synchronize customer or contact information for sales and account-management processes. | NetSuite → Martini → Google Contacts | Martini consumes NetSuite data, applies matching based on source IDs and normalized contact values, maps the result to Person fields, and performs controlled Google People API writes. |
How to build a Google Contacts integration in Martini
Objective
Establish Google People API access using OAuth 2.0 and keep credentials, refresh tokens, and environment-specific values outside workflow logic.
Instructions in Martini
- Configure the Google OAuth client and redirect or authorization model
- Request only the contacts, other-contacts, or directory scopes required
- Store client credentials and refresh tokens in Martini secrets or environment configuration
- Confirm Google Workspace administrator policies and consent requirements
Objective
Select a schedule or API invocation because a general Google People contact-change webhook was not confirmed.
Instructions in Martini
- Use a scheduler for recurring synchronization
- Use an API trigger for controlled lookup or on-demand processing
- Define the initial full-load and recurring incremental-sync behavior
- Set execution limits appropriate for Google quotas
Objective
Call the Google People REST API and retrieve complete, authorized result sets while maintaining pagination and synchronization state.
Instructions in Martini
- Request the required Person or related resource fields
- Follow page tokens until all pages are processed
- Load and validate the prior synchronization token where applicable
- Keep pagination state separate from synchronization-token state
Objective
Coordinate retrieval, transformation, matching, target writes, state persistence, and failure paths as an explicit Martini workflow.
Instructions in Martini
- Branch for regular contacts, other contacts, directory people, groups, and photos where needed
- Use reusable services or workflow stages for common API and mapping logic
- Commit synchronization state only after successful downstream processing
- Route authorization, validation, quota, and transient failures separately
Objective
Convert Google’s multi-valued Person model into the target application’s schema without losing source identity or overwriting unrelated fields.
Instructions in Martini
- Normalize email addresses and phone numbers
- Map names, organizations, addresses, memberships, and selected metadata
- Use field masks for intended Google updates
- Retain Google resource names and source-system identifiers
Objective
Apply matching, ownership, privacy, and data-minimization rules before writing contact information.
Instructions in Martini
- Do not use display name as the sole matching key
- Define whether Google or the target system owns groups and memberships
- Filter personal data to the minimum required fields
- Quarantine ambiguous duplicate matches for review
Common Google Contacts data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Person | Represents an individual with names, email addresses, phone numbers, organizations, addresses, biographies, birthdays, URLs, memberships, and photos. | Salesforce, HubSpot, Microsoft Outlook, Zendesk, NetSuite | Martini retrieves selected fields, normalizes multi-valued data, maps it to a canonical contact model, and uses resource names or mapping tables for idempotent updates. |
| Contact group | Organizes a user's contacts into managed groups that can be listed, created, updated, or deleted. | Salesforce, HubSpot, internal directories | Martini processes groups separately from Person fields and applies an explicit ownership rule for memberships. |
| Membership | Represents the relationship between a Person and a contact group. | CRM platforms, directory applications | Martini maps group relationships independently, validates referenced resources, and prevents duplicate memberships. |
| Other contact | Represents contact-like information created from interactions or other Google data with more limited operations. | CRM enrichment workflows, reporting stores | Martini requests the appropriate read-only scope, distinguishes this object from regular contacts, and applies separate synchronization rules. |
| Directory person | Represents a person in a Google Workspace organization directory rather than a user's personal contacts. | ServiceNow, Slack, internal directories, service catalogs | Martini uses permitted directory scopes, filters work-related fields, and keeps directory synchronization separate from personal-contact synchronization. |
| Contact photo | Represents photo media associated with a Person resource. | CRM platforms, employee directories, media storage | Martini handles photo retrieval or updates as a separate media flow with content-type, authorization, and storage considerations. |
Authentication and security considerations
OAuth 2.0 authorization
Google People API access is primarily authorized with OAuth 2.0. Use the narrowest practical scopes, such as read-only contacts access for lookups or writable contacts access for create and update operations.
Secrets and administration
Store client credentials, refresh tokens, and environment-specific configuration in Martini secrets or secure environment configuration. Google Workspace administrator policies, consent requirements, and app verification may apply to organization-wide deployments.
Data minimization
- Request only the fields required by the workflow.
- Keep personal contacts, other contacts, directory people, groups, and photos under separate authorization and processing rules.
- Do not assume a service account can access a user's personal contacts without the applicable delegation and policy configuration.
Operational considerations for Google Contacts integrations
Quotas and pagination
Google APIs enforce project and user quotas. Follow page tokens, avoid unbounded parallel writes, and use controlled batching where appropriate. Handle 429 responses with throttling and backoff.
Synchronization state
Persist synchronization tokens only after all returned changes have been processed successfully. Keep them separate from page tokens and fall back to a full synchronization when Google invalidates or expires a token.
Mapping and updates
Person resources can contain missing fields and multiple values. Use field selection, explicit update masks, stable resource identifiers, and rules for group ownership. Treat contact photos as separate media processing.
Errors and testing
- Distinguish 401 and 403 authorization failures from 404 access or resource problems.
- Retry eligible 429 and 5xx responses with bounded backoff.
- Handle 409 conflicts and invalid synchronization tokens explicitly.
- Test full loads, incremental changes, duplicate candidates, missing fields, token recovery, and partial target failures.
Why use Martini instead of scripts or point-to-point integrations?
Orchestration instead of isolated scripts
Martini provides a maintainable workflow for OAuth-protected API calls, pagination, synchronization state, transformations, business rules, target writes, and error paths. The integration can be reused through APIs and workflow components rather than embedded in one-off scripts.
Controlled data movement
Martini can apply field selection, validation, data minimization, matching rules, and update masks before data reaches a target system. This is important because Google Person resources are multi-valued and do not map directly to every enterprise contact model.
Operational reliability
Scheduled execution, bounded retries, token checkpoints, monitoring, and explicit handling of authorization and quota failures provide a stronger operational model than unmanaged point-to-point code.
Frequently asked questions
New integrations should use the Google People REST API with OAuth 2.0. Enterprise workflows commonly use paginated reads, contact creation or updates, contact groups, directory resources, and synchronization tokens for scheduled incremental synchronization. The older Google Contacts Data API is deprecated, and no general contact-change webhook mechanism was confirmed.
Yes. Martini can consume the Google People REST API using OAuth 2.0, orchestrate scheduled or API-triggered workflows, map Person and related resources, maintain synchronization tokens, and write results to other applications. A dedicated native Martini Google Contacts connector is not confirmed.
No. A dedicated Google Contacts connector is not required. Martini can integrate through the confirmed Google People REST API, OAuth 2.0, pagination, synchronization tokens, and applicable batch or photo operations.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Google Contacts. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Google, cloud infrastructure, or other third-party systems based on subscription, API usage, and deployment model.
Use the Google People REST API with OAuth 2.0. Use paginated list operations and synchronization tokens for recurring synchronization, and use HTTP batching only as a controlled request optimization. Do not design new integrations around the deprecated Google Contacts Data API, SOAP, or GraphQL.
A general Google People API webhook or outbound callback for contact changes was not confirmed. The safer documented approach is a scheduled Martini workflow that polls applicable resources and uses synchronization tokens to limit subsequent reads.
Run an initial full synchronization, then persist the returned synchronization token only after downstream processing succeeds. Use Google resource names and source-system IDs for stable matching, with normalized email or phone values as controlled fallbacks. If a token becomes invalid, perform a full resynchronization.
Yes. Martini can expose an authenticated API that validates a lookup request, calls the Google People API, applies field filtering and business rules, and returns only the required contact data. This is useful when applications should not receive direct Google OAuth access.
Related Martini documentation
Plan your Google Contacts integration
Use Martini to design a secure Google People API workflow for synchronization, contact enrichment, directory publishing, or controlled API access.