Adding Information to the Address Book
The addContacts method adds one or more contacts to a
user's address book. The request contains a list of contacts to be added
to (or merged with) the user's Address Book. In response to the request,
Address Book servers attempt to uniquely add those contacts to the
Address Book.
The following is a POST request for adding or merging contacts into a user's address book:
The general format of an addContacts request is:
The Response is an entity of type add-response
containing responses to the individual addition operations in the same
order as they appeared in the Request:
Add Conditions
For each contact being added, one of the four conditions can occur:
- Contact was not valid
- Contact was added without duplication
- Contact was merged with an existing contact
Contact was not valid
The contact cannot be added because it is not valid (see General Validity Constraints).
The Response contains an error entry.
Error entities are standard error responses relating to
the particular operation (see the Error Reporting section):
Contact was added without duplication
The contact can be added without causing any contact
duplication The Response contains a contact entry with
add-action set to "add":
Contact was merged with an existing contact
The contact can be reliably merged with an existing contact.
The Response will contain a contact entry with
add-action set to "merge".
Examples
In the following example, the user wants to add two contacts into a category named "Friends", which might be a new category.
In the following response, the first contact was merged with an existing contact in the address book. The second contact was added. In both cases, the resulting contact is returned with an additional property "add-action" indicating "merge" or "add" respectively.
Note
In the above Response, the category entity is
qualified with catid (the category-ID). The category
"Friends" either already existed, or it has just been created as
needed for this add/merge operation.