Filtering

Filters can only be used when calling the HTTP GET method of the Contacts URI.

If you call GET without a filter, you get a response including all of the contacts from the authenticated user's list of contacts. If you call GET with a search filter, you get a response including a subset of the authenticated user's contacts.

Display filtering allows you to select specific information for each returned contact. Search and display filtering can be used independently or conjunctively.

Filters use criteria that include two components: a predefined set of keys and user-defined values.

The keys are case-sensitive, and the values for search filters have the following constraints:

  • Cannot contain commas, question marks, or forward slashes.
  • Cannot begin with a pound sign, an equal sign, a semicolon, or an angle bracket.
  • Cannot be a single exclamation mark.

Search Filtering

Using search filters, you can get Contact Objects in the response that match certain criteria.

Syntax

Search filters are appended to the URI for the Contacts API.

A URI with a search filter has the following syntax:

https://social.yahooapis.com/v1/user/{guid}/contacts;{field}.{condition}={var}

The field key represents a field or a category of a Contact Object. The condition key is an operand, such as contains, which sets a rule that must be satisfied for a Contact Object to be returned in the response.

The field key in the field.condition={var} pair may consist of the following:

  • Field Types
  • Name Fields
  • all - matches all field names in a Contact Object
  • category - matches the category name of the Category Object that is part of the Contact Object
  • all-but-category - matches all the field names of Contact Object, except the category name of Category Objects

The following table lists the allowed values for a condition key:

Table 3.1. Condition Keys

Condition Value Description
is Case-insensitive comparison of a Contact Object's field value with the given value of the search criteria.
startswith Case-insensitive comparison of the beginning of a Contact Object's field value with the given value of the search criteria.
contains Case-insensitive comparison of a substring in a Contact Object's field value with the given value of the search criteria.
cs-is Case-sensitive comparison of a Contact Object's field value with the given value of the search criteria (same as is).
cs-startswith Case-sensitive comparison of the beginning of a Contact Object's field value with the given value of the search criteria.
cs-contains Case-sensitive comparison of a substring in Contact Object's field value with the given value of the search criteria.
present If the given value is 1, match if the field is present in the Contact Object. If the given value is 0, match if the field is not present in the Contact Object.


Multiple Search Filters

Multiple search filters can be specified and joined logically. To indicate a logical AND, separate the filters with a semicolon. To specify a logical OR, separate the filters with a comma. The given value can be a string or an integer, but cannot be a series of comma-separated strings.

A URI with multiple search filters has the following syntax:

https://social.yahooapis.com/v1/user/{guid}/contacts;{field1}.{condition1}={var1};{field2}.{condition2}={var2},{field3}.{condition3}={var3}

Search Filter Examples
Getting Contacts by GUID:

Find a contact with the contact's GUID. The user's GUID is specified by {guid1}, and the contact's GUID is specified by {guid2}.

/v1/user/{guid1}/contacts;guid.is={guid2}?format=json

Getting Contacts by Name:

Find the contacts whose names contain the substring {var} and have an email address. The semicolon acts as an AND operator, so both conditions have to be true for a Contact Object to be returned.

/v1/user/{guid}/contacts;name.contains={var};email.present=1?format=json

Getting Contacts of a Company:

Find the contacts who work at the company name that starts with {var1} and whose user names begin with {var2}.

/v1/user/{guid}/contacts;company.startswith={var1};name.startswith={var2}

Getting Contacts by Name and Phone Number:

Find a contact whose first name contains {var1} or whose last name contains {var2} and who has a phone number that contains {var3}.

/v1/user/{guid}/contacts;first.contains={var1},last.contains={var2};phone.present=1;phone.contains={var3};

Getting Contacts Who Are Also Connections:

Use this URI to return a list of contacts who are also connections of the specified GUID. For example, suppose you have Jane's GUID and want to know which of her contacts are also her connections. Replace {guid} with Jane's GUID to return a collection of Jane's contacts who are also connections.

/v1/user/{guid}/contacts;connection.present=1

Display Filtering

Display filters are used with the HTTP GET method to obtain a subset of the fields for each returned Contact Object in the response.

Calling GET with search and display filters, you get a response that includes customized Contact Objects for the each of the authenticated user's contacts that satisfies the search criteria. Calling GET with only a display filter, you get a response that includes customized Contact Objects for all of the authenticated user's contacts.

Syntax

Display filters are appended to the URI for the Contacts API. The GUID of the user is represented by {guid} and {field1}, {field2}, and {field3} are the only fields of each Contact Objects in the returned response.

/v1/user/{guid}/contacts;out={field1},{field2},{field3}

The pair out and fields define the fields of the Contact Objects that will be returned in the response. The key fields can be one or more fields of the Contact Object, with each field being separated by a comma.

The fields key may consist of the following:

  • A comma-separated list of Field Types to return. If the fields parameter is omitted, all fields are returned.
  • all - include all fields. The default is to include all fields if no fields key is given.

Display Filter Examples
Getting the Name, the Nickname, and the Phone Numbers of Contacts:

Return only the name, nickname, and phone fields of the Contact Objects in the response:

/v1/user/{guid}/contacts;out=name,nickname,phone

Return All Fields for Each Contact:

Return all fields for each Contact Objects in the response. If no {field} is specified in the key-value pair out={field}, all fields for each Contact Objects are also returned in the response.

/v1/user/{guid}/contacts;out=all

Example Responses

The following responses are returned when making a GET call to the following URL:

v1/user/{guid}/contacts;out=nickname,name,phone

XML Example Response

JSON Example Response

Table of Contents