Read and Manage Google Contacts with Apps Script

Apps Script's ContactsApp lets you access and manipulate your Google Contacts programmatically — useful for exporting contact lists to Sheets, syncing data, or building lightweight CRM workflows.

Get all contacts

function getAllContacts() {
  const contacts = ContactsApp.getContacts();
  Logger.log(`Total contacts: ${contacts.length}`);

  contacts.slice(0, 10).forEach(contact => {
    const name  = contact.getFullName();
    const emails = contact.getEmails().map(e => e.getAddress());
    const phones = contact.getPhones().map(p => p.getPhoneNumber());
    Logger.log(`${name} | ${emails.join(', ')} | ${phones.join(', ')}`);
  });
}

Export contacts to a Google Sheet

function exportContactsToSheet() {
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  sheet.clearContents();
  sheet.appendRow(['Full Name', 'Email', 'Phone', 'Company', 'Notes']);

  const contacts = ContactsApp.getContacts();

  contacts.forEach(contact => {
    const name    = contact.getFullName() || '';
    const email   = contact.getEmails()[0]?.getAddress() || '';
    const phone   = contact.getPhones()[0]?.getPhoneNumber() || '';
    const company = contact.getCompanies()[0]?.getCompanyName() || '';
    const notes   = contact.getNotes() || '';

    sheet.appendRow([name, email, phone, company, notes]);
  });

  Logger.log(`Exported ${contacts.length} contacts.`);
}

Search contacts by name or email

function searchContacts(query) {
  const results = ContactsApp.getContactsByName(query);
  Logger.log(`Found ${results.length} contact(s) matching "${query}"`);

  results.forEach(c => {
    Logger.log(`${c.getFullName()} — ${c.getEmails().map(e => e.getAddress()).join(', ')}`);
  });
}

function findContactByEmail(email) {
  const results = ContactsApp.getContactsByEmailAddress(email);
  if (results.length === 0) {
    Logger.log('No contact found with that email.');
    return null;
  }
  return results[0];
}

Get contacts from a specific group

function getContactsFromGroup(groupName) {
  const group = ContactsApp.getContactGroup(groupName);
  if (!group) {
    Logger.log(`Group "${groupName}" not found.`);
    return;
  }

  const contacts = group.getContacts();
  Logger.log(`Group "${groupName}" has ${contacts.length} contact(s).`);

  contacts.forEach(c => {
    Logger.log(`${c.getFullName()} — ${c.getEmails()[0]?.getAddress() || 'No email'}`);
  });
}

Update a contact's notes field

function addNoteToContact(email, note) {
  const contacts = ContactsApp.getContactsByEmailAddress(email);
  if (contacts.length === 0) {
    Logger.log('Contact not found.');
    return;
  }

  const contact = contacts[0];
  const existing = contact.getNotes() || '';
  contact.setNotes(existing + (existing ? '\n' : '') + note);
  Logger.log(`Note added to ${contact.getFullName()}.`);
}

Create a new contact

function createContact(firstName, lastName, email, phone) {
  const contact = ContactsApp.createContact(firstName, lastName, email);

  if (phone) {
    contact.addPhone(ContactsApp.Field.MOBILE_PHONE, phone);
  }

  Logger.log(`Created contact: ${contact.getFullName()} (${email})`);
  return contact;
}

Import contacts from a Sheet

function importContactsFromSheet() {
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  const data = sheet.getDataRange().getValues().slice(1); // Skip header

  let created = 0;

  data.forEach(([firstName, lastName, email, phone]) => {
    if (!email) return;

    // Check if contact already exists
    const existing = ContactsApp.getContactsByEmailAddress(email);
    if (existing.length > 0) {
      Logger.log(`Skipping existing contact: ${email}`);
      return;
    }

    createContact(firstName, lastName, email, phone);
    created++;
    Utilities.sleep(200); // Avoid quota issues
  });

  Logger.log(`Imported ${created} new contact(s).`);
}

Tips

ContactsApp is deprecated in favour of the People API (via UrlFetchApp), but it still works and is much simpler for basic use cases.
For large contact lists, ContactsApp.getContacts() can be slow — consider using getContactsByName() or group-based access to narrow down results.
Contact updates are applied immediately — there's no saveAndClose() needed.
Be mindful of the Apps Script contacts quota: up to 1,000 contact operations per day.