Google People API gebruiken voor contactbeheer

Wat is de Google People API?

De Google People API geeft programmatische toegang tot contacten in Google Contacts. Je kunt contacten lezen, aanmaken, bijwerken en verwijderen. De API vervangt de oudere Google Contacts API v3 (de m8/feeds-scope) en biedt modernere endpoints met betere ondersteuning voor zakelijke contacten.

Veelvoorkomende toepassingen:

• CRM-synchronisatie waarbij klantdata automatisch naar Google Contacts wordt gestuurd.
• Contactimport vanuit een legacy-systeem.
• Automatisch bijhouden van contactinformatie op basis van e-mailinteracties.
• Organisatiecontacten beschikbaar maken voor medewerkers.

API inschakelen

Scopes kiezen

De People API vereist specifieke OAuth-scopes afhankelijk van de operaties. Vraag altijd de minimaal benodigde scope aan, dus geen schrijftoegang als alleen lezen voldoende is.

Alle schrijfacties (createContact, updateContact, deleteContact, updateContactPhoto) vereisen de volledige contacts-scope.

Contacten ophalen

Gebruik people.connections.list met een personFields-masker om te bepalen welke velden je terugkrijgt. Paginering verloopt via nextPageToken.

from google.oauth2.credentials import Credentials
from googleapiclient.discovery import build


def get_contacts(credentials, page_size=100):
    service = build('people', 'v1', credentials=credentials)

    results = service.people().connections().list(
        resourceName='people/me',
        pageSize=page_size,
        personFields='names,emailAddresses,phoneNumbers,organizations'
    ).execute()

    connections = results.get('connections', [])
    contacts = []

    for person in connections:
        contact = {}

        names = person.get('names', [])
        if names:
            contact['name'] = names[0].get('displayName', '')

        emails = person.get('emailAddresses', [])
        if emails:
            contact['email'] = emails[0].get('value', '')

        phones = person.get('phoneNumbers', [])
        if phones:
            contact['phone'] = phones[0].get('value', '')

        contacts.append(contact)

    return contacts

Een contact aanmaken

def create_contact(service, naam, email, telefoon=None, bedrijf=None):
    delen = naam.split()
    contact_body = {
        'names': [{
            'givenName': delen[0],
            'familyName': ' '.join(delen[1:])
        }],
        'emailAddresses': [{'value': email, 'type': 'work'}],
    }

    if telefoon:
        contact_body['phoneNumbers'] = [{'value': telefoon, 'type': 'work'}]

    if bedrijf:
        contact_body['organizations'] = [{'name': bedrijf, 'type': 'work'}]

    result = service.people().createContact(body=contact_body).execute()
    return result.get('resourceName')

Contacten bijwerken

Bij een update moet je de actuele etag van het contact meesturen. Haal daarom eerst het contact op, neem de etag over en gebruik updatePersonFields om aan te geven welke velden je wijzigt.

def update_contact(service, resource_name, update_fields):
    person = service.people().get(
        resourceName=resource_name,
        personFields='names,emailAddresses,phoneNumbers'
    ).execute()

    update_fields['etag'] = person.get('etag')

    velden = [k for k in update_fields if k != 'etag']

    result = service.people().updateContact(
        resourceName=resource_name,
        updatePersonFields=','.join(velden),
        body=update_fields
    ).execute()

    return result

Contactgroepen beheren

Contactgroepen (labels) helpen je contacten te categoriseren:

def create_contact_group(service, naam):
    body = {'contactGroup': {'name': naam}}
    result = service.contactGroups().create(body=body).execute()
    return result.get('resourceName')


def add_to_group(service, group_resource_name, contact_resource_names):
    body = {'resourceNamesToAdd': contact_resource_names}
    service.contactGroups().members().modify(
        resourceName=group_resource_name,
        body=body
    ).execute()

Synchroniseren met een CRM

Voor een betrouwbare sync vergelijk je contacten op een stabiele sleutel (zoals e-mailadres of een eigen ID) en houd je per kant bij wat het laatst is gewijzigd.