Graph API User

This document refers to an outdated version of Graph API. Please use the latest version.

Graph API Version

v2.2

User

A user represents a person on Facebook. The /{user-id} node returns a single user.

Reading

Returns a single user node

Examples

Graph API Explorer

GET /v2.2/{user-id} HTTP/1.1
Host: graph.facebook.com

/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'GET',
  '/{user-id}'
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */

/* make the API call */
FB.api(
    "/{user-id}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* 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
}];

/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{user-id}",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();

If you want to learn how to use the Graph API, read our Using Graph API guide.

Fields

Field	Description
`id` numeric string	The id of this person's user account. This ID is unique to each app and cannot be used across different apps. Our upgrade guide provides more information about app-specific IDs Core Default
`about` string	The About Me section of this person's profile Default
`address` Location	The person's address Default
`age_range` AgeRange	The age segment for this person expressed as a minimum and maximum age. For example, more than 18, less than 21. Core
`bio` string	The person's bio Default
`birthday` string	The person's birthday. This is a fixed format string, like `MM/DD/YYYY`. However, people can control who can see the year they were born separately from the month and day so this string can be only the year (YYYY) or the month + day (MM/DD) Core Default
`context` UserContext	Social context for this person
`currency` Currency	The person's local currency information
`devices` list<UserDevice>	The list of devices the person is using. This will return only iOS and Android devices
`education` list<EducationExperience>	The person's education Default
`email` string	The person's primary email address listed on their profile. This field will not be returned if no valid email address is available Core Default
`favorite_athletes` list<Experience>	Athletes the person likes Default
`favorite_teams` list<Experience>	Sports teams the person likes Default
`first_name` string	The person's first name Core Default
`gender` string	The gender selected by this person, `male` or `female`. This value will be omitted if the gender is set to a custom value Core Default
`hometown` Page	The person's hometown Default
`inspirational_people` list<Experience>	The person's inspirational people Default
`install_type` enum	Install type
`installed` bool	Is the app making the request installed?
`interested_in` list<string>	Genders the person is interested in Default
`is_shared_login` bool	Is this a shared login (e.g. a gray user)
`is_verified` bool	People with large numbers of followers can have the authenticity of their identity manually verified by Facebook. This field indicates whether the person's profile is verified in this way. This is distinct from the `verified` field
`languages` list<Experience>	Facebook Pages representing the languages this person knows Default
`last_name` string	The person's last name Core Default
`link` string	A link to the person's Timeline Core Default
`location` Page	The person's current location as entered by them on their profile. This field is not related to check-ins Core Default
`locale` string	The person's locale Core Default
`meeting_for` list<string>	What the person is interested in meeting for Default
`middle_name` string	The person's middle name Core Default
`name` string	The person's full name Core Default
`name_format` string	The person's name formatted to correctly handle Chinese, Japanese, or Korean ordering
`payment_pricepoints` PaymentPricepoints	The person's payment pricepoints
`test_group` unsigned int32	Platform test group
`political` string	The person's political views Default
`relationship_status` string	The person's relationship status Default
`religion` string	The person's religion Default
`security_settings` SecuritySettings	Security settings
`significant_other` User	The person's significant other Default
`sports` list<Experience>	Sports this person likes Default
`quotes` string	The person's favorite quotes Default
`third_party_id` string	A string containing an anonymous, but unique identifier for the person. You can use this identifier with third parties
`timezone` float (min: -24) (max: 24)	The person's current timezone offset from UTC Core Default
`token_for_business` string	A token that is the same across a business's apps. Access to this token requires that the person be logged into your app. This token will change if the business owning the app changes
`updated_time` datetime	Updated time Default
`shared_login_upgrade_required_by` datetime	The time that the shared loginneeds to be upgraded to Business Manager by
`verified` bool	Indicates whether the account has been verified. This is distinct from the `is_verified` field. Someone is considered verified if they take any of the following actions: Register for mobile Confirm their account via SMS Enter a valid credit card Default
`video_upload_limits` VideoUploadLimits	Video upload limits
`viewer_can_send_gift` bool	Can the viewer send a gift to this person?
`website` string	The person's website Default
`work` list<WorkExperience>	Details of a person`s work experience Default
`public_key` string	The person's PGP public key
`cover` CoverPhoto	The person's cover photo

Edges

Edge	Description
`accounts`	Facebook Pages this person administers/is an admin for
`achievements`	Achievements made in Facebook games
`activities`	The activities listed on the person's profile
`adaccounts`	The advertising accounts to which this person has access
`adaccountgroups`	Reference document for using Facebook Marketing APIs to manage your ad account group
`adcontracts`	The person's ad contracts
`adnetworkanalytics`	Insights data for the person's Audience Network apps
`albums`	The photo albums this person has created
`apprequests`	This person's pending requests from an app
`apprequestformerrecipients`	App requests
`books`	The books listed on this person's profile
`domains`	The domains the user admins
`events`	Events for this person. By default this does not include events the person has declined or not replied to
`friendlists`	The person's custom friend lists
`ids_for_business`	Business entities can claim ownership of multiple apps using the Business Manager. This edge returns the list of IDs that this user has in any of those other apps
`invitable_friends`	A list of friends that can be invited to install a Facebook Canvas app
`games`	Games this person likes
`groups`	The Facebook Groups that the person belongs to
`interests`	The interests listed on the person's profile under Likes > Interests
`likes`	All the Pages this person has liked
`links`	This is similar to the `/feeds` node but only shows posts of type `link` and manually posted by the person
`movies`	Movies this person likes
`music`	Music this person likes
`objects`	Objects
`permissions`	The permissions that the person has granted this app
`photos`	Photos the person is tagged in or has uploaded
`picture`	The person's profile picture
`tagged_places`	List of tagged places for this person. It can include tags on videos, posts, statuses or links
`statuses`	This is similar to the `/feeds` node but only shows status update posts published by the person themselves
`taggable_friends`	Friends that can be tagged in content published via the Graph API
`television`	TV shows this person likes
`videos`	Videos the person is tagged in or uploaded
`video_broadcasts`	Video broadcasts from this person
`applications`	The Facebook apps that this person is a developer of.
`checkins`	The checkins this person has made.
`family`	This person's family relationships.
`feed`	The feed of posts (including status updates) and links published by this person.
`friendrequests`	A person's pending friend requests.
`friends`	A person's friends.
`home`	A person's Facebook homepage feed.
`inbox`	A person's Facebook Messages inbox.
`locations`	A feed of posts and photos that include location information and in which this person has been tagged. This is useful for constructing a chronology of places that the person has visited.
`mutualfriends`	The list of mutual friends between two people.
`notifications`	The unread Facebook notifications that a person has.
`outbox`	A person's Facebook Messages outbox.
`questions`	The questions that a person has created.
`scores`	The scores this person has received from Facebook Games that they've played.
`subscribers`	The profiles that are following this person.
`subscribedto`	The profile that this person is following.

Creating

You can't perform this operation on this endpoint.

You may perform a POST request to the following edges from this node:

Updating

You can update a User by making a POST request to /{user_id}.

Parameters

Name	Description
`id` int	The ID of this person's account Required
`password` string	Used for test accounts only. Password for this account
`name` string	Used for test accounts only. Name for this account
`firstname` string	This person's first name
`lastname` string	This person's last name
`label_cohort` Object	This person's label cohort
`ref` string

Return Type

Struct {

success: bool,

}

You can update a User by making a POST request to /{user_id}.

Parameters

Name	Description
`id` int	The ID of this person's account Required
`password` string	Used for test accounts only. Password for this account
`name` string	Used for test accounts only. Name for this account
`firstname` string	This person's first name
`lastname` string	This person's last name
`label_cohort` Object	This person's label cohort
`ref` string

Return Type

Struct {

success: bool,

}

You can update a User by making a POST request to /{custom_audience_id}/users.

Parameters

Name	Description
`id` numeric string	Custom Audience ID
`session` Object	[UNDOCUMENTED] Please write a sensible, developer-friendly description of what this field/param does
`session_type` enum{A, T, B}	Default value: `A`
`session_id` unsigned int32
`estimated_num_total` unsigned int32
`batch_seq` unsigned int32
`last_batch_flag` boolean
`payload` Object	Fields: schema, data,app_ids. e.g. payload = { "schema":"EMAIL_SHA256", "data":["HASH", "HASH", "HASH" ]} or payload = { "schema":"UID", "data":[123, 456, 789], "app_ids":[1111, 2222]}
`schema` string
`data` list<The type of this param is undocumented. If you are the owner of this param, please specify a developer-friendly type for it>
`app_ids` list<int>
`data_source` Object
`type` enum {UNKNOWN, FILE_IMPORTED, EVENT_BASED, SEED_BASED, THIRD_PARTY_IMPORTED, COPY_PASTE, CLAIM_BASED, CONTACT_IMPORTER}
`subtype` enum {ANYTHING, NOTHING, HASHES, USER_IDS, HASHES_OR_USER_IDS, MOBILE_ADVERTISER_IDS, EXTERNAL_IDS, MULTI_HASHES, WEB_PIXEL_HITS, MOBILE_APP_EVENTS, MOBILE_APP_COMBINATION_EVENTS, VIDEO_EVENTS, WEB_PIXEL_COMBINATION_EVENTS, ENGAGEMENT_EVENTS, CUSTOM_AUDIENCE_USERS, PAGE_FANS, CONVERSION_PIXEL_HITS, APP_USERS, S_EXPR, DYNAMIC_RULE, CAMPAIGN_CONVERSIONS, WEB_PIXEL_HITS_CUSTOM_AUDIENCE_USERS, MOBILE_APP_CUSTOM_AUDIENCE_USERS, COMBINATION_CUSTOM_AUDIENCE_USERS, REV_SHARE_CUSTOM_AUDIENCE_USERS, INTEREST_ENGAGERS, VIDEO_EVENT_USERS, MAIL_CHIMP_EMAIL_HASHES, CONSTANT_CONTACTS_EMAIL_HASHES, COPY_PASTE_EMAIL_HASHES, USER_PROPERTIES, CONTACT_IMPORTER}
`creation_params` JSON-encoded string

Return Type

Struct {

audience_id: numeric string,

session_id: numeric string,

num_received: int32,

num_invalid_entries: int32,

invalid_entry_samples: Map {

string: string

}

Deleting

Delete a test user

You can dissociate a User from a Page by making a DELETE request to /{page_id}/blocked.

Parameters

Name	Description
`id` int	Page ID Required
`uid` int	Deprecated. Same as `user`
`user` int	List of User or Page IDs to unblock. This or `uid` is required

Return Type

Struct {

success: bool,

}

You can delete a User by making a DELETE request to /{user_id}.

Parameters

Name	Description
`id` int	Test User ID Required

Return Type

Struct {

success: bool,

}