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 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.

https://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:

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

Table of Contents