Fork me on GitHub

JMAP Contacts

This document specifies a data model for synchronising contacts data with a server using JMAP.


JMAP is a generic protocol for synchronising data, such as mail, calendars or contacts, between a client and a server. It is optimised for mobile and web environments, and aims to provide a consistent interface to different data types.

This specification defines a data model for synchronising contacts between a client and a server using JMAP.

Notational Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [@!RFC2119].

The underlying format used for this specification is JSON. Consequently, the terms “object” and “array” as well as the four primitive types (strings, numbers, booleans, and null) are to be interpreted as described in Section 1 of [@!RFC7159]. Unless otherwise noted, all the property names and values are case sensitive.

Some examples in this document contain “partial” JSON documents used for illustrative purposes. In these examples, three periods “…” are used to indicate a portion of the document that has been removed for compactness.

Types signatures are given for all JSON objects in this document. The following conventions are used:


The same terminology is used in this document as in the core JMAP specification.

Addition to the capabilities object

The capabilities object is returned as part of the standard JMAP Session object; see the JMAP spec. Servers supporting this specification MUST add a property called {TODO: URI for this spec} to the capabilities object. The value of this is an empty object.

Contact Groups

A ContactGroup object represents a named set of contacts. It has the following properties:


Standard /get method. The ids argument may be null to fetch all at once.


Standard /changes method.


Standard /set method.


A Contact object stores information about a person or company. It has the following properties:

Note, none of these properties have a nullable type. If the specific information is not known for a contact, the empty string or empty array should be used as appropriate, or in the case of birthday the string "0000-00-00".

A ContactInformation object has the following properties:

An Address object has the following properties:

A File Object has the following properties:


Standard /get method. The ids argument may be null to fetch all at once.


Standard /changes method.


Standard /query method.


A FilterCondition object has the following properties:

If zero properties are specified on the FilterCondition, the condition MUST always evaluate to true. If multiple properties are specified, ALL must apply for the condition to be true (it is equivalent to splitting the object into one-property conditions and making them all the child of an AND filter operator).

The exact semantics for matching String fields is deliberately not defined to allow for flexibility in indexing implementation, subject to the following:


The following properties MUST be supported for sorting:


Standard /queryChanges method.


Standard /set method.

To set a new avatar, the file must first be uploaded using the standard upload mechanism (see the File Uploads section of this spec). This will give the client a valid blobId/size/type to use. The server SHOULD reject attempts to set a file that is not a recognised image type as the avatar for a contact.