Graph API User - Documentation - Facebook for Developers

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

Graph API Version

v2.5

User

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

Reading

Returns a single user node

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps

ads_management
manage_pages
publish_pages

Page management Apps

manage_pages

Other Apps

Permissions are not usually requested.

Examples

Graph API Explorer

GET /v2.10/{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 */
      }
    }
);

/* 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();

// 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
}];

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

Parameters

This endpoint doesn't have any parameters.

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
`about` string	Equivalent to the `bio` field
`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	A short bio, found on a person's profile in the "About This Person" section Deprecated
`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
`context` UserContext	Social context for this person
`cover` CoverPhoto	The person's cover photo
`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
`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
`employee_number` string	The person's employee number, as set by the company via SCIM API
`favorite_athletes` list<Experience>	Athletes the person likes
`favorite_teams` list<Experience>	Sports teams the person likes
`first_name` string	The person's first name Core
`gender` string	The gender selected by this person, `male` or `female`. If the gender is set to a custom value, this value will be based off of the preferred pronoun; it will be omitted if the preferred preferred pronoun is neutral Core
`hometown` Page	The person's hometown
`inspirational_people` list<Experience>	The person's inspirational people
`install_type` enum	Install type
`installed` bool	Is the app making the request installed?
`interested_in` list<string>	Genders the person is interested in
`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
`last_name` string	The person's last name Core
`link` string	A link to the person's Timeline Core
`local_news_megaphone_dismiss_status` bool	Display megaphone for local news bookmark Deprecated
`locale` string	The person's locale Core
`location` Page	The person's current location as entered by them on their profile. This field is not related to check-ins Core
`meeting_for` list<string>	What the person is interested in meeting for
`middle_name` string	The person's middle name Core
`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
`political` string	The person's political views
`public_key` string	The person's PGP public key
`quotes` string	The person's favorite quotes
`relationship_status` string	The person's relationship status
`religion` string	The person's religion
`security_settings` SecuritySettings	Security settings
`shared_login_upgrade_required_by` datetime	The time that the shared loginneeds to be upgraded to Business Manager by
`significant_other` User	The person's significant other
`sports` list<Experience>	Sports played by the person
`test_group` unsigned int32	Platform test group
`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
`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 or have a role on your app. This token will change if the business owning the app changes
`updated_time` datetime	Updated time
`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
`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
`work` list<WorkExperience>	Details of a person`s work experience

Edges

Edge	Description
`accounts`	Facebook Pages this person administers/is an admin for
`achievements`	Achievements made in Facebook games
`ad_studies`	Ad studies that this person can view
`adaccountgroups`	Ad account groups
`adaccounts`	The advertising accounts to which this person has access
`adcontracts`	The person's ad contracts
`admined_groups`	Groups the user admins
`adnetworkanalytics`	Insights data for the person's Audience Network apps
`albums`	The photo albums this person has created
`apprequestformerrecipients`	App requests
`apprequests`	This person's pending requests from an app
`books`	The books listed on this person's profile
`business_activities`	The business activities related to this user
`business_users`	Business users corresponding to the user
`businesses`	Businesses associated with the user
`conversations`	Facebook Messenger conversation
`curated_collections`	The curated collections created by this user
`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
`family`	This person's family relationships.
`favorite_requests`	Developers' favorite requests to the Graph API
`friendlists`	The person's custom friend lists
`friends`	A person's friends.
`games`	Games this person likes
`groups`	The Facebook Groups that the person is an admin of
`ids_for_business`	Businesses can claim ownership of multiple apps using 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
`likes`	All the Pages this person has liked
`live_videos`	Live videos from this person
`movies`	Movies this person likes
`music`	Music this person likes
`objects`	Objects
`permissions`	The permissions that the person has granted this app
`personal_ad_accounts`	The advertising accounts to which this person has personal access
`photos`	Photos the person is tagged in or has uploaded
`picture`	The person's profile picture
`promotable_domains`	All the domains user can promote
`promotable_events`	All the events which user can promote.
`request_history`	Developers' Graph API request history
`session_keys`	Any session keys that the app knows the user by
`stream_filters`	A list of filters that can be applied to the News Feed edge
`taggable_friends`	Friends that can be tagged in content published via the Graph API
`tagged_places`	List of tagged places for this person. It can include tags on videos, posts, statuses or links
`television`	TV shows this person likes
`threads`	A message conversation thread
`video_broadcasts`	Video broadcasts from this person
`videos`	Videos the person is tagged in or uploaded
`checkins`	The checkins this person has made.
`feed`	The feed of posts (including status updates) and links published by this person.
`friendrequests`	A person's pending friend requests.
`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.

Validation Rules

Error	Description
100	Invalid parameter
200	Permissions error
210	User not visible
110	Invalid user id
452	Session key invalid. This could be because the session key has an incorrect format, or because the user has revoked this session
289	Accessing friend requests requires the extended permission read_requests
278	Reading advertisements requires an access token with the extended permission ads_read
3001	Invalid query
1157	Sorry, but we're having trouble processing a payment on this app. The user has not been charged for this transaction and has been asked to try again.
294	Managing advertisements requires an access token with the extended permission for ads_management

Creating

You can't perform this operation on this endpoint.

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

Validation Rules

Error	Description
200	Permissions error
100	Invalid parameter
240	Desktop applications cannot call this function for other users
368	The action attempted has been deemed abusive or is otherwise disallowed
195	The name you are trying to use is invalid
210	User not visible

Updating

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

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps

No data

Page management Apps

No data

Other Apps

Permissions are not usually requested.

Parameters

Name	Description
`emoji_color_pref` int64	emoji color preference.
`firstname` string	This person's first name
`label_cohort` Object	This person's label cohort
`ref` string
`lastname` string	This person's last name
`local_news_megaphone_dismiss_status` enum {YES, NO}	Dismisses local news megaphone
`local_news_subscription_status` enum {STATUS_ON, STATUS_OFF}	Preference for setting local news notifications
`name` string	Used for test accounts only. Name for this account
`password` string	Used for test accounts only. Password for this account

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.

Struct {

success: bool,

}

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

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps

No data

Page management Apps

No data

Other Apps

Permissions are not usually requested.

Parameters

Name	Description
`emoji_color_pref` int64	emoji color preference.
`firstname` string	This person's first name
`label_cohort` Object	This person's label cohort
`ref` string
`lastname` string	This person's last name
`local_news_megaphone_dismiss_status` enum {YES, NO}	Dismisses local news megaphone
`local_news_subscription_status` enum {STATUS_ON, STATUS_OFF}	Preference for setting local news notifications
`name` string	Used for test accounts only. Name for this account
`password` string	Used for test accounts only. Password for this account

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.

Struct {

success: bool,

}

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

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps

ads_management

Page management Apps

No data

Other Apps

No data

Parameters

Name	Description
`namespace` string	If extern_id provided and namespace specified, will match under specified namespace and update the mapping if necessary and pass permission check
`payload` Object	Payload representing users to add
`schema` string	`UID`, `EMAIL_SHA256`, `PHONE_SHA256`, `MOBILE_ADVERTISER_ID`. One can also pass an array of multiple keys for multi-key match. Supported key types includes: `EXTERN_ID` `EMAIL` `PHONE` `GEN` `DOBY` `DOBM` `DOBD` `LN` `FN` `FI` `CT` `ST` `ZIP` `MADID` `COUNTRY` The multi-key array is of the form `["EMAIL", "LN", "FN", "ZIP"]`
`is_raw` boolean	Is the key raw? If the keys are combinational keys like "LN_FN_ZIP", set this to `false`, otherwise set this to `true`. Default to false
`data` list<JSON array>	Array with users data. If the multi-key feature is used, a two-dimensional array of the form `[["test1@example.com", "john", "smith", "95124"], ["", "lucy", "brown", "95124"]]` should be passed. In case a key is unknown, it should be left blank.
`app_ids` list<int>	App ids used by the users being uploaded. This field is required when `schema` is a Facebook UID and the IDs were collected by an App integration. e.g. `[1234,5678]`
`page_ids` list<Page ID>	Page ids used by the users being uploaded. This field is required when `schema` is a Facebook UID and the IDs were collected by a Page webhook integration. e.g. `[1234,5678]`
`data_source` Object	Indicates by which method the custom audience was created, defined by the `type` and `subtype` of the `data_source`
`type` enum {UNKNOWN, FILE_IMPORTED, EVENT_BASED, SEED_BASED, THIRD_PARTY_IMPORTED, COPY_PASTE, CONTACT_IMPORTER, HOUSEHOLD_AUDIENCE}	Type of the custom audience
`sub_type` enum {ANYTHING, NOTHING, HASHES, USER_IDS, HASHES_OR_USER_IDS, MOBILE_ADVERTISER_IDS, EXTERNAL_IDS, MULTI_HASHES, TOKENS, EXTERNAL_IDS_MIX, HOUSEHOLD_EXPANSION, WEB_PIXEL_HITS, MOBILE_APP_EVENTS, MOBILE_APP_COMBINATION_EVENTS, VIDEO_EVENTS, WEB_PIXEL_COMBINATION_EVENTS, PLATFORM, MULTI_DATA_EVENTS, IG_BUSINESS_EVENTS, STORE_VISIT_EVENTS, INSTANT_ARTICLE_EVENTS, FB_EVENT_SIGNALS, ENGAGEMENT_EVENT_USERS, 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, VIDEO_EVENT_USERS, FB_PIXEL_HITS, IG_PROMOTED_POST, PLACE_VISITS, OFFLINE_EVENT_USERS, EXPANDED_AUDIENCE, SEED_LIST, PARTNER_CATEGORY_USERS, PAGE_SMART_AUDIENCE, MULTICOUNTRY_COMBINATION, PLATFORM_USERS, MULTI_EVENT_SOURCE, MAIL_CHIMP_EMAIL_HASHES, CONSTANT_CONTACTS_EMAIL_HASHES, COPY_PASTE_EMAIL_HASHES, CONTACT_IMPORTER, DATA_FILE}	Subtype of the custom audience
`session` Object	Information about the session. Sessions are used when you have a lot of users to upload. For example, if you have 1 million users to upload, you need to split them into at least 100 requests because each request can only take 10k users. Specify the session info so that you can track if the session has finished or not.
`session_id` int64	Advertiser generated session identifier, used to track the session. Needs to be unique in the same ad account.
`estimated_num_total` int64	Estimated total num of users to be uploaded in this session, used by Facebook systems to better process this session.
`batch_seq` int64	A 1 based sequence number to identify the request in the session.
`last_batch_flag` boolean	`true` mean this request is the last request in this session. You must mark the last request otherwise Facebook doesn't know the session has ended

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.

Struct {

audience_id: numeric string,

session_id: numeric string,

num_received: int32,

num_invalid_entries: int32,

invalid_entry_samples: Map {

string: string

}

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

Parameters

Name	Description
`user_id` int	ID of the user to be whitelisted for the page. Required

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.

Struct {

success: bool,

}

Validation Rules

Error	Description
200	Permissions error
100	Invalid parameter
240	Desktop applications cannot call this function for other users
368	The action attempted has been deemed abusive or is otherwise disallowed
195	The name you are trying to use is invalid
210	User not visible

Deleting

Delete a test user

You can dissociate a User from an AdAccountGroup by making a DELETE request to /{ad_account_group_id}/users.

Parameters

Name	Description
`redownload` boolean	Allows you to specify that you would like to retrieve all fields of the set in your response. Default value: `false`.
`uid` int	ID of the user Required

Return Type

Struct {

success: bool,

} Or Struct {

success: bool,

account_group: Struct {

account_group_id: id,

name: string,

status: unsigned int32,

users: List [

Struct {

uid: id,

permissions: List [

unsigned int32

role: integer,

}

accounts: List [

Struct {

account_id: string,

account_group_id: id,

status: unsigned int32,

name: string,

}

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

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps

ads_management
manage_pages
pages_show_list

Page management Apps

manage_pages
pages_show_list

Other Apps

No data

Parameters

Name	Description
`asid` int	AppScopedUserID to unblock
`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}.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps

No data

Page management Apps

No data

Other Apps

Permissions are not usually requested.

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {

success: bool,

}

You can dissociate a User from a CustomAudience by making a DELETE request to /{custom_audience_id}/users.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps

ads_management

Page management Apps

No data

Other Apps

No data

Parameters

Name	Description
`namespace` string	If extern_id provided and namespace specified, will match under specified namespace and update the mapping if necessary and pass permission check
`payload` Object	Payload representing users to delete
`schema` string	`UID`, `EMAIL_SHA256`, `PHONE_SHA256`, `MOBILE_ADVERTISER_ID`. One can also pass an array of multiple keys for multi-key match. Supported key types includes: `EXTERN_ID` `EMAIL` `PHONE` `GEN` `DOBY` `DOBM` `DOBD` `LN` `FN` `FI` `CT` `ST` `ZIP` `MADID` `COUNTRY` The multi-key array is of the form `["EMAIL", "LN", "FN", "ZIP"]`
`is_raw` boolean	Is the key raw? If the keys are combinational keys like "LN_FN_ZIP", set this to `false`, otherwise set this to `true`. Default to false
`data` list<JSON array>	Array with users data. If the multi-key feature is used, a two-dimensional array of the form `[["test1@example.com", "john", "smith", "95124"], ["", "lucy", "brown", "95124"]]` should be passed. In case a key is unknown, it should be left blank.
`app_ids` list<int>	App ids used by the users being uploaded. This field is required when `schema` is a Facebook UID and the IDs were collected by an App integration. e.g. `[1234,5678]`
`page_ids` list<Page ID>	Page ids used by the users being uploaded. This field is required when `schema` is a Facebook UID and the IDs were collected by a Page webhook integration. e.g. `[1234,5678]`
`data_source` Object	Indicates by which method the custom audience was created, defined by the `type` and `subtype` of the `data_source`
`type` enum {UNKNOWN, FILE_IMPORTED, EVENT_BASED, SEED_BASED, THIRD_PARTY_IMPORTED, COPY_PASTE, CONTACT_IMPORTER, HOUSEHOLD_AUDIENCE}	Type of the custom audience
`sub_type` enum {ANYTHING, NOTHING, HASHES, USER_IDS, HASHES_OR_USER_IDS, MOBILE_ADVERTISER_IDS, EXTERNAL_IDS, MULTI_HASHES, TOKENS, EXTERNAL_IDS_MIX, HOUSEHOLD_EXPANSION, WEB_PIXEL_HITS, MOBILE_APP_EVENTS, MOBILE_APP_COMBINATION_EVENTS, VIDEO_EVENTS, WEB_PIXEL_COMBINATION_EVENTS, PLATFORM, MULTI_DATA_EVENTS, IG_BUSINESS_EVENTS, STORE_VISIT_EVENTS, INSTANT_ARTICLE_EVENTS, FB_EVENT_SIGNALS, ENGAGEMENT_EVENT_USERS, 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, VIDEO_EVENT_USERS, FB_PIXEL_HITS, IG_PROMOTED_POST, PLACE_VISITS, OFFLINE_EVENT_USERS, EXPANDED_AUDIENCE, SEED_LIST, PARTNER_CATEGORY_USERS, PAGE_SMART_AUDIENCE, MULTICOUNTRY_COMBINATION, PLATFORM_USERS, MULTI_EVENT_SOURCE, MAIL_CHIMP_EMAIL_HASHES, CONSTANT_CONTACTS_EMAIL_HASHES, COPY_PASTE_EMAIL_HASHES, CONTACT_IMPORTER, DATA_FILE}	Subtype of the custom audience
`session` Object	Information about the session. Sessions are used when you have a lot of users to upload. For example, if you have 1 million users to upload, you need to split them into at least 100 requests because each request can only take 10k users. Specify the session info so that you can track if the session has finished or not.
`session_id` int64	Advertiser generated session identifier, used to track the session. Needs to be unique in the same ad account.
`estimated_num_total` int64	Estimated total num of users to be uploaded in this session, used by Facebook systems to better process this session.
`batch_seq` int64	A 1 based sequence number to identify the request in the session.
`last_batch_flag` boolean	`true` mean this request is the last request in this session. You must mark the last request otherwise Facebook doesn't know the session has ended

Return Type

Struct {

audience_id: numeric string,

session_id: numeric string,

num_received: int32,

num_invalid_entries: int32,

invalid_entry_samples: Map {

string: string

}

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

Parameters

Name	Description
`user_id` numeric string	ID of the user to be removed from whitelist for the page. Required

Return Type

Struct {

success: bool,

}

You can dissociate a User from a User by making a DELETE request to /{user_id}/businesses.

Parameters

Name	Description
`business` numeric string or integer	business

Return Type

Struct {

success: bool,

}

You may perform a DELETE request to the following edge from this node:

/{user_id}/permissions

Validation Rules

Error	Description
200	Permissions error
2904	Cannot delete the OG Test User
100	Invalid parameter
240	Desktop applications cannot call this function for other users
2903	Cannot delete this test account