Contacts

Description

With the Contacts API, you can obtain and add to the a collection of resources that represent a user's contacts. To retrieve contacts of contacts you will need a separate operation and each contact owner's permission.

When you run a GET operation on this resource, you obtain a collection of Contact Objects. Along with other information, each Contact Object contains identifiers such as {cid} (Contact ID), {category-name}, and {fid} (Field ID). You will need these identifiers in other URIs provided by the Contacts API.

When you run a POST operation on this resource, a Contact Object is written to the URI, thus adding a new contact for the user specified by the GUID value. The POST operation sends a request in XML or JSON with the new contact's information. Write access to the Contacts API must be requested through the YDN Contact Form.

URI

Use the following URI to obtain Contact Objects or add a Contact Object for a user identified by the {guid} value.

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

HTTP Operations Supported

GET
POST
PUT

Query Parameters Supported

format
view

Allowed values for the view parameter:

Matrix Parameters Supported

If count is not specified, the Contacts API will return 10 contacts. To get the entire list of contacts, use count=max.

Scopes Required

GET: Read Yahoo! Contacts
POST: Write Yahoo! Contacts
PUT: Write Yahoo! Contacts

Elements of the Contacts Object

When you make a JSON request for a collection of contacts, the information will be returned as an array of Contact Objects.

Element	JSON Data Type	XML Schema Data Type	Description
`start`	number	nonNegativeInteger	Index of the first contact returned.
`count`	number	nonNegativeInteger	Number of contacts returned.
`total`	number	nonNegativeInteger	Total number of contacts available.
`uri`	string	anyURI	A link to the actual resource.
`created`	string	dateTime	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	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`
`contact`	array of Contact Objects	Zero or more Contact Objects	A collection of Contacts Objects.

JSON Syntax for Contacts Object for GET

Example JSON Response for GET Contacts

{  
  "contacts": 
  {    
    "start": 0,    
    "count": 10,    
    "total": 172,    
    "uri": "http:\/\/social.yahooapis.com\/v1\/user\/ZZIDWJNWVNQD4GXZ5NGMZUSTQ4\/contacts",    
    "contact": 
    [      
      {        
        "uri": "http:\/\/social.yahooapis.com\/v1\/user\/ZZIDWJNWVNQD4GXZ5NGMZUSTQ4\/contact\/378",        
        "created": "2009-02-02T00:47:11Z", 
        "updated": "2009-07-15T18:07:16Z",
        "isConnection": false, 
        "id": 378,
        "fields": 
        [ 
          {
            "uri": "http:\/\/social.yahooapis.com\/v1\/user\/ZZIDWJNWVNQD4GXZ5NGMZUSTQ4\/contact\/378\/guid\/819",
            "created": "2009-02-02T00:47:11Z",
            "updated": "2009-07-15T18:07:16Z",
            "id": 819,
            "type": "guid",
            "value": "ZZB6FCEBZO3MDCUQQNNEFIBWMA",
            "editedBy": "OWNER",
            "flags": [ ], 
            "isConnection": false 
          },
          ...
        ]     
        "categories": 
        [ 
          { 
            "uri": "http:\/\/social.yahooapis.com\/v1\/user\/ZZIDWJNWVNQD4GXZ5NGMZUSTQ4\/contact\/209\/category\/Yahoo!",
            "created": "2009-10-01T17:09:09Z",
            "updated": "2009-10-01T17:10:02Z",
            "id": 483,
            "name": "Yahoo!"
          },
          ...
        ]      
      },
      ...  
    ]  
  }
}

Example XML Response for GET Contacts

<contacts xmlns="http://social.yahooapis.com/v1/schema.rng" xmlns:yahoo="http://www.yahooapis.com/v1/base.rng" yahoo:start="0" yahoo:count="10" yahoo:total="172" yahoo:uri="http://social.yahooapis.com/v1/user/ZZIDWJNWVNQD4GXZ5NGMZUSTQ4/contacts">
  <contact yahoo:uri="http://social.yahooapis.com/v1/user/ZZIDWJNWVNQD4GXZ5NGMZUSTQ4/contact/378" yahoo:created="2009-02-02T00:47:11Z" yahoo:updated="2009-07-15T18:07:16Z">
    <isConnection>false</isConnection>
    <id>378</id>
    <fields yahoo:uri="http://social.yahooapis.com/v1/user/ZZIDWJNWVNQD4GXZ5NGMZUSTQ4/contact/378/guid/819" yahoo:created="2009-02-02T00:47:11Z" yahoo:updated="2009-07-15T18:07:16Z">
      <id>819</id>
      <type>guid</type>
      <value>ZZB6FCEBZO3MDCUQQNNEFIBWMA</value>
      <editedBy>OWNER</editedBy>
      <isConnection>false</isConnection>
    </fields>
    <fields yahoo:uri="http://social.yahooapis.com/v1/user/ZZIDWJNWVNQD4GXZ5NGMZUSTQ4/contact/378/name/818" yahoo:created="2009-02-02T00:47:11Z" yahoo:updated="2009-02-02T00:47:11Z">
      <id>818</id>
      <type>name</type>
      <value>
        <givenName>echo</givenName>
        <middleName/>
        <familyName>&quot;mich&quot;;</familyName>
        <prefix/>
        <suffix/>
        <givenNameSound/>
        <familyNameSound/>
      </value>
      <editedBy>OWNER</editedBy>
    </fields>
  </contact>
  ...
</contacts>

Example JSON Response for GET Single Contact

This example illustrates the structure of a JSON response for a single contact object. To make this request, you only need to provide your own GUID and specify the format JSON with the following URL:

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

This is a partial listing that shows only two fields and the contact's categories. The fields are nickname and address.

You should observe the following information items about the contact.

The contact is not a connection because the isConnection field value is false.
The first id value, 2, is the CID. (Note: The id tag provides different information, depending on its placement. It may represent a CID or a FID value.)

About the first Field Object:
- The uri value states the location of this field resource.
- The id value is 1. This is its FID value.
- The field type is nickname and its value is HeadClown.

About the second Field Object:
- The field type is address. Its values are subfields that define the contact's residence address.
- The flags field value is HOME. If the contact has more than one address, the flags value will help to distinguish them.

About the Category Object:
- There is only one category, and this contact is placed under the category name CLOWNS.

{  
  "contact": 
  {    
   "uri":
 "http:\/\/social.yahooapis.com\/v1\/user\/XYZUHL23NH5DGGGGXM\/contact\/2",
    "created": "2008-08-28T01:07:55Z",    
    "updated": "2009-07-15T18:07:16Z",    
    "isConnection": false,    
    "id": 2,    
    "fields": 
    [      
      {        
        "uri": "http:\/\/social.yahooapis.com\/v1\/user/XYZUHL23NH5DGGGGXM\/contact\/2\/nickname\/1",
        "created": "2008-08-28T01:07:55Z",
        "updated": "2008-08-28T01:07:55Z", 
        "id": 1,
        "type": "nickname",
        "value": "HeadClown",   
      },      
      {        
        "uri":
"http:\/\/social.yahooapis.com\/v1\/user\/XYZUHL23NH5DGGGGXM\/contact\/2\/address\/6",
        "created": "2008-08-28T01:07:55Z",
        "updated": "2008-08-28T01:07:55Z",
        "id": 6,
        "type": "address",
        "value": 
        { 
          "street": "1234",
          "city": "NowheresVille",
          "stateOrProvince": "ca",
          "postalCode": "91234",
          "country": "usa",
      }
      "flags":
      [
        {
          "HOME"
        }
      ]  
    }      
    "categories": 
    [
      {
        "created": "2008-08-28T01:05:17Z",
        "updated": "2008-08-28T01:07:55Z",
        "id": "1",
        "name": "Clowns",
        "uri": "http://social.yahooapis.com/v1/user/XYZUHL23NH5DGGGGXM/contact/2/category/Clowns"
      }  
    ]  
  }
}

Example XML Response for GET Single Contact

This example illustrates the structure of an XML response for a single contact object. To make this request, you only need to provide your own GUID. Since the format is not specified, the response will be in XML, which is the default.

http://social.yahooapis.com/v1/user/XYZUHL23NH5DGGGGXM/contacts

<yahoo:created="2008-08-28T01:07:55Z"
         yahoo:updated="2008-08-28T01:07:55Z"
         yahoo:uri="http://social.yahooapis.com/v1/user/XYZUHL23NH5DGGGGXM/contact/2"
         xmlns="http://social.yahooapis.com/v1/schema.rng"
         xmlns:yahoo="http://www.yahooapis.com/v1/base.rng"
         xmlns:ns="http://social.yahooapis.com/v1/schema.rng">
  <isConnection>false</isConnection>
  <id>2</id>
  <fields yahoo:created="2008-08-28T01:07:55Z"
          yahoo:updated="2008-08-28T01:07:55Z"
          yahoo:uri="http://social.yahooapis.com/v1/user/XYZUHL23NH5DGGGGXM/contact/2/nickname/1">
    <id>1</id>
    <type>nickname</type>
    <value>HeadClown</value>
  </fields>
  <fields yahoo:created="2008-08-28T01:07:55Z"
          yahoo:updated="2008-08-28T01:07:55Z"
          yahoo:uri="http://social.yahooapis.com/v1/user/XYZUHL23NH5DGGGGXM/contact/2/address/6">
    <id>6</id>
    <type>address</type>
    <value>
      <street>1234</street>
      <city>NowheresVille</city>
      <stateOrProvince>ca</stateOrProvince>
      <postalCode>91234</postalCode>
      <country>usa</country>
    </value>
    <flags>HOME</flags>
  </fields>
  <categories yahoo:created="2008-08-28T01:05:17Z" 
              yahoo:id="1"
              yahoo:name="Clowns" 
              yahoo:updated="2008-08-28T01:07:55Z"
              yahoo:uri="http://social.yahooapis.com/v1/user/XYZUHL23NH5DGGGGXM/contact/2/category/Clowns" 
              />
</contact>