server/protocols/jmap-draft/doc/specs/spec/contact.mdwn - james-project - Git at Google

 ## Contacts
 <aside class="warning">
 Not implemented
 </aside>

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

 - **id**: `String`
   The id of the contact. This property is immutable.
 - **isFlagged**: `Boolean`
   Is the contact flagged (marked as important in some way by the user)?
 - **avatar**: `File|null`
   A file containing an image to be used to represent this contact.
 - **prefix**: `String`
   The honorific title of the contact, e.g. "Mr", "Ms", "Dr", etc.
 - **firstName**: `String`
   The first name(s) of a contact.
 - **lastName**: `String`
   The last name of a contact.
 - **suffix**: `String`
   The honorific suffix of the contact, e.g. "B.A.", "Esq." etc.
 - **nickname**: `String`
   The nickname of the contact.
 - **birthday**: `String`
   The person's birth date in the form `"YYYY-MM-DD"` (any part may be all `0`s for unknown).
 - **anniversary**: `String`
   The person's anniversary date in the form `"YYYY-MM-DD"` (any part may be all `0`s for unknown).
 - **company**: `String`
   The company for which the person works.
 - **department**: `String`
   The department within the company for which the person works.
 - **jobTitle**: `String`
   The job title of the person.
 - **emails**: `ContactInformation[]`
   An array of ContactInformation objects where the values are email addresses. Types are:
   - `"personal"` The address is for emailing the person in a personal context.
   - `"work"` The address is for emailing the person in a professional context.
   - `"other"` The address is for some other purpose. A *label* property MAY be included to display next to the address to help the user identify its purpose.
 - **phones**: `ContactInformation[]`
   An array of ContactInformation objects where the values are phone numbers. Types are:
   - `"home"` The number is for contacting the person at their residence.
   - `"work"` The number is for contacting the person at their workplace.
   - `"mobile"` The number is for contacting the person regardless of location.
   - `"fax"` The number is for sending faxes to the contact.
   - `"pager"` The number is for a pager or beeper associated with the contact.
   - `"other"` The number is for some other purpose. A *label* property MAY be included to display next to the number to help the user identify its purpose.
 - **online**: `ContactInformation[]`
   An array of ContactInformation objects where the values are URIs or usernames associated with the person for online services.
   Types are:
   - `"uri"` The value is a URI, e.g. a website link.
   - `"username"` The value is a username associated with the person (e.g. for Twitter, or Facebook, or an IM client). A *label* property SHOULD be included to identify what service this is for. For compatibility between clients, this label SHOULD be the canonical service name, including capitalisation. e.g. `"Twitter"`, `"Facebook"`, `"Skype"`, `"GitHub"`, `"XMPP"`.
   - `"other"` The value is something else not covered by the above categories. A *label* property MAY be included to display next to the number to help the user identify its purpose.
 - **addresses**: `Address[]`
   An array of Address objects, containing physical locations associated with the person.
   Types are:
   - `"home"` An address of a residence associated with the person.
   - `"work"` An address of a workplace associated with the person.
   - `"billing"` An address to be used with billing associated with the person.
   - `"postal"` An address to be used for delivering physical items to the person.
   - `"other"` An address not covered by the above categories.
 - **notes**: `String`
   Arbitrary notes about the contact.

 Note, none of these properties have a `null`able 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:

 - **type**: `String`
   Specifies the context of the contact information. This MUST be taken from the set of values allowed depending on whether this is part of the *phones*, *emails* or *online* property (see above).
 - **label**: `String|null`
   A label describing the value in more detail, especially if `type === "other"` (but MAY be included with any type).
 - **value**: `String`
   The actual contact information, e.g. the email address or phone number.
 - **isDefault**: `Boolean`
   Whether this contact is the default for its type (SHOULD only be one per type, but some backends will allow multiple defaults)

 An **Address** object has the following properties:

 - **type**: `String`
   Specifies the context of the contact information. This MUST be taken from the set of values allowed depending on whether this is part of the *phones*, *emails* or *online* property (see above).
 - **label**: `String|null`
   A label describing the value in more detail, especially if `type === "other"` (but MAY be included with any type).
 - **street**: `String`
   The street address. This MAY be multiple lines; newlines MUST be preserved.
 - **locality**: `String`
   The city, town, village, post town, or other locality within which the street address may be found.
 - **region**: `String`
   The province, such as a state, county, or canton within which the locality may be found.
 - **postcode**: `String`
   The postal code, post code, ZIP code or other short code associated with the address by the relevant country's postal system.
 - **country**: `String`
   The country name.
 - **isDefault**: `Boolean`
   Whether this contact is the default for its type (SHOULD only be one per type, but some backends will allow multiple defaults)

 A **File** Object has the following properties:

 - **blobId**: `String`
   The id of the binary data.
 - **type**: `String|null`
   The content-type of the file, if known.
 - **name**: `String|null`
   The full file name, if known. e.g. "myface.png"
 - **size**: `Number|null`
   The size, in bytes, of the file when fully decoded (i.e. the number of bytes in the file the user would download), if known.

 ### getContacts

 Contacts can either be fetched explicitly by id, or all of them at once. To fetch contacts, make a call to `getContacts`. It takes the following arguments:

 - **accountId**: `String|null`
   The Account to fetch the contacts for. If `null`, the primary account is used.
 - **ids**: `String|null`
   The ids of the contacts to fetch. If `null`, all contacts in the account are be fetched.
 - **properties**: `String[]|null`
   If supplied, only the properties listed in the array will be returned for each contact. If `null`, all properties are returned. The id of the contact will **always** be returned, even if not explicitly requested.

 The response to *getContacts* is called *contacts*. It has the following arguments:

 - **accountId**: `String`
   The id of the account used for the call.
 - **state**: `String`
   A string representing the state on the server for **all** contacts. If the state of a contact changes, or a new contact is created, or a contact is destroyed, this string will change. It is used to get delta updates.
 - **list**: `Contact[]`
   An array of the Contact objects requested. This will be the **empty array** if the *ids* argument was the empty array, or contained only ids for contacts that could not be found.
 - **notFound**: `String[]|null`
   This array contains the ids passed to the method for contacts that do not exist, or `null` if all requested ids were found. It will always be `null` if the *ids* argument in the call was `null`.

 The following errors may be returned instead of the *contacts* response:

 `accountNotFound`: Returned if an *accountId* was explicitly included with the request, but it does not correspond to a valid account.

 `accountNoContacts`: Returned if the *accountId* given corresponds to a valid account, but does not contain any contact data.

 `invalidArguments`: Returned if the request does not include one of the required arguments, or one of the arguments is of the wrong type, or otherwise invalid. A `description` property MAY be present on the response object to help debug with an explanation of what the problem was.

 ### getContactUpdates

 The *getContactUpdates* call allows a client to efficiently update the state of its cached contacts to match the new state on the server. It takes the following arguments:

 - **accountId**: `String|null`
   The id of the account to use for this call. If `null`, the primary account will be used.
 - **sinceState**: `String`
   The current state of the client. This is the string that was returned as the *state* argument in the *contacts* response. The server will return the changes made since this state.
 - **maxChanges**: `Number|null`
   The maximum number of Contact ids to return in the response. The server MAY choose to clamp this value to a particular maximum or set a maximum if none is given by the client. If supplied by the client, the value MUST be a positive integer greater than 0. If a value outside of this range is given, the server MUST reject the call with an `invalidArguments` error.
 - **fetchRecords**: `Boolean|null`
   If `true`, after outputting a *contactUpdates* response, an implicit call will be made to *getContacts* with the *changed* property of the response as the *ids* argument, and the *fetchRecordProperties* argument as the *properties* argument. If `false` or `null`, no implicit call is made.
 - **fetchRecordProperties**: `String[]|null`
   Passed through as the *properties* argument to any implicit *getContacts* call.

 The response to *getContactUpdates* is called *contactUpdates*. It has the following arguments:

 - **accountId**: `String`
   The id of the account used for the call.
 - **oldState**: `String`
   This is the *sinceState* argument echoed back; the state from which the server is returning changes.
 - **newState**: `String`
   This is the state the client will be in after applying the set of changes to the old state.
 - **hasMoreUpdates**: `Boolean`
   If `true`, the client may call *getContactUpdates* again with the *newState* returned to get further updates. If `false`, *newState* is the current server state.
 - **changed**: `String[]`
   An array of Contact ids where a property of the contact has changed between the old state and the new state, or the contact has been created, and the contact has not been destroyed.
 - **removed**: `String[]`
   An array of Contact ids for contacts which have been destroyed since the old state.

 If a *maxChanges* is supplied, or set automatically by the server, the server must try to limit the number of ids across *changed* and *removed* to the number given. If there are more changes than this between the client's state and the current server state, the update returned MUST take the client to an intermediate state, from which the client can continue to call *getContactUpdates* until it is fully up to date. The server MAY return more ids than the *maxChanges* total if this is required for it to be able to produce an update to an intermediate state, but it SHOULD try to keep it close to the maximum requested.

 If a contact has been modified AND deleted since the oldState, the server should just return the id in the *removed* array, but MAY return it in the *changed* array as well. If a contact has been created AND deleted since the oldState, the server SHOULD remove the contact id from the response entirely, but MAY include it in the *removed* array, and optionally the *changed* array as well.

 The following errors may be returned instead of the `contactUpdates` response:

 `accountNotFound`: Returned if an *accountId* was explicitly included with the request, but it does not correspond to a valid account.

 `accountNoContacts`: Returned if the *accountId* given corresponds to a valid account, but does not contain any contacts data.

 `invalidArguments`: Returned if the request does not include one of the required arguments, or one of the arguments is of the wrong type, or otherwise invalid. A `description` property MAY be present on the response object to help debug with an explanation of what the problem was.

 `cannotCalculateChanges`: Returned if the server cannot calculate the changes from the state string given by the client. Usually due to the client's state being too old, or the server being unable to produce an update to an intermediate state when there are too many updates. The client MUST invalidate its Contact cache. The error object MUST also include a `newState: String` property with the current state for the type.

 ### setContacts

 Modifying the state of Contact objects on the server is done via the *setContacts* method. This encompasses creating, updating and destroying Contact records.

 The *setContacts* method takes the following arguments:

 - **accountId**: `String|null`
   The id of the account to use for this call. If `null`, the primary account will be used.
 - **ifInState**: `String|null`
   This is a state string as returned by the *getContacts* method. If supplied, the string must match the current state, otherwise the method will be aborted and a `stateMismatch` error returned. If `null`, the change will be applied to the current state.
 - **create**: `String[Contact]|null`
   A map of *creation id* (an arbitrary string set by the client) to Contact objects (containing all properties except the id).
 - **update**: `String[Contact]|null`
   A map of id to a Contact object. The object may omit any property; only properties that have changed need be included.
 - **destroy**: `String[]|null`
   A list of ids for Contact objects to permanently delete.

 Each create, update or destroy is considered an atomic unit. It is permissible for the server to commit some of the changes but not others, however it is not permissible to only commit part of an update to a single contact (e.g. update the *firstName* property but not the *lastName* property if both are supplied in the update object).

 If a create, update or destroy is rejected, the appropriate error should be added to the notCreated/notUpdated/notDestroyed property of the response and the server MUST continue to the next create/update/destroy. It does not terminate the method.

 If an id given cannot be found, the update or destroy MUST be rejected with a `notFound` set error.

 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.

 The response to *setContacts* is called *contactsSet*. It has the following arguments:

 - **accountId**: `String`
   The id of the account used for the call.
 - **oldState**: `String|null`
   The state string that would have been returned by *getContacts* before making the requested changes, or `null` if the server doesn't know what the previous state string was.
 - **newState**: `String`
   The state string that will now be returned by *getContacts*.
 - **created**: `String[Contact]`
   A map of the creation id to an object containing the **id** property for all successfully created contacts.
 - **updated**: `String[]`
   A list of ids for contacts that were successfully updated.
 - **destroyed**: `String[]`
   A list of ids for contacts that were successfully destroyed.
 - **notCreated**: `String[SetError]`
   A map of creation id to a SetError object for each contact that failed to be created. The possible errors are defined in the description of the method for specific data types.
 - **notUpdated**: `String[SetError]`
   A map of Contact id to a SetError object for each contact that failed to be updated. The possible errors are defined in the description of the method for specific data types.
 - **notDestroyed**: `String[SetError]`
   A map of Contact id to a SetError object for each contact that failed to be destroyed. The possible errors are defined in the description of the method for specific data types.

 A **SetError** object has the following properties:

 - **type**: `String`
   The type of error.
 - **description**: `String|null`
   A description of the error to display to the user.

 Other properties may also be present on the object, as described in the relevant methods.

 The following errors may be returned instead of the *contactsSet* response:

 `accountNotFound`: Returned if an *accountId* was explicitly included with the request, but it does not correspond to a valid account.

 `accountNoContacts`: Returned if the *accountId* given corresponds to a valid account, but does not contain any contacts data.

 `accountReadOnly`: Returned if the account has `isReadOnly == true`.

 `invalidArguments`: Returned if one of the arguments is of the wrong type, or otherwise invalid. A *description* property MAY be present on the response object to help debug with an explanation of what the problem was.

 `stateMismatch`: Returned if an *ifInState* argument was supplied and it does not match the current state.
	## Contacts
	<aside class="warning">
	Not implemented
	</aside>

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

	- id: `String`
	The id of the contact. This property is immutable.
	- isFlagged: `Boolean`
	Is the contact flagged (marked as important in some way by the user)?
	- avatar: `File\|null`
	A file containing an image to be used to represent this contact.
	- prefix: `String`
	The honorific title of the contact, e.g. "Mr", "Ms", "Dr", etc.
	- firstName: `String`
	The first name(s) of a contact.
	- lastName: `String`
	The last name of a contact.
	- suffix: `String`
	The honorific suffix of the contact, e.g. "B.A.", "Esq." etc.
	- nickname: `String`
	The nickname of the contact.
	- birthday: `String`
	The person's birth date in the form `"YYYY-MM-DD"` (any part may be all `0`s for unknown).
	- anniversary: `String`
	The person's anniversary date in the form `"YYYY-MM-DD"` (any part may be all `0`s for unknown).
	- company: `String`
	The company for which the person works.
	- department: `String`
	The department within the company for which the person works.
	- jobTitle: `String`
	The job title of the person.
	- emails: `ContactInformation[]`
	An array of ContactInformation objects where the values are email addresses. Types are:
	- `"personal"` The address is for emailing the person in a personal context.
	- `"work"` The address is for emailing the person in a professional context.
	- `"other"` The address is for some other purpose. A label property MAY be included to display next to the address to help the user identify its purpose.
	- phones: `ContactInformation[]`
	An array of ContactInformation objects where the values are phone numbers. Types are:
	- `"home"` The number is for contacting the person at their residence.
	- `"work"` The number is for contacting the person at their workplace.
	- `"mobile"` The number is for contacting the person regardless of location.
	- `"fax"` The number is for sending faxes to the contact.
	- `"pager"` The number is for a pager or beeper associated with the contact.
	- `"other"` The number is for some other purpose. A label property MAY be included to display next to the number to help the user identify its purpose.
	- online: `ContactInformation[]`
	An array of ContactInformation objects where the values are URIs or usernames associated with the person for online services.
	Types are:
	- `"uri"` The value is a URI, e.g. a website link.
	- `"username"` The value is a username associated with the person (e.g. for Twitter, or Facebook, or an IM client). A label property SHOULD be included to identify what service this is for. For compatibility between clients, this label SHOULD be the canonical service name, including capitalisation. e.g. `"Twitter"`, `"Facebook"`, `"Skype"`, `"GitHub"`, `"XMPP"`.
	- `"other"` The value is something else not covered by the above categories. A label property MAY be included to display next to the number to help the user identify its purpose.
	- addresses: `Address[]`
	An array of Address objects, containing physical locations associated with the person.
	Types are:
	- `"home"` An address of a residence associated with the person.
	- `"work"` An address of a workplace associated with the person.
	- `"billing"` An address to be used with billing associated with the person.
	- `"postal"` An address to be used for delivering physical items to the person.
	- `"other"` An address not covered by the above categories.
	- notes: `String`
	Arbitrary notes about the contact.

	Note, none of these properties have a `null`able 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:

	- type: `String`
	Specifies the context of the contact information. This MUST be taken from the set of values allowed depending on whether this is part of the phones, emails or online property (see above).
	- label: `String\|null`
	A label describing the value in more detail, especially if `type === "other"` (but MAY be included with any type).
	- value: `String`
	The actual contact information, e.g. the email address or phone number.
	- isDefault: `Boolean`
	Whether this contact is the default for its type (SHOULD only be one per type, but some backends will allow multiple defaults)

	An Address object has the following properties:

	- type: `String`
	Specifies the context of the contact information. This MUST be taken from the set of values allowed depending on whether this is part of the phones, emails or online property (see above).
	- label: `String\|null`
	A label describing the value in more detail, especially if `type === "other"` (but MAY be included with any type).
	- street: `String`
	The street address. This MAY be multiple lines; newlines MUST be preserved.
	- locality: `String`
	The city, town, village, post town, or other locality within which the street address may be found.
	- region: `String`
	The province, such as a state, county, or canton within which the locality may be found.
	- postcode: `String`
	The postal code, post code, ZIP code or other short code associated with the address by the relevant country's postal system.
	- country: `String`
	The country name.
	- isDefault: `Boolean`
	Whether this contact is the default for its type (SHOULD only be one per type, but some backends will allow multiple defaults)

	A File Object has the following properties:

	- blobId: `String`
	The id of the binary data.
	- type: `String\|null`
	The content-type of the file, if known.
	- name: `String\|null`
	The full file name, if known. e.g. "myface.png"
	- size: `Number\|null`
	The size, in bytes, of the file when fully decoded (i.e. the number of bytes in the file the user would download), if known.

	### getContacts

	Contacts can either be fetched explicitly by id, or all of them at once. To fetch contacts, make a call to `getContacts`. It takes the following arguments:

	- accountId: `String\|null`
	The Account to fetch the contacts for. If `null`, the primary account is used.
	- ids: `String\|null`
	The ids of the contacts to fetch. If `null`, all contacts in the account are be fetched.
	- properties: `String[]\|null`
	If supplied, only the properties listed in the array will be returned for each contact. If `null`, all properties are returned. The id of the contact will always be returned, even if not explicitly requested.

	The response to getContacts is called contacts. It has the following arguments:

	- accountId: `String`
	The id of the account used for the call.
	- state: `String`
	A string representing the state on the server for all contacts. If the state of a contact changes, or a new contact is created, or a contact is destroyed, this string will change. It is used to get delta updates.
	- list: `Contact[]`
	An array of the Contact objects requested. This will be the empty array if the ids argument was the empty array, or contained only ids for contacts that could not be found.
	- notFound: `String[]\|null`
	This array contains the ids passed to the method for contacts that do not exist, or `null` if all requested ids were found. It will always be `null` if the ids argument in the call was `null`.

	The following errors may be returned instead of the contacts response:

	`accountNotFound`: Returned if an accountId was explicitly included with the request, but it does not correspond to a valid account.

	`accountNoContacts`: Returned if the accountId given corresponds to a valid account, but does not contain any contact data.

	`invalidArguments`: Returned if the request does not include one of the required arguments, or one of the arguments is of the wrong type, or otherwise invalid. A `description` property MAY be present on the response object to help debug with an explanation of what the problem was.

	### getContactUpdates

	The getContactUpdates call allows a client to efficiently update the state of its cached contacts to match the new state on the server. It takes the following arguments:

	- accountId: `String\|null`
	The id of the account to use for this call. If `null`, the primary account will be used.
	- sinceState: `String`
	The current state of the client. This is the string that was returned as the state argument in the contacts response. The server will return the changes made since this state.
	- maxChanges: `Number\|null`
	The maximum number of Contact ids to return in the response. The server MAY choose to clamp this value to a particular maximum or set a maximum if none is given by the client. If supplied by the client, the value MUST be a positive integer greater than 0. If a value outside of this range is given, the server MUST reject the call with an `invalidArguments` error.
	- fetchRecords: `Boolean\|null`
	If `true`, after outputting a contactUpdates response, an implicit call will be made to getContacts with the changed property of the response as the ids argument, and the fetchRecordProperties argument as the properties argument. If `false` or `null`, no implicit call is made.
	- fetchRecordProperties: `String[]\|null`
	Passed through as the properties argument to any implicit getContacts call.

	The response to getContactUpdates is called contactUpdates. It has the following arguments:

	- accountId: `String`
	The id of the account used for the call.
	- oldState: `String`
	This is the sinceState argument echoed back; the state from which the server is returning changes.
	- newState: `String`
	This is the state the client will be in after applying the set of changes to the old state.
	- hasMoreUpdates: `Boolean`
	If `true`, the client may call getContactUpdates again with the newState returned to get further updates. If `false`, newState is the current server state.
	- changed: `String[]`
	An array of Contact ids where a property of the contact has changed between the old state and the new state, or the contact has been created, and the contact has not been destroyed.
	- removed: `String[]`
	An array of Contact ids for contacts which have been destroyed since the old state.

	If a maxChanges is supplied, or set automatically by the server, the server must try to limit the number of ids across changed and removed to the number given. If there are more changes than this between the client's state and the current server state, the update returned MUST take the client to an intermediate state, from which the client can continue to call getContactUpdates until it is fully up to date. The server MAY return more ids than the maxChanges total if this is required for it to be able to produce an update to an intermediate state, but it SHOULD try to keep it close to the maximum requested.

	If a contact has been modified AND deleted since the oldState, the server should just return the id in the removed array, but MAY return it in the changed array as well. If a contact has been created AND deleted since the oldState, the server SHOULD remove the contact id from the response entirely, but MAY include it in the removed array, and optionally the changed array as well.

	The following errors may be returned instead of the `contactUpdates` response:

	`accountNotFound`: Returned if an accountId was explicitly included with the request, but it does not correspond to a valid account.

	`accountNoContacts`: Returned if the accountId given corresponds to a valid account, but does not contain any contacts data.

	`invalidArguments`: Returned if the request does not include one of the required arguments, or one of the arguments is of the wrong type, or otherwise invalid. A `description` property MAY be present on the response object to help debug with an explanation of what the problem was.

	`cannotCalculateChanges`: Returned if the server cannot calculate the changes from the state string given by the client. Usually due to the client's state being too old, or the server being unable to produce an update to an intermediate state when there are too many updates. The client MUST invalidate its Contact cache. The error object MUST also include a `newState: String` property with the current state for the type.

	### setContacts

	Modifying the state of Contact objects on the server is done via the setContacts method. This encompasses creating, updating and destroying Contact records.

	The setContacts method takes the following arguments:

	- accountId: `String\|null`
	The id of the account to use for this call. If `null`, the primary account will be used.
	- ifInState: `String\|null`
	This is a state string as returned by the getContacts method. If supplied, the string must match the current state, otherwise the method will be aborted and a `stateMismatch` error returned. If `null`, the change will be applied to the current state.
	- create: `String[Contact]\|null`
	A map of creation id (an arbitrary string set by the client) to Contact objects (containing all properties except the id).
	- update: `String[Contact]\|null`
	A map of id to a Contact object. The object may omit any property; only properties that have changed need be included.
	- destroy: `String[]\|null`
	A list of ids for Contact objects to permanently delete.

	Each create, update or destroy is considered an atomic unit. It is permissible for the server to commit some of the changes but not others, however it is not permissible to only commit part of an update to a single contact (e.g. update the firstName property but not the lastName property if both are supplied in the update object).

	If a create, update or destroy is rejected, the appropriate error should be added to the notCreated/notUpdated/notDestroyed property of the response and the server MUST continue to the next create/update/destroy. It does not terminate the method.

	If an id given cannot be found, the update or destroy MUST be rejected with a `notFound` set error.

	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.

	The response to setContacts is called contactsSet. It has the following arguments:

	- accountId: `String`
	The id of the account used for the call.
	- oldState: `String\|null`
	The state string that would have been returned by getContacts before making the requested changes, or `null` if the server doesn't know what the previous state string was.
	- newState: `String`
	The state string that will now be returned by getContacts.
	- created: `String[Contact]`
	A map of the creation id to an object containing the id property for all successfully created contacts.
	- updated: `String[]`
	A list of ids for contacts that were successfully updated.
	- destroyed: `String[]`
	A list of ids for contacts that were successfully destroyed.
	- notCreated: `String[SetError]`
	A map of creation id to a SetError object for each contact that failed to be created. The possible errors are defined in the description of the method for specific data types.
	- notUpdated: `String[SetError]`
	A map of Contact id to a SetError object for each contact that failed to be updated. The possible errors are defined in the description of the method for specific data types.
	- notDestroyed: `String[SetError]`
	A map of Contact id to a SetError object for each contact that failed to be destroyed. The possible errors are defined in the description of the method for specific data types.

	A SetError object has the following properties:

	- type: `String`
	The type of error.
	- description: `String\|null`
	A description of the error to display to the user.

	Other properties may also be present on the object, as described in the relevant methods.

	The following errors may be returned instead of the contactsSet response:

	`accountNotFound`: Returned if an accountId was explicitly included with the request, but it does not correspond to a valid account.

	`accountNoContacts`: Returned if the accountId given corresponds to a valid account, but does not contain any contacts data.

	`accountReadOnly`: Returned if the account has `isReadOnly == true`.

	`invalidArguments`: Returned if one of the arguments is of the wrong type, or otherwise invalid. A description property MAY be present on the response object to help debug with an explanation of what the problem was.

	`stateMismatch`: Returned if an ifInState argument was supplied and it does not match the current state.