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.

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

Query Parameters Supported

  • format
  • view
  • start
  • count

Note

For paging with filters, use start and count as matrix parameters.

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.

See also: Filtering Contacts

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.

See also JSON Syntax for Contact Object.

See also Example JSON Response Body for GET Contacts.

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

Example XML Response for GET Contacts

JSON Example of Contact Object

This example illustrates the a JSON example for a single contact object.

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.

XML Example of Contact Object

This example illustrates the structure of an XML response for a single contact object.

JSON Syntax for Contacts Object for POST Contact

Example JSON Request Body for POST Contact

Example XML Request Body for POST Contact

Table of Contents