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

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

FieldDescription

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

about

string

Equivalent to the bio field

age_range

The age segment for this person expressed as a minimum and maximum age. For example, more than 18, less than 21.

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)

context

Social context for this person

cover

The person's cover photo

currency

The person's local currency information

devices

The list of devices the person is using. This will return only iOS and Android devices

education

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

employee_number

string

The person's employee number, as set by the company via SCIM API

favorite_athletes

Athletes the person likes

favorite_teams

Sports teams the person likes

first_name

string

The person's first name

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

hometown

The person's hometown

inspirational_people

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

Facebook Pages representing the languages this person knows

last_name

string

The person's last name

link

string

A link to the person's Timeline

local_news_megaphone_dismiss_status

bool

Display megaphone for local news bookmark

Deprecated

locale

string

The person's locale

location

The person's current location as entered by them on their profile. This field is not related to check-ins

meeting_for

list<string>

What the person is interested in meeting for

middle_name

string

The person's middle name

name

string

The person's full name

name_format

string

The person's name formatted to correctly handle Chinese, Japanese, or Korean ordering

payment_pricepoints

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

Security settings

shared_login_upgrade_required_by

datetime

The time that the shared loginneeds to be upgraded to Business Manager by

significant_other

The person's significant other

sports

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

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

Video upload limits

viewer_can_send_gift

bool

Can the viewer send a gift to this person?

website

string

The person's website

work

Details of a person`s work experience

Edges

EdgeDescription

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

ErrorDescription
100Invalid parameter
200Permissions error
210User not visible
110Invalid user id
452Session key invalid. This could be because the session key has an incorrect format, or because the user has revoked this session
289Accessing friend requests requires the extended permission read_requests
278Reading advertisements requires an access token with the extended permission ads_read
3001Invalid query
1157Sorry, 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.
294Managing 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

ErrorDescription
200Permissions error
100Invalid parameter
240Desktop applications cannot call this function for other users
368The action attempted has been deemed abusive or is otherwise disallowed
195The name you are trying to use is invalid
210User 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

NameDescription
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

NameDescription
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

NameDescription
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

NameDescription
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

ErrorDescription
200Permissions error
100Invalid parameter
240Desktop applications cannot call this function for other users
368The action attempted has been deemed abusive or is otherwise disallowed
195The name you are trying to use is invalid
210User 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

NameDescription
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

NameDescription
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

NameDescription
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

NameDescription
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

NameDescription
business
numeric string or integer

business

Return Type

Struct {
success: bool,
}
You may perform a DELETE request to the following edge from this node:

Validation Rules

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