contacts phone format fixer | Winfred van Kuijk

contacts phone format fixer

By • Published: November 15, 2014 • Last updated: June 4, 2023 • Filed in: Software

The script will format phone numbers according using international notation:

  • contacts phone format fixer before afterLocal numbers (e.g. 0891234567) will be converted to an international number (e.g. +33 891 23 45 67), by using the country of the contact’s address.
  • All numbers will get the format that is the preferred format for that country (e.g. 0891234567 in Germany would be +49 89 1234567).
  • Phone numbers with a (potential) issue are highlighted so you can take action.
  • If there is no address available for the contact and the phone number is in an international format, then the script will add the address (country name), e.g. +49 89 1234567 will add the country Germany to the address field.

Turning local phone numbers into international formats depends on using the contact’s address. This relies on the country format code (not the country name). You can set the format manually for each card, or you can use my country format plug-in that automates it.
It is highly recommended to run the country format plug-in before you check the phone formats.

You can use the script standalone (run using Script Editor), or you can use it as a plug-in inside the Contacts application. Yosemite (10.10) or higher is required.

Note that the Contacts application tries to format the phone numbers automatically as well, so it could be Apple’s formatting is shown instead of the actually stored format. In that case the formatting done by the script is mostly useful if you want to print or export contacts.

Download and check instructions for details.

Download “Contacts phone format fixer”

contacts phone format fixer.scpt.bz2 – 9.70 KB

Is this script saving you time/money?
Feel free to make a donation, to me or your favorite charity.

This script will modify the phone numbers. Before using the script: make sure you have a backup of your contacts. And check the examples, to avoid unwanted changes.

Address country format

The script can add the country prefix to a number, by using the country format used for that contact’s address.
It is important you use the right format. Example: if a contact’s address is in Germany, but the format used is France, then local (German) phone numbers will be turned into a French international number.

To automatically check + fix country codes you can use my country format plug-in.
It highly recommended to run that script/plug-in before you use the phone format fixer.

Your default country code is set by:

  • Contacts: Preferences… > General > Address Format

The country format code for an address is manually set by:

  • selecting Edit for a contact
  • clicking the label of an Address (e.g. “work”)
  • selecting “Change Address Format” and then the country


In short: download the zip file, open the script file, check the user options and run.

In detail:

  • The script requires Yosemite (10.10) or higher. This is because the script is written in Javascript for Automation, which became available in Yosemite.
  • Download the zip file and unzip.
  • The script can be used standalone, or as plug-in. To use standalone: store the script wherever you like. To use as Contacts plug-in, place the script in ~/Library/Application scripts/
  • Check if the default settings (see user options) are ok, and if not: open the script and modify them.
  • When using as plug-in: restart Contacts after installing the script. Click on any phone number and you will see the option “Check format for this contact” (by default the plug-in will only check the currently selected person).
  • When using as standalone script: open the script and press the run button. By default it will check all contacts when running as standalone script.
  • The first time you run the script it will download + install the required library. The script uses the PhoneFormat library, which is built using Google’s libphonenumer.
  • Optional: in the Contacts application, create a smart group (Phone ends with ]). This so you will automatically see all contacts that have a phone number with a (possible) issue.

create Contacts smart group to show phone numbers with issue

use script as Contacts plug-in

Manually install PhoneFormat library

The script will install the required PhoneFormat library automatically.
It can use both the released version, or (preferred and default) create one based on the latest libphonenumber library.
You can also manually install / update the released version of the library.

mkdir ~/Library/Script\ Libraries/; curl -s | \
osacompile -l JavaScript -o ~/Library/Script\ Libraries/PhoneFormat.scpt

Version history

  • 1.0: initial release
  • 1.1: better support for extensions, user option to display all as E164 format, bug fixes
  • 1.2: ignore short numbers, support prefixes, use latest libphonenumber repository, bug fixes
  • 1.3: check if phone number is mobile and update label if necessary
  • 1.3.2: new source locations for latest and released libraries
  • 1.4: address changes in phoneformat library
  • 1.5: add option to check latest libphonenumber library version and download if there is a newer version

User options

The following options are available. Open the script to change them.

option default explanation
addComment true add comment to phone numbers that have an issue?
minimumLength 5 ignore phone numbers shorter than this length (e.g. 911)
warnAboutPrefix false warn if phone number contains prefix (e.g. #31# 1-800…, **1 1-800…)
warnAboutExtensions false warn if phone number contains extension, e.g. 123456 x123
labelMobile “mobile” if library determines the number is mobile: use this as label (instead of home/office/iPhone/…); use labelMobile:null to ignore
checkValid true check if the phone number is valid for that country (=slower)
createAddress true create an address (=country) if there is no address for a contact and we know the country
writeMyCountryAsLocal false write all numbers in international format (false), or write local numbers without international prefix (true)
writeAllAsE164 false write all phone numbers in E164 format (+49891234567), without country specific formatting
useAddressForCountryCode true for local numbers: use the 1st address with country code to determine the country prefix?
useDefaultCountryForCountryCode false if we don’t know what country the number is, use Contact’s default country?
useLatestLibrary true create latest from phoneliblibrary (true), or use officially released JavaScript library (false)
maxAgeForLibrary 60 update libraries every n days (set to 0 to force download every time the script is used)
pluginAllContacts false when using as Contacts plugin: check all contacts (true), or only the selected one (false)
showWarning true show the alert dialog before running the script

By default all contacts will be checked (when running as standalone script). In the user options you can define a subset. Examples:

myPeople = Contacts.groups.whose({ name : "phone issues" }).people // all contacts from a specific group
myPeople = Contacts.people.whose({ lastName: "testing" }) // all contacts with last name "testing"

input output
phone: 0891234567
address: country code “Germany”
phone: +49 89 1234567
phone: +49891234567 phone: +49 89 1234567
phone: 089-1234567
address: country code “France”
phone: +33 891 23 45 67
phone: +1-800-234 issue: invalid number (incorrect format)
phone: 0800-1234567
address: none
issue: unknown country
phone: +1-800-1234567 issue: invalid number (according to the library it is not likely this number exists)
phone: +1-800-2345678
country: none
phone: +1 800-234-5678
new address: country = “United States”
phone: 0891234567
address: country name “Germany” but country formatting code “France”
phone: +33 891 23 45 67
note: to avoid the unwanted behavior, set the country formatting code to Germany
phone: 0891234567
address 1: France (work)
address 2: Germany (home)
phone: +33 891 23 45 67
note: the first country will be used to decide what country prefix to use

4 Responses to “contacts phone format fixer”

  1. Steve says:

    At the present time, contacts phone format cannot be expanded with either the Mac Archive Utility nor with Unarchiver. The Archive Utility fails with Error 1, and Unarchiver fails with archive is incomplete.

    I’d love to use this script and would greatly appreciate a fix.

    • winfred says:

      I am seeing the same issue, not sure why. As a workaround I have uploaded a bzip compressed version which does not seem to have this issue. Enjoy!

  2. mathepac (msj) says:

    Great script, I’ve been looking for something to do this job for ages. Thank you.

Leave a Reply

Home | »