Single Field

Description

Use these URIs to access a single specific field resource containing information about a contact. Using an HTTP GET operation on any of these URIs, you can obtain a specific field from the contact's information. You identify the contact with the {cid} variable, and you specify the field you want with the {fid} variable. Examples of this field-level information are a contact's nickname, address, or email. Using an HTTP DELETE operation on any of these URIs with the {cid} and {fid} variables, you can delete a single field from the contact's information.

These resources can be especially useful when a specified CID has multiples for any of its entries (such as address, anniversary, name, etc.). Use these resources to distinguish between the multiple fields of any such entry. This allows you to distinguish between users (such as husband and wife, as well as their family) when they share a single profile.

If you need to get all of the fields for a contact rather than the single field access provided by these URIs, see the Multiple Fields section.

URIs

Each of the following URIs points to a single Field resource. You will need the {cid} Contact ID and the {fid} Field ID from a Contact Object. Run an HTTP GET operation to obtain a Contact Object. The Contacts section provides the details for obtaining the Contact Object.

http://social.yahooapis.com/v1/user/{guid}/contact/{cid}/address/{fid}
http://social.yahooapis.com/v1/user/{guid}/contact/{cid}/anniversary/{fid}
http://social.yahooapis.com/v1/user/{guid}/contact/{cid}/birthday/{fid}
http://social.yahooapis.com/v1/user/{guid}/contact/{cid}/company/{fid}
http://social.yahooapis.com/v1/user/{guid}/contact/{cid}/custom/{fid}
http://social.yahooapis.com/v1/user/{guid}/contact/{cid}/email/{fid}
http://social.yahooapis.com/v1/user/{guid}/contact/{cid}/guid/{fid}
http://social.yahooapis.com/v1/user/{guid}/contact/{cid}/jobTitle/{fid}
http://social.yahooapis.com/v1/user/{guid}/contact/{cid}/link/{fid}
http://social.yahooapis.com/v1/user/{guid}/contact/{cid}/name/{fid}
http://social.yahooapis.com/v1/user/{guid}/contact/{cid}/nickname/{fid}
http://social.yahooapis.com/v1/user/{guid}/contact/{cid}/notes/{fid}
http://social.yahooapis.com/v1/user/{guid}/contact/{cid}/otherid/{fid}
http://social.yahooapis.com/v1/user/{guid}/contact/{cid}/phone/{fid}
http://social.yahooapis.com/v1/user/{guid}/contact/{cid}/yahooid/{fid}

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 Field Object

Element	JSON Data Type	XML Schema Data Type	Required for Write?	Read Only?	Description
`id`	string	string	No	Yes	Field ID. This is the {fid} value that some resource endpoints require.
`uri`	string	anyURI	No	Yes	A link to the actual resource.
`created`	string	dateTime	No	Yes	Date resource was created.
`updated`	string	dateTime	No	Yes	Date resource was last modified.
`type`	Field Type	Field Type	Yes	No	See Field Types for a list of valid string values.
`value`	string or Field Object	string or Field Object	Yes	No	The field value will be a field type or an object for structured fields.
`flags`	Array of Field Flags	string	No	No	List of Field Flags (strings). See Field Flags for the list of valid string values.
`title`	string	string	No	No	The field title (only present if the value of `type` is set to `"custom"`).
`isConnection`	boolean	boolean	No	Yes	Specifies whether the GUID owner is connected to the GUID specified in this Field Object. (only present if the value of `type` is set to `"guid"`).
`nickname`	string	string	No	No	Display name from GUID's tinyusercard (only present if the value of `type` is set to `"guid"` and the endpoint specifies "`contacts?view=tinyusercards`").
`image`	Image Object	imageContent	No	No	This is a structured data type that contains the sizing information for an image. The image is the display photo URI from GUID's tinyusercard (only present if the value of `type` is set to `"guid"` and the endpoint specifies "`contacts?view=tinyusercards`").

JSON Syntax for Field Object

Contact Field Types

The list of values is an enumeration, so the listed values have no other data type associated with them.

The type field, which is found in a Field Object, will be one of the values in the following table.

See also the list of Contact Plural Fields.

Singular Field	Description
`guid`	The contact's GUID.
`nickname`	The contact's nickname.
`email`	The contact's email.
`yahooid`	Yahoo! ID.
`otherid`	Other identifiers, such as ICQ, etc., distinguished by flags (see Contact Field Flags).
`phone`	Phone number; use flags for type.
`jobtitle`	The contact's job title.
`company`	Company name.
`notes`	Comments about the Contact.
`link`	A URL.
`custom`	A custom field created with Yahoo Address Book, `Add a Custom Field` dialog.
`name`	A name.
`address`	A postal address.
`birthday`	A birthday.
`anniversary`	An anniversary.

Structured Field Data Types

Some fields are structured objects. A structured object is a data type that consists of more than one field. For example, an Address Object is a structured object that consists of several fields, each of which is a string. The individual strings contain information such as street, city, state and so forth.

An unstructured field is a simple, non-compound type. For example, the Field Object contains a title field, the value of which is nothing more than a string such as "My Greatest Moments." See also Field Types.

This table provides a summary of the structured field data types.

Data Type	JSON Object	XML Object	Description
`address`	JSON Syntax for Address Field Values	XML Address Structure	This is a structured type composed of string values that provide the address details. At least one field must be filled in.
`anniversary`	JSON Syntax for Anniversary Field Values	XML Anniversary Structure	This is a structured type composed of string values that provide the anniversary details. At least one field must be filled in.
`birthday`	JSON Syntax for Birthday Field Values	XML Birthday Structure	This is a structured type composed of string values that provide the birthday details. At least one field must be filled in.
`name`	JSON Syntax for Name Field Values	XML Name Structure	This is a structured type composed of string values that accept the individual's name components. At least one field must be filled in.

JSON Syntax for Address Field Values

The address field is a structured type based on a RELAX NG schema. It can contain the following values. At least one field must be non-empty.

XML Syntax for Address Field Values

This example illustrates the XML layout of the address structure. It can contain the following values. At least one field must be non-empty.

JSON Syntax for Anniversary Field Values

The anniversary is a structured field. If all the anniversary date information is provided, it will contain the following fields. If a field is not defined, it will not be returned.

Example of XML Anniversary Field Values

This example illustrates the XML layout of the anniversary structure.

JSON Syntax for Birthday Field Values

The birthday field is a structured field. It must contain the following fields.

Example of XML Birthday Field Values

This example illustrates the XML layout of the birthday structure.

JSON Syntax for Name Field Values

The name field is a structured field. At least one component must be non-empty.

XML Syntax for Name Field Values

Field Flag

Use a Field Flag to help clarify the type of data. Flags have no intrinsic meaning, and it is up to the user to apply them. For example, when a profile has multiple phone entries, each entry can use a flag (such as MOBILE, WORK, FAX, and so forth) to distinguish the entries. However, there is no verification that the flags actually represent the implied type of device.

The following flags are contained in a Field Object. These are the allowed values in the Flags array of strings. You may use zero or more flags.

XML Syntax for Image Object

JSON Syntax for GET Field Type

This is the response format for a specific field. The Field Type must be one of the values listed in Contact Field Types For a fully detailed example, see Example of JSON Response Body for GET Field.

Example Responses for GET Field

These examples show the response returned when making a request for the nickname field. These requests are for a FID whose value is 1, indicating the nickname field.

The response body is for a single field and reveals that the particular contact (uniquely identified by CID 2) is known by the nickname HeadClown.

Example of JSON Response Body for GET Field

To get the requested information in JSON format, you must explicitly make your request as shown here.

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

Example XML Response Body for GET Field

This example shows the XML response body returned when making a request for the nickname field with the following URI:

http://social.yahooapis.com/v1/user/XYZUHL23NH5DGGGGXM/contact/2/nickname/1