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].

Type signatures, examples and property descriptions in this document follow the conventions established in section 1.1 of [@!I-D.ietf-jmap-core].

Object properties may also have a set of attributes defined along with the type signature. These have the following meanings:

Data types defined in the core specification are used in this document.


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. 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.


Standard “/copy” method.