Bookmark and Share BitCoin Donate: 13t8gAWVpHP2ddxMp88d1NFpZjnFJC6UwK

Facebook User model

Example

https://graph.facebook.com/me (the current user)


Fields

The User object has the following fields:

Name Description Permissions Returns
id

The user's Facebook ID

No access_token required

string

name

The user's full name

No access_token required

string

first_name

The user's first name

No access_token required

string

middle_name

The user's middle name

No access_token required

string

last_name

The user's last name

No access_token required

string

gender

The user's gender: female or male

No access_token required

string

locale

The user's locale

No access_token required

string containing the ISO Language Code and ISO Country Code

languages

The user's languages

user_likes

array of objects containing language id and name

link

The URL of the profile for the user on Facebook

No access_token required

string containing a valid URL

username

The user's Facebook username

No access_token required

string

age_range

The user's age range; only returned if specifically requested via the fields URL parameter

Requires access_token

object containing min and max for the age range; Possible age ranges are 13-17, 18-20, and 21+; max is not set if the age is 21+

third_party_id

An anonymous, but unique identifier for the user; only returned if specifically requested via the fields URL parameter

Requires access_token

string

installed

Specifies whether the user has installed the application associated with the app access token that is used to make the request; only returned if specifically requested via the fields URL parameter

Requires app access_token

object containing type (this is always "user"), id (the ID of the user), and optional installed field (always true if returned); The installed field is only returned if the user has installed the application, otherwise it is not part of the returned object

timezone

The user's timezone offset from UTC

Available only for the current user

number

updated_time

The last time the user's profile was updated; changes to the languages, link, timezone, verified, interested_in, favorite_athletes, favorite_teams, and video_upload_limits are not not reflected in this value

Requires access_token

string containing an ISO-8601 datetime

verified

The user's account verification status, either true or false (see below)

Requires access_token

boolean

bio

The user's biography

user_about_me or friends_about_me

string

birthday

The user's birthday

user_birthday or friends_birthday

Date string in MM/DD/YYYY format

cover

The user's cover photo (must be explicitly requested using fields=cover parameter)

Requires access_token

array of fields id, source, and offset_y

currency

The user's currency settings (must be explicitly requested using a fields=currency URL parameter)

Requires access_token

object with fields currency (detailed here), id

devices

A list of the user's devices beyond desktop

User access_token required; only available for friends of the current user

array of objects containing os which may be a value of 'iOS' or 'Android', along with an additional field hardware which may be a value of 'iPad' or 'iPhone' if present, however may not be returned if we are unable to determine the hardware model - Note: this is a non-default field and must be explicitly specified as shown below

education

A list of the user's education history

user_education_history or friends_education_history

array of objects containing year and type fields, and school object (name, id, type, and optional year, degree, concentration array, classes array, and with array )

email

The proxied or contact email address granted by the user

email

string containing a valid RFC822 email address

hometown

The user's hometown

user_hometown or friends_hometown

object containing name and id

interested_in

The genders the user is interested in

user_relationship_details or friends_relationship_details

array containing strings

location

The user's current city

user_location or friends_location

object containing name and id

political

The user's political view

user_religion_politics or friends_religion_politics

string

payment_pricepoints

The payment price-points available for that user

User access_token

array of objects containing user_price, credits and local_currency fields

favorite_athletes

The user's favorite athletes; this field is deprecated and will be removed in the near future

user_likes or friends_likes

array of objects containing id and name fields

favorite_teams

The user's favorite teams; this field is deprecated and will be removed in the near future

user_likes or friends_likes

array of objects containing id and name fields

picture

The URL of the user's profile pic (only returned if you explicitly specify a 'fields=picture' param)

access_token required for pages with whitelisting/targeting restrictions, otherwise no access_token required

string; If the "October 2012 Breaking Changes" migration setting is enabled for your app, this field will be an object with the url and is_silhouette fields; is_silhouette is true if the user has not uploaded a profile picture

quotes

The user's favorite quotes

user_about_me or friends_about_me

string

relationship_status

The user's relationship status: Single, In a relationship, Engaged, Married, It's complicated, In an open relationship, Widowed, Separated, Divorced, In a civil union, In a domestic partnership

user_relationships or friends_relationships

string

religion

The user's religion

user_religion_politics or friends_religion_politics

string

security_settings

Information about security settings enabled on the user's account (must be explicitly requested using a fields=security_settings URL parameter)

Available only for the current user

object containing secure_browsing (an object with a single field, enabled, which indicates whether Secure Browsing is enabled)

significant_other

The user's significant other

user_relationships or friends_relationships

object containing name and id

video_upload_limits

The size of the video file and the length of the video that a user can upload; only returned if specifically requested via the fields URL parameter

Requires access_token

object containing length and size of video

website

The URL of the user's personal website

user_website or friends_website

string containing a valid URL

work

A list of the user's work history

user_work_history or friends_work_history

array of objects containing employer, location, position, start_date and end_date fields

You can choose the fields you want returned using the fields query parameter:

https://graph.facebook.com/me?fields=id,name

Verified Users


A user is considered verified if she takes any of the following actions:

  • Registers for mobile
  • Confirms her account via SMS
  • Enters a valid credit card

Real-Time Subscriptions

The User object supports Real-Time Updates for all fields except the verified property.


Connections

The User object has the following connections:

Name Description Permissions Returns
accounts

The Facebook apps and pages owned by the current user.

manage_pages yields access_tokens that can be used to query the Graph API on behalf of the app/page

array of objects containing account name, access_token, category, id

achievements

The achievements for the user.

user_games_activity or friends_games_activity.

array of achievement(instance) objects

activities

The activities listed on the user's profile.

user_activities or friends_activities.

array of objects containing activity id, name, category and create_time fields.

albums

The photo albums this user has created.

user_photos or friends_photos.

array of Album objects.

apprequests

The user's outstanding requests from an app.

Requires app access_token.

array of app requests for the user within that app.

books

The books listed on the user's profile.

user_likes or friends_likes.

array of objects containing book id, name, category and create_time fields.

checkins

The places that the user has checked-into.

user_checkins or friends_checkins.

array of Checkin objects

events

The events this user is attending.

user_events or friends_events.

array of objects containing event id, name, start_time, end_time, location and rsvp_status defaulting to the past two weeks.

family

The user's family relationships

user_relationships.

array of objects containing id, name, and relationship fields.

feed

The user's wall.

read_stream

array of Post objects containing (up to) the last 25 posts.

friendlists

The user's friend lists.

read_friendlists.

array of objects containing id and name fields of the friendlist.

friendrequests

The user's incoming friend requests.

user_requests.

array of objects containing to, from, message, created_time and unread fields of the friend request

friends

The user's friends.

Any valid access_token of the current session user.

array of objects containing friend id and name fields.

games

Games the user has added to the Arts and Entertainment section of their profile.

user_likes

array of objects containing id, name, category, and created_time

groups

The Groups that the user belongs to.

user_groups or friends_groups.

An array of objects containing the version(old-0 or new Group-1), name, id, administrator (if user is the administrator of the Group) and bookmark_order(at what place in the list of group bookmarks on the homepage, the group shows up for the user).

home

The user's news feed.

read_stream.

array of Post objects containing (up to) the last 25 posts.

inbox

The Threads in this user's inbox.

read_mailbox.

array of thread objects

interests

The interests listed on the user's profile.

user_interests or friends_interests.

array of objects containing interest id, name, category and create_time fields.

likes

All the pages this user has liked.

user_likes or friends_likes.

array of objects containing like id, name, category and create_time fields.

links

The user's posted links.

read_stream.

array of Link objects.

locations

Posts, statuses, and photos in which the user has been tagged at a location, or where the user has authored content (i.e. this excludes objects with no location information, and objects in which the user is not tagged). See documentation of the location_post table for more detailed information on permissions.

user_photos, friend_photos, user_status, friends_status, user_checkins, or friends_checkins.

array of objects containing the id, type, place, created_time, and optional application and tags fields.

movies

The movies listed on the user's profile.

user_likes or friends_likes.

array of objects containing movie id, name, category and create_time fields.

music

The music listed on the user's profile.

user_likes or friends_likes.

array of objects containing music id, name, category and create_time fields.

mutualfriends

The mutual friends between two users.

Any valid access_token of the current session user.

array of objects containing friend id and name fields.

notes

The user's notes.

user_notes.

array of Note objects.

notifications

App notifications for the user.

Any valid access_token of the current session user.

array of objects containing template and href.

outbox

The messages in this user's outbox.

read_mailbox.

array of messages

payment_transactions

The Facebook Payments orders the user placed with an application. See the Payments API for more information.

app access_token

array of payment objects.

payments

The Facebook Credits orders the user placed with an application. See the Credits API for more information.

app access_token

array of order objects.

permissions

The permissions that user has granted the application.

None.

array containing a single object which has the keys as the permission names and the values as the permission values (1/0) - Permissions with value 0 are omitted from the object by default; also includes a type field which is always permissions if the query param metadata=1 is passed.

photos

Photos the user (or friend) is tagged in.

user_photo_video_tags or friends_photo_video_tags.

array of Photo objects.

photos/uploaded

All of the updates photos of a user. Cursor based pagination.

user_photos

array of Photo objects containing all of the photos a user has uploaded in order of upload time.

picture

The user's profile picture.

No access_token required.

HTTP 302 redirect to URL of the user's profile picture (use ?type=square | small | normal | large to request a different photo). If you specify ?redirect=false, this connection will return the URL of the profile picture without a 302 redirect. Additionally, you can specify width and height URL parameters to request a picture of a specific size, however the returned picture is not guaranteed to be exactly the requested size. Specifying width and height will return an available profile picture closest to the requested size and requested aspect ratio. If only width or height is specified, we will return a picture whose width or height is closest to the requested size, respectively; if width=height, we will always return a square picture. If the "October 2012 Breaking Changes" migration setting is enabled for your app, this connection will return a JSON object with url, width, height, and is_silhouette fields, where the width and height specify the actual dimensions of the returned picture; is_silhouette is a boolean which specifies whether the profile picture is the default picture (i.e. the user has not uploaded a profile picture).

pokes

The user's pokes.

read_mailbox.

an array of objects containing to, from, created_time and type fields.

posts

The user's own posts.

Any valid access_token or read_stream to see non-public posts.

array of Post objects.

questions

The user's questions.

user_questions

array of Question objects.

scores

The current scores for the user in games.

user_games_activity or friends_games_activity.

array of objects containing user, application, score and type.

sharedposts

Returns shares of the object. Cursor based pagination.

read_stream

array of Post objects.

statuses

The user's status updates.

read_stream.

An array of Status message objects.

subscribedto

People you're subscribed to.

Any valid access_token

array of objects containing user id and name fields.

subscribers

The user's subscribers.

Any valid access_token

array of objects containing user id and name fields.

tagged

Posts the user is tagged in.

read_stream

array of objects containing id, from, to, picture, link, name, caption, description, properties, icon, actions, type, application, created_time, and updated_time

television

The television listed on the user's profile.

user_likes or friends_likes.

array of objects containing television id, name, category and create_time fields.

updates

The updates in this user's inbox.

read_mailbox.

array of messages

videos

The videos this user has been tagged in.

user_videos or friends_videos.

array of Video objects.

This object supports Real-Time Updates for the following connections: feed, friends, activities, interests, music, books, movies, television, likes, checkins.


albums

Create

You can create an album for a user by issuing an HTTP POST request to PROFILE_ID/albums with the publish_stream permissions and the following parameters.

ParameterDescriptionTypeRequired
name Album name string yes
message Album description string no
privacy Privacy settings for the Album A JSON object with fields described here no

If the create is successful, you get the following return.

NameDescriptionType
id The new album ID string

apprequests

Read

You can read the apprequests sent to a user by your app by issuing an HTTP GET request to /USER_ID/apprequests with user access_token.

The API returns an array of objects containing the following data:

NameDescriptionType
id The full request ID. string
application App associated with the request. object containing the name, canvas_name, namespace and id of the app.
to The recipient user associated with the request. object containing the name and id for the user.
from The sender user associated with the request. object containing the name and id for the user.
message A string describing the request. string
created_time Timestamp when the request was created. UNIX timestamp
type type of the data which is "apprequest". string

Create

You can post a apprequest for a user by issuing an HTTP POST request to /USER_ID/apprequests with the app access_token.

Note: POSTing to the Graph API endpoint of /USER_ID/apprequests is considered an App to User Request. App-Generated Requests do not receive notifications and get limited distribution in comparison to User to User Requests sent with the Request Dialog

NameDescriptionTypeRequired
message A UTF-8 string which describes the request. string yes
data Additional data a developer may pass for tracking. This will be stored as part of the request objects created. The maximum length is 255 characters. string no

If the create is successful, you get the following response

DescriptionType
request

The Request Object ID. To get the full request ID, concatenate this with a User ID from the to field: ‘<request_object_id>_<user_id>’

to

An array of the recipient user IDs for the request that was created.

Delete

You can delete the current Request for a user for your app by issuing an HTTP DELETE request to /<request_object_id>_<user_id> with the user access token or app access_token. For more information see Deleting Requests.

Response

DescriptionType
True if the delete succeeded and error otherwise. boolean

checkins

Create

Publishing a Checkin has been deprecated in favor of creating a Post with a place attached or publishing Open Graph stories with Place Tagging.


events

Create

You can create an event for a user by issuing an HTTP POST request to PROFILE_ID/events with the create_event permissions and the following parameters.

NOTE - After the 'Events Timezone' migration, all event times are ISO-8601 formatted strings; they can no longer be specified as timestamps. The following formats are accepted:

  • Date-only (e.g., '2012-07-04'): events that have a date but no specific time yet.
  • Precise-time (e.g., '2012-07-04T19:00:00-0700'): events that start at a particular point in time, in a specific offset from UTC. This is the way new Facebook events keep track of time, and allows users to view events in different timezones.

Event times with a date and time but no offset from UTC are no longer accepted.

ParameterDescriptionTypeRequired
name Event name string yes
start_time Event start time, in ISO-8601 string yes
end_time Event end time, in ISO-8601 string no
description Event description string no
location Event location string no
location_id Facebook Place ID of the place the Event is taking place string no
privacy_type Event privacy setting string containing 'OPEN' (default), 'SECRET', or 'FRIENDS' no

If the create is successful, you get the following return.

NameDescriptionType
id The new event ID string

Edit

You can edit an event by issuing an HTTP POST to /EVENT_ID with the create_event permission. Note that only the application that created the event can edit the event. Any of the fields listed above as being available when creating an event can be edited by specifying a new value for that field. You don't need to specify values for fields you are not editing. Note that the name and time cannot be changed if the event is old, or if it has over 5000 attendees.

If the edit is successful, you get the following return.

TypeDescription
boolean True if the delete succeeded and error otherwise.

Delete

You can delete an event by issuing an HTTP DELETE to /EVENT_ID with the create_event permission. Note that only the application that created the event can delete the event.

If the delete is successful, you get the following return.

TypeDescription
boolean True if the delete succeeded and error otherwise.

feed

This connection corresponds to the user's Wall. You can create a link, post or status message by issuing an HTTP POST request to the PROFILE_ID/feed connection. To see more details please see links, posts, and status messages documentation.

When retrieving Wall posts, you can get only those Post objects with a location attached by adding with=location to the URL parameters:

https://graph.facebook.com/me/feed?with=location


friends

Read

You can read the list of a User's friends by issuing an HTTP GET to /PROFILE_ID/friends with any valid access_token of the current session user. For example:

https://graph.facebook.com/me/friends

Belongs

You can also see if a User is a friend of the current session User by issuing an HTTP GET to /PROFILE_ID/friends/FRIEND_ID. This will return, in the data array, an object with the following fields if the current user is friends with the User represented by FRIEND_ID:

NameDescriptionType
id Facebook ID of the friend string
name Name of friend of current user string

If the current user is not a friend with the User represented by FRIEND_ID, the data array will be empty.

For example, to see if you are friends with Dhiren Patel, issue an HTTP GET to:

https://graph.facebook.com/me/friends/1207059


friendlists

Create

You can create a friend list for a user by issuing an HTTP POST request to PROFILE_ID/friendlists with the manage_friendlists permissions and the following parameters.

ParameterDescriptionTypeRequired
name Friend list name. Maximum 25 characters string yes

If the create is successful, you get the following return.

NameDescriptionType
id The new friend list ID string

friendrequests

Read

You can read the outstanding friend requests for a user by issuing an HTTP GET request to USER_ID/friendrequests with the read_requests permission.

https://graph.facebook.com/me/friendrequests

This returns an array of objects of the following type:

NameDescriptionType
from The name and id of the user who sent the friend request object containing string name and string id.
to The name and id of the user to whom the friend request was sent object containing string name and string id.
created_time Time at which the friend request was created ISO 8601 datetime
message Message provided the friend request sender when they sent the request string
unread Whether the user has read the friend request or not. boolean

home

This connection corresponds to the News Feed. See the feed connection for information on how to create and delete objects that show up in the News Feed.

You can retrieve the News Feed filtered by user's stream filters:

  • friend lists
  • applications: For example, to retrive your News Feed filtered by photos GET me/home?filter=app_2305272732
  • networks
  • the home page stream (News Feed, this is the default view)

To retrieve a user's stream filters, you will need to access the the stream_filter table.

You can retrieve only posts with a location attached by adding with=location to the URL parameters:

https://graph.facebook.com/me/home?with=location


likes

Read

You can read the pages that a User has liked by issuing an HTTP GET to /PROFILE_ID/likes with the user_likes or friends_likes permissions. For example:

https://graph.facebook.com/me/likes

Belongs

You can check if a User likes a specific page by issuing an HTTP GET to /PROFILE_ID/likes/PAGE_ID. This requires the user_likes (current user) or friends_likes (current user's friend) permission. This will return, in the data array, an object with the following fields if the user is connected to the page:

NameDescriptionType
id Facebook ID of the page string
name Name of the Page string
category Category of the Page, e.g. 'Website', 'Product/Service', etc. string
created_time ISO-8601 datetime representing when the User was connected to the Page string

If the user is not connected to the page, the data array will be empty.

For example to see if you like the Facebook Platform Page, HTTP GET the following:

https://graph.facebook.com/me/likes/19292868552


Create

You can post a link on the user's behalf by issuing an HTTP POST request to PROFILE_ID/feed with the publish_stream permissions and the following parameters.

ParameterDescriptionTypeRequired
link Link URL string yes
message Link message string no

The other fields are taken from the metadata of the page URL given in the 'link' param.

If the create is successful, you get the following return.

NameDescriptionType
id The new link ID string

mutualfriends

Read

You can read the list of two Users mutual friends by issuing an HTTP GET to /PROFILE_ID/mutualfriends/FRIEND_ID with any valid access_token of the current session user. For example, to see the friends you and Dhiren Patel have in common, issue an HTTP GET to:

https://graph.facebook.com/me/mutualfriends/1207059


notes

Create

You can create a note on behalf of the user by issuing an HTTP POST request to PROFILE_ID/notes with the publish_stream permissions and the following parameters.

ParameterDescriptionTypeRequired
subject The subject of the Note string yes
message Note content string yes

If the create is successful, you get the following return.

NameDescriptionType
id The new note ID string

notifications

Create

You can send app notifications to users of your app by using our notifications API. This does not require any special permissions but can only be used with TOS'd users.

To send a new App2User notifications you can issue the HTTP POST request with the template and optional href parameter to /USER_ID/notifications using your the current user's access_token or your app access_token.

More information on the parameters here:

NameDescriptionType
template The template text to be shown to the user. string
href the unique tracking data you want added to the url for tracking string

For example:

https://graph.facebook.com/USER_ID/notifications?
    template={1234} just passed your high score. Play now to regain your throne!&
    href=track_123&access_token=APP_ACCESS_TOKEN

On success, this returns an object showing the request has been sent:

 {
    "success": true
 }

For more information on app notifications including detailed examples, see our feature specific documentation here.

payment_transactions

Note: This document describes a technology that is still in its final design phase and is subject to change. We are migrating all canvas game developers in the third quarter this year and want to provide ample time for you to review this documentation before we launch local currency payments. After launch, developers will have a minimum of 90 days to implement the updated payments infrastructure to continue accepting payments. In the coming weeks, we will provide further updates on when you can begin integration.

Read

To retrieve all transactions for a given user you can query the following Graph API request:

https://graph.facebook.com/USER_ID/payment_transactions?access_token=APP_ACCESS_TOKEN

You may want to since and until to filter the response. Those parameter are a unix timestamp or any date accepted by strtotime.

Example Response

{"data":{"id":"312474835534988","user":{"name":"Marie Utilisatrice","id":"172347878787877"},"application":{"name":"In Your Village","namespace":"inyourvillage","id":"40478799879398899"},"actions":{"type":"charge","status":"completed","currency":"USD","amount":"3.98","time_created":"2012-12-06T13:28:21+0000","time_updated":"2012-12-06T13:28:23+0000"},"refundable_amount":{"currency":"USD","amount":"3.98"},"items":{"type":"IN_APP_PURCHASE","product":"http://inyourvillage.com/og/money","quantity":2},"request_id":"abcd_221159","country":"US","created_time":"2012-12-06T13:28:21+0000","payout_foreign_exchange_rate":1},{"id":"301210783328056","user":{"name":"Marie Utilisatrice","id":"172347878787877"},"application":{"name":"In Your Village","namespace":"inyourvillage","id":"40478799879398899"},"actions":{"type":"charge","status":"inited","currency":"USD","amount":"0.10","time_created":"2012-11-16T05:08:20+0000","time_updated":"2012-11-16T05:08:20+0000"},"refundable_amount":{"currency":"USD","amount":"0.00"},"items":{"type":"IN_APP_PURCHASE","product":"http://inyourvillage.com/og/money","quantity":1},"request_id":"abcde_221159","country":"US","created_time":"2012-11-16T05:08:20+0000","payout_foreign_exchange_rate":1},"paging":{"previous":"https://graph.facebook.com/172347878787877/payment_transactions?access_token=APP_ACCESS_TOKEN&limit=1000&since=1354800501&__paging_token=40478799879398899&__previous=1","next":"https://graph.facebook.com/172347878787877/payment_transactions?access_token=APP_ACCESS_TOKEN&limit=1000&until=1353042500&__paging_token=40478799879398899"}}

Verify that there is an element of the actions array whose status is completed, and then award the user the item purchased.


photos

Create

You can post photos to a user's Wall on their behalf by issuing an HTTP POST request to PROFILE_ID/photos with the publish_stream permissions and the following parameters.

ParameterDescriptionTypeRequired
source Photo content multipart/form-data yes
message Photo description string no
place Facebook ID of the place associated with the Photo string no
no_story If set to 1, optionally suppresses the feed story that is automatically generated on a user’s profile when they upload a photo using your application. boolean no

If the create is successful, you get the following return.

NameDescriptionType
id The new photo ID string

Delete

You can delete photos for a user posted from your app by issuing an HTTP DELETE request to PROFILE_ID/photos with the user access token or app access_token. For more information see Deleting Requests.

Response

DescriptionType
True if the delete succeeded and error otherwise. boolean

permissions

Read

You can read the permissions granted by the user to the current application by issuing an HTTP GET to /USER_ID/permissions with either a user access_token for this app, or an app access_token. This will return an object containing the permission names which the user has granted the application:

https://graph.facebook.com/me/permissions

Example response :

{"data":{"installed":1,"read_stream":1,"read_mailbox":1,"publish_actions":1,"user_groups":1,"user_events":1}}

Delete

You can de-authorize an application entirely, or just revoke a specific permission on behalf of a user by issuing an HTTP DELETE to USER_ID/permissions or USER_ID/permissions/PERMISSION_NAME respectively. This request must be made with a valid user access_token or an app access token for the current app.

ParameterDescriptionTypeRequired
permission The permission you wish to revoke. If you don't specify a permission then this will de-authorize the application completely. string no

https://graph.facebook.com/me/permissions or, for a specific permission such as email, https://graph.facebook.com/me/permissions/email

You get the following result.

DescriptionType
True if the delete succeeded and error otherwise. boolean

posts

Read

You can read Post published by a user by issuing an HTTP GET to /USER_ID/posts. This will return an array of Post objects:

https://graph.facebook.com/me/posts

You can retrieve only posts with a location attached by adding with=location to the URL parameters:

https://graph.facebook.com/me/posts?with=location

Create

You can create a post on behalf of the user by issuing an HTTP POST request to PROFILE_ID/feed (not PROFILE_ID/posts) with the publish_stream permissions and the following parameters. Note that you can only delete the post if it was created by your app.

ParameterDescriptionTypeRequired
message Post message string either message or link
link Post URL string either message or link
picture Post thumbnail image (can only be used if link is specified) string no
name Post name (can only be used if link is specified) string no
caption Post caption (can only be used if link is specified) string no
description Post description (can only be used if link is specified) string no
actions Post actions array of objects containing name and link no
place Facebook Page ID of the location associated with this Post string no
tags Comma-separated list of Facebook IDs of people tagged in this Post. For example: 1207059,701732. This field is returned as the with_tags field when the Post is read. NOTE: You cannot specify this field without also specifying a place. string no
privacy Post privacy settings (can only be specified if the Timeline being posted on belongs to the User creating the Post) string no
object_attachment Facebook ID for an existing picture in the User's photo albums to use as the thumbnail image. The User must be the owner of the photo, and the photo cannot be part of a message attachment. string no

If the create is successful, you get the following return.

NameDescriptionType
id The new post ID string

questions

Read

To read a Question, you need the following permissions:

  • user_questions for questions asked by the current user.
  • friends_questions for questions asked by friends of the current user.

Example

Questions that the current user has asked:

https://graph.facebook.com/me/questions

Create

You can post a question on behalf of the user by issuing an HTTP POST request to PROFILE_ID/questions with the publish_stream permissions and the following parameters.

ParameterDescriptionTypeRequired
question The text of the question string yes
options Array of answer options array no
allow_new_options Allows other users to add new options (True by default) boolean no

Delete

You can delete a question by issuing an HTTP DELETE request to the QUESTION_ID object with the publish_stream permission.


statuses

Create

You can post a status message on behalf of the user by issuing an HTTP POST request to PROFILE_ID/feed with the publish_stream permissions and the following parameters.

ParameterDescriptionTypeRequired
message Status Message content string yes

If the create is successful, you get the following return.

NameDescriptionType
id The new status message ID string

subscribedto

Read

You can read the people the user is subscribed to by issuing an HTTP GET request to /USER_ID/subscribedto with a user access_token with the user_subscriptions or friends_subscriptions permission.

Example

People you're subscribed to:

https://graph.facebook.com/me/subscribedto


subscribers

Read

You can read the subscribers for a user for your app by issuing an HTTP GET request to /USER_ID/subscribers with the user access_token with the user_subscriptions or friends_subscriptions permission.

Example

A person's list of subscribers:

https://graph.facebook.com/me/subscribers


videos

Create

You can publish a video on behalf of a user by issuing an HTTP POST request to PROFILE_ID/videos with the publish_stream permission and the following parameters.

ParameterDescriptionTypeRequired
source Video content multipart/form-data yes
title Video title string no
description Video description string no

If the create is successful, you get the following return.

NameDescriptionType
id The new video ID string

Scores

Read

You can read the scores for a user for your app by issuing an HTTP GET request to /USER_ID/scores with user or app access_token for that app.

  • If the user has granted your app with the user_games_activity permission then this api will give you scores for all apps for that user. Otherwise it will give you scores only for your app.
  • The friends_games_activity permission will enable you to access scores for users' friends for all apps by issuing an HTTP GET request to /FRIEND_ID/scores.

The API returns an array of objects containing the following data:

NameDescriptionType
user User associated with the scores. object containing the name and id for the user.
score Numeric score. integer
application App associated with the score. object containing the name and id of the app.
type type of the data which is "score". string

Create

You can post a score for a user by issuing an HTTP POST request to /USER_ID/scores with a user or app access_token as long as you have the publish_actions permission.

NameDescriptionTypeRequired
score numeric score with value < 0. integer yes

Return value

DescriptionType
Whether the write succeeded. boolean

Delete

You can delete the current score for a user for your app by issuing an HTTP DELETE request to /USER_ID/scores with a user or app access_token as long as your app has the publish_actions permission.

Response

DescriptionType
true or error depending on whether the delete was successful. boolean

Achievements

Read

You can read the set of achievements for a user by issuing an HTTP GET request to /USER_ID/achievements with a an app or user access_token. This returns an array of achievement(instance) objects where each achievement(instance) represents the instance of the achievement achieved by the user.

  • If the user has authorized your app with the user_games_activity permission then this returns the achievements for all games. Otherwise it returns achievements only for your app.
  • If the user has authorized your app with the friends_games_activity permission then you can also access achievements for the user's friends by issuing a HTTP GET request to /FRIEND_ID/achievements.

Create

You can post an achievement for a user by issuing an HTTP POST request to /USER_ID/achievements with a user or app access_token as long as the user has given the app the publish_actions permission. The API takes the following parameters:

NameDescriptionTypeRequired
achievement The unique URL of the achievement which the user achieved. string yes

Response

NameDescriptionType
id achievement (instance) id for that user. string
Error CodeDescription
3403 If the app tries to post an achievement which isn't registered.
3501 If the app tries to post an achievement which the user already has.

Delete

You can delete an achievement for a user by issuing an HTTP DELETE request to USER_ID/achievements with a user or app access_token as long as you have the publish_actions permission.

NameDescriptionTypeRequired
achievement The unique URL of the achievement you wish to delete. string yes

Response

DescriptionType
true or error depending on whether the delete was successful. boolean
Error CodeDescription
3404 If the app tries to delete an achievement that the user doesn't have.