Contact

Description

A contact resource contains information about a user who is known, perhaps through an email exchange, to another user. Contacts are just like entries in an address book. The person who is listed as a contact does not have to give his or her approval. For example, Joe can add everyone from his school to his address book, and he does not need to ask each of them for permission to be added to his list of contacts.

URI

Use this URI to get a single resource for the user specified by {guid}. The {cid} is the ID. You can get IDs by running an HTTP GET operation to retrieve a collection of contacts. Then, you can extract the value of the {cid} field from each Contact Object in the collection. With the {cid} field, you can then run an HTTP GET operation to retrieve a single contact or run an HTTP DELETE operation to delete a single contact.

The Contacts section provides the details for obtaining the Contact Object.

This is the syntax for getting or deleting a specific contact with the {cid} for a specific GUID.

http://social.yahooapis.com/v1/user/{guid}/contact/{cid}

HTTP Operations Supported

  • GET
  • DELETE

Query Parameters Supported

  • format

Matrix Parameters Supported

Not available.

Scopes Required

  • GET: Read Yahoo! Contacts
  • DELETE: Write Yahoo! Contacts

Elements of the Contact Object

Not all elements may be present in a requested contact.

Element JSON Data Type XML Schema Data Type Required for Write? Read Only? Description
created string dateTime No Yes This is a system-generated response indicating the date that the object was created. The date is in RFC 3339 format. Example: Wed, 13 Aug 2008 21:24:09 GMT
updated string dateTime No Yes This is a system-generated response indicating the date that the object was modified. The date is in RFC 3339 format. Example: Wed, 13 Aug 2008 21:24:09 GMT
uri string anyURI No Yes A link to the actual resource.
isConnection boolean boolean No Yes Indicates whether there is a connection with the user specified by the {guid} in the call operation. Its values are true or false.
id number string No Yes The Contact's Id. This is the {cid} variable required in some resource endpoints. The CID is not the same as the contact's GUID and they are not interchangeable.
fields Field Object Field Object Yes No A collection of Field Objects. This is the actual data of the contact.
categories Category Object. Category Object No No This is a collection of key-value pairs, comma-separated and enclosed in curly brackets. For an example, see Category objects.

JSON Syntax for Contact Object

Example Responses for GET Contact

In the following responses, you can see the URIs which identify the exact location of each information block. You can use the URI to access specific fields for this contact. See the Single Field section for details.

The responses below consists of information blocks that include the contact, five fields, and any existing categories. In this case, there is only one Category Object: Clowns.

Example JSON Response Body for GET Contact

This example shows requests for a contact that is uniquely identified by the CID value 2.

http://social.yahooapis.com/v1/user/XYZUHL23NH5DGGGGXM/contact/2?format=json

Example XML Response Body for GET Single Contact

This example shows a request for a contact that is uniquely identified by CID value 2.

http://social.yahooapis.com/v1/user/XYZUHL23NH5DGGGGXM/contact/2?format=xml

Contact Validity Criteria

The following are data constraints. These constraints are enforced during a PUT or a POST operation. A response to a GET operation has the following constraints.

Data Constraint
Contacts per address book Maximum 5000
Categories per address book Maximum 1000
Fields per contact Maximum 48
Categories (including system) associated with a contact Maximum 32
Length of value of an unstructured field Maximum 4095 UTF-8 bytes
Length of components of a structured field Maximum 4095 UTF-8 bytes
Length of a category name Maximum 255 UTF-8 bytes
Range of year field in anniversary and birthday The year value must be between 1902 and 2037.
Content of email field The field must contain the @ character
Required fields for a Contact Object The object must contain at least one of the following fields: givenName (first), familyName (last), nickname,company,email,phone,yahooid,otherid. The otherid field can indicate a type of ID from the Contact Field Flags.
Number of yahooid fields Maximum allowed: 1
Multiplicity of GUID value No two contacts in the address book can share the same GUID value.
Content of category name The category name cannot be empty. It cannot contain any of the following characters: slashes, @, colons, semi-colons, brackets, parenthesis, less-than or greater-than signs, spaces, commas, single or double quotes

Table of Contents