Add contacts by pasting JSON

Create several contacts at once, with their emails, phone numbers, addresses and tags, by pasting a JSON document.

The contacts that are hardest to add are the ones currently written as prose: the people named in a set of meeting notes, the attendees on an email, the suppliers listed in a brief. Importing turns them into real contact records in one step, with their emails, phone numbers, addresses and tags already set.

Find it on Contacts, under Import JSON. Use Copy the prompt in the import box to get this format plus the instructions an assistant needs, then paste in the notes or list you are working from and paste back what it gives you.

In the mobile app, choose Import JSON from the Contacts action menu and paste the document. The app reports how many contacts were added.

Importing only ever creates contacts. It does not look for someone who is already in your contacts and merge into them — matching people by name is guesswork, and a wrong guess overwrites a real person's details with a half-remembered version. If a document duplicates somebody, delete the copy afterwards.

The whole document is checked before anything is saved. If any part of it does not fit the format below, no contacts are created and the problem is reported with the exact field that caused it.

The document

{
  "contacts": [
    { "displayName": "Priya Raman", "companyName": "Northgate Studio" }
  ]
}

contacts is required, and holds at least one contact and up to 200.

Each contact

Field Type Notes
displayName string, optional What the contact is listed as. Worked out from the other names if left out.
prefix string, optional Up to 20 characters, e.g. Dr.
firstName string, optional Up to 100 characters.
middleName string, optional Up to 100 characters.
lastName string, optional Up to 100 characters.
suffix string, optional Up to 20 characters.
companyName string, optional Up to 255 characters.
notes string, optional Markdown, up to 20,000 characters. Newlines are kept.
paymentTermsDays number, optional 0 to 365. Used as the default due date when invoicing this contact.
billing object, optional The billing address used on invoices. See below.
emails array, optional Up to 10.
phones array, optional Up to 10.
addresses array, optional Up to 10.
tags array of strings, optional Up to 10, each up to 50 characters. An existing tag with that name is reused rather than duplicated.

Every contact needs at least one of displayName, firstName, lastName or companyName — a contact with no name at all is a row nobody can find again.

billing takes line1, line2, city, state, postalCode and country, all optional strings. It is one address, not a list, and it is the one invoices use.

Emails, phones and addresses

{ "email": "priya@example.com", "label": "Work", "isPrimary": true }
{ "phone": "+44 7700 900123", "label": "Mobile" }
{ "label": "Studio", "street1": "12 Market Street", "city": "Hebden Bridge", "postalCode": "HX7 6AA", "country": "United Kingdom" }
Field Type Notes
email string, required on an email Checked as an email address.
phone string, required on a phone Free text, up to 50 characters. Not checked.
street1, street2, city, state, postalCode, country strings, optional on an address An address needs at least street1 or city.
label string, optional e.g. Work, Home, Studio. Up to 50 characters.
isPrimary boolean, optional The first one in each list is the primary unless another says otherwise. Only one can be.

A complete example

{
  "contacts": [
    {
      "displayName": "Priya Raman",
      "firstName": "Priya",
      "lastName": "Raman",
      "companyName": "Northgate Studio",
      "notes": "Met at the June trade show. Wants a quote for the spring range.",
      "paymentTermsDays": 30,
      "billing": { "line1": "12 Market Street", "city": "Hebden Bridge", "postalCode": "HX7 6AA", "country": "United Kingdom" },
      "emails": [{ "email": "priya@example.com", "label": "Work" }],
      "phones": [{ "phone": "+44 7700 900123", "label": "Mobile" }],
      "tags": ["supplier", "prospect"]
    },
    {
      "displayName": "Halden Freight",
      "companyName": "Halden Freight",
      "emails": [{ "email": "bookings@example.com" }],
      "tags": ["supplier"]
    }
  ]
}

If an import is rejected for a reason you can't work out, Contact support.

Updated September 23, 2026

Related articles