Graph API Version

User Context - All Mutual Friends

Feature Review: Platform Limitation

The All Mutual Friends API must be called from your server to obtain the full list of mutual friends. Calling this API in JavaScript, Android, or iOS client code will omit some of the results.

Learn more about Feature Review

Reading

All friends that the viewer and the target person have in common. This includes the friends who do not use your app

Returns a list of all the Facebook friends that the session user and the request user have in common. This includes friends who use the app as well as non-app-using mutual friends.

Permissions

  • A valid user access token with user_friends permission is required to view the mutual friends of other friends using the app.
  • The user in the request and the session user must both have granted user_friends permission to the app.
  • The ID will be returned for a mutual friend only if the given user has installed your app and granted the user_friends permission
  • If you want to call this endpoint on behalf two app-users who are not friends, then you must provide the appsecret_proof parameter along with the user access token when making the request. This means you must call this endpoint from your server.
  • Usage of the this field requires review by Facebook before it can be used by in production by non-developers of your app.

Fields

This API returns an array of LimitedProfile nodes - each representing a mutual friend. If the mutual friend has logged into your app and granted the user_friends permission, and ID parameter will be present containing the ID of that user in your app. This may be the original Facebook User ID or an App-Scoped ID depending on how that user is known to your app. If the user has not logged into your app, the ID will not be present.

Modifiers

By default, the API returns up to five mutual friends including a token, name and profile picture URL for each.

You can modify the number of mutual friends returned using the limit modifier:

GET /v2.10/{user-id}?fields=context.fields%28all_mutual_friends.limit%28100%29%29 HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'GET',
  '/{user-id}',
  array (
    'fields' => 'context.fields(all_mutual_friends.limit(100))',
  )
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */
/* make the API call */
FB.api(
    "/{user-id}",
    {
        "fields": "context.fields(all_mutual_friends.limit(100))"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("fields", "context.fields(all_mutual_friends.limit(100))");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{user-id}",
    params,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"fields": @"context.fields(all_mutual_friends.limit(100))",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{user-id}"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

By default, the profile picture returned is a 50x50 pixel jpeg image. If you want to modify the size of this image, you can do so with the height and width modifiers:

GET /v2.10/{user-id}?fields=context.fields%28all_mutual_friends.fields%28picture.width%28500%29.height%28200%29%29%29 HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'GET',
  '/{user-id}',
  array (
    'fields' => 'context.fields(all_mutual_friends.fields(picture.width(500).height(200)))',
  )
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */
/* make the API call */
FB.api(
    "/{user-id}",
    {
        "fields": "context.fields(all_mutual_friends.fields(picture.width(500).height(200)))"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("fields", "context.fields(all_mutual_friends.fields(picture.width(500).height(200)))");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{user-id}",
    params,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"fields": @"context.fields(all_mutual_friends.fields(picture.width(500).height(200)))",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{user-id}"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

The API will return a pre-cached image who's dimentions most closely match those you specify. The image may not have the exact dimentions you specify.

Basic Call

Graph API Explorer
GET /v2.10/{user-context-id}/all_mutual_friends HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'GET',
  '/{user-context-id}/all_mutual_friends'
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */
/* make the API call */
FB.api(
    "/{user-context-id}/all_mutual_friends",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{user-context-id}/all_mutual_friends",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{user-context-id}/all_mutual_friends"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Feature Permissions

NameDescription
all_mutual_friendsThis is a required feature permission

Parameters

This endpoint doesn't have any parameters.

Fields

Reading from this edge will return a JSON formatted result:

{ "data": [], "paging": {}, "summary": {} }

data

A list of LimitedFriend nodes.

paging

For more details about pagination, see the Graph API guide.

summary

Aggregated information about the edge, such as counts. Specify the fields to fetch in the summary param (like summary=total_count).

FieldDescription

total_count

unsigned int32

Total number of mutual friends

Validation Rules

ErrorDescription
100Invalid parameter

Creating

You can't perform this operation on this endpoint.

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.