Page

A Page in the Graph API.

The fields shown below are some of the common fields of Facebook Pages. Pages may also contain other (or additional) category-specific fields. Access to certain Pages may be restricted based on demographic information such as the current user's age or location. Access may also be restricted to only a Page's administrators.

To read a Page you need:

no access token for public and non-demographically restricted pages
a user access_token for restricted pages that the current user is able to view (no special permissions required)

Example

The Page for Facebook Platform:

https://graph.facebook.com/19292868552

Fields

Name	Description	Permissions	Returns
`id`	The Page's ID	No access token or user `access_token`	`string`
`name`	The Page's name	No access token or user `access_token`	`string`
`link`	Link to the page on Facebook	No access token or user `access_token`	`string` containing a valid URL
`category`	The Page's category	No access token or user `access_token`	`string`
`is_published`	Indicates whether the page is published and visible to non-admins	No access token or user `access_token`	`boolean`
`can_post`	Indicates whether the current session user can post on this Page	No access token or user `access_token`	`boolean`
`likes`	The number of users who like the Page	No access token or user `access_token`	`number`
`location`	The Page's street address, latitude, and longitude (when available)	No access token or user `access_token`	`dictionary`
`phone`	The phone number (not always normalized for country code) for the Page	No access token or user `access_token`	`string`
`checkins`	The total number of users who have checked in to the Page	No access token or user `access_token`	`number`
`picture`	Link to the Page's profile picture	No access token or user `access_token`	`string`
`cover`	The `JSON` object including `cover_id` (the ID of the photo), `source` (the URL for the cover photo), and `offset_y` (the percentage offset from top [0-100])	No access token or user `access_token`	`JSON` object
`website`	Link to the external website for the page	No access token or user `access_token`	`string`
`talking_about_count`	The number of people that are talking about this page (last seven days)	No access token or user `access_token`	`number`
`access_token`	A Page admin `access_token` for this page; The current user must be an administrator of this page; only returned if specifically requested via the `fields` URL parameter	`manage_pages`	`string`

Real-Time Subscriptions

The Page object supports Real-time Updates for picture, tagged and checkins connections.

Note: Real-time updates are not yet supported for the total number of Page checkins.

Connections

Name	Description	Permissions	Returns
feed	The Page's wall.	any valid `access_token` or user `access_token`	`array` of `Post` objects.
picture	The Page's profile picture.	No access token or user `access_token`.	Returns a HTTP 302 with the URL of the user's profile picture.
settings	The settings for this page.	page `access_token`	`array` of objects containing `setting` and `value` fields.
tagged	The photos, videos, and posts in which the Page has been tagged.	any valid `access_token` or user `access_token`	a heterogeneous `array` of `Photo`, `Video` or `Post` objects.
links	The Page's posted links.	any valid `access_token` or user `access_token`.	`array` of `link` objects
photos	The Page's uploaded photos.	No access token or user `access_token`	`array` of `Photo` objects.
groups	Groups to which the Page belongs.	any valid `access_token` or user `access_token`	`array` containing `group id`, `version`, `name` and `unread` fields.
albums	The photo albums the Page has uploaded.	No access token or user `access_token`	`array` of `Album` objects.
statuses	The Page's status updates.	any valid `access_token` or user `access_token`	`array` of `Status message` objects.
videos	The videos the Page has uploaded.	any valid `access_token` or user `access_token`	`array` of `Video` objects.
notes	The Page's notes.	any valid `access_token` or user `access_token`	An array of `Note` objects.
posts	The Page's own posts.	any valid `access_token` or user `access_token`	`array` of `Post` objects.
questions	The Page's questions.	any valid `access_token` or user `access_token`	`array` of `Question` objects.
events	The events the Page is attending.	any valid `access_token` or user `access_token`	`array` containing `event id`, `name`, `start_time`, `end_time`, `location` and `rsvp_status`
checkins	Checkins made to this Place Page by the current user, and friends of the current user.	`user_checkins` or `friends_checkins`	`array` of `Checkin` objects.
admins	A list of the Page's Admins.	Page admin `access_token`	`array` of objects containing `id`, `name`.
conversations	A list of the Page's conversations.	Page admin `access_token` with `read_mailbox` permission	`array` of objects containing conversation objects.
milestones	A list of the Page's milestones.	Page admin `access_token`	`array` of `Milestone` Objects.
blocked	A list of users blocked from the Page.	Page admin `access_token`	`array` of objects containing `id`, `name`.
tabs	The Page's profile tabs.	Page admin `access_token`	`array` of objects containing `id`, `name`, `link`, `application`, `custom_name`, `is_permanent`, `position`, and `is_non_connection_landing_tab`.
insights	The Page's Insights data	A valid `access_token` with `read_insights` permission for a user authorized to view the Page's insights.	`array` of `Insights` objects. See the Insights documentation for more information.

NOTE: For connections that require an access token, you can use any valid access token if the page is public and not restricted. Connections on restricted pages require a user access token and are only visible to users who meet the restriction criteria (e.g. age) set on the page.

Page Access Tokens

To perform the following operations as a Page, and not the current user, you must use the Page's access token, not the user access token commonly used for reading Graph API objects. This access token can be retrieved by issuing an HTTP GET to /USER_ID/accounts with the manage_pages permission. This will return a list of Pages (including application profile Pages) to which the user has administrative access, along with access_tokens for those Pages. Alternatively, you can get a page access token for a single, specific, page by issuing an HTTP GET to /PAGE_ID?fields=access_token with the manage_pages permission, as described above. Publishing to a Page also requires the publish_stream permission, unless otherwise noted.

Updating Page Attributes

You can update a Page's basic attributes or About section by issuing an HTTP POST request to PAGE_ID with Page Access Tokens that has manage_pages permission and following parameters:

Parameter	Description	Type	Required
`about`	Text for the about section of a page	`string`	N
`description`	The description of a page	`string`	N
`general_info`	The general information for a page	`string`	N
`website`	The website URL for a page	`string`	N
`phone`	The Phone number for a page	`string`	N

Setting a Cover Photo

You can set a cover photo for a Page by issuing an HTTP POST to '/PAGE_ID/' with a Page Acces Token and the following parameters:

Parameter	Description	Type	Required
`cover`	The ID of the photo	`integer`	Y
`offset_y`	The percentage offset from top (0-100). The default value is `50`	`integer`	N
`no_feed_story`	The flag indicating whether or not to create a story. The default value is `false`	`boolean`	N

Hiding a Page Post

You can hide a Page post that is published by a non-admin user by issuing an HTTP POST to /POST_ID with the following parameter:

Parameter	Description	Type	Required
`is_hidden`	Whether a post is hidden	`boolean`	Y

events

Create

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

Parameter	Description	Type	Required
`name`	Event name	`string`	yes
`start_time`	Event start time	UNIX `timestamp`	yes
`end_time`	Event end time	UNIX `timestamp`	no
`description`	Event description	`string`	no
`location`	Event location	`string`	no
`privacy_type`	Event privacy setting	`string` containing 'OPEN' (default), 'CLOSED', or 'SECRET'	no

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

Name	Description	Type
`id`	The new event ID	`string`

feed

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

To impersonate the Page when posting to the wall (i.e. post as the Page, and not the current user), you must use a Page access_token with the manage_pages and publish_stream permissions, as described under Page Access Tokens above.

Posts may be targeted to countries, cities, regions or locales using the targeting parameter. Please see posts for additional information.

links

Create

You can post a link on a Page by issuing an HTTP POST request to PAGE_ID/feed with the publish_stream and manage_pages permissions and the following parameters.

Parameter	Description	Type	Required
`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.

Name	Description	Type
`id`	The new link ID	`string`

notes

Create

You can create a note on a Page by issuing an HTTP POST request to PAGE_ID/notes with the publish_stream and manage_pages permissions and the following parameters.

Parameter	Description	Type	Required
`subject`	The subject of the Note	`string`	yes
`message`	Note content	`string`	yes

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

Name	Description	Type
`id`	The new note ID	`string`

photos

Create

You can post photos to a Page's Wall by issuing an HTTP POST request to PAGE_ID/photos with the publish_stream and manage_pages permissions and the following parameters.

Parameter	Description	Type	Required
`source`	Photo content	`multipart/form-data`	yes
`message`	Photo description	`string`	no
`targeting`	JSON object containing countries, cities, regions or locales Example: {'countries':['US','GB']}	`string` containing JSON object	no

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

Name	Description	Type
`id`	The new photo ID	`string`

posts

Create

You can create a post on a Page by issuing an HTTP POST request to PAGE_ID/feed with the publish_stream and manage_pages permissions and the following parameters.

Parameter	Description	Type	Required
`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
`targeting`	JSON object containing countries, cities, regions or locales Example: {'countries':['US','GB']}	`string` containing JSON object	no

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

Name	Description	Type
`id`	The new post ID	`string`

questions

Create

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

Parameter	Description	Type	Required
`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.

milestones

Read

You can read milestones for a page by issuing an HTTP GET too /PAGE_ID/milestones with a Page Access Token. This will return the following fields.

Parameter	Description	Type
`id`	The ID of a milestone event	`string`
`title`	The title of the milestone	`string`
`from`	`JSON` object containing the name, category, and id of the Page	object
`description`	The description of the milestone	`string`
`created_time`	The creation time of the milestone	date/time format `ISO-8601`
`updated_time`	The update time of the milestone	date/time format `ISO-8601`
`start_time`	The start time of the milestone	date/time format `ISO-8601`
`end_time`	The end time of the milestone. Page's milestones have the same start and end time	date/time format `ISO-8601`

Create

You can add a milestone by issuing an HTTP POST request to PAGE_ID/milestones with a Page Access Token and the following parameters:

Parameter	Description	Type	Required
`title`	The title of the milestone	`string`	Y
`description`	The description of the milestone	`string`	Y
`start_time`	Th start time of the milestone. A Page's milestones have the same start and end time.	date/time format `ISO-8601`	Y

If the edit is successful, you get the following response:

Parameter	Description	Type
`id`	The ID of the milestone	`string`

Delete

You can delete a milestone by issuing an HTTP DELETE request to /milestone_id with a Page Access Token

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

Description	Type
If the delete is successful	`boolean`

offers

Offers is currently in beta and is available to a limited set of Pages in New Zealand, Singapore, Australia, Japan, and Turkey. We plan to launch offers more widely in the next few weeks. To learn more, please see our recent blog post.

Read

You can read offers of a Page by issuing an HTTP GET to /PAGE_ID/offers with a Page Access Token. This will return the following fields:

Name	Description	Type
`id`	The ID of the Offer	`string`
`from`	`JSON` object containing `name`, `category`, and `id` of the page that posted the Offer	`JSON` object
`title`	The title of the Offer	`string`
`terms`	The description of the terms under which the offer can be claimed	`string`
`image_url`	The URL of the image for the offer.	`string`
`claim_limit`	The maximum number of times the offer can be claimed	`integer`
`created_time`	Time when the Offer was created	date/time format
`expiration_time`	The expiration time of the Offer (used when displaying the Offer)	date/time format `ISO-8601`

Create

You can create an Offer for a page by issuing an HTTP POST to /PAGE_ID/offers with a Page Access Token and the following parameters:

Parameter	Description	Type	Required
`title`	The title of the Offer	`string`	Y
`expiration_time`	The expiration time of the Offer (used when displaying the Offer)	date/time format `ISO-8601`	Y
`terms`	The terms of the Offer	`string`	N
`image_url`	The URL for the Offer's image. Either `image_url` or `image` parameter should be specified, but not both.	`string`	N
`image`	The image for the Offer. Either `image_url` or `image` parameter should be specified, but not both.	`binary file`	N

If the edit is successful, you get the following response:

Description	Description	Type
`id`	The ID of the Offer	`string`

Delete

You can delete a Offer by issuing an HTTP DELETE request to /offer_id with a Page Access Token.

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

Description	Type
If the delete is successful	`boolean`

Note that you cannot modify an offer.

Messages

Read

You can read the messages for a page by issuing an HTTP GET request to /PAGE_ID/conversations with a Page Access Token and read_mailbox permission. This will return the following fields:

Name	Description	Type
`id`	The ID of a conversation, e.g., `t_id.216477638451347`	`string`
`snippet`	The title of a message in the conversation	`string`
`updated_time`	Last update time of the conversation	date/time format `ISO-8601`
`message_count`	The number of messages in the conversation	`integer`
`unread_count`	The number of unread messages in the conversation	`integer`
`tags`	A Set of tags indicating the message folder, and whether the conversation is read and seen.	`JSON` objects that include a name field.
`participants`	Users who are on this message conversation	`JSON` array of objects containing `name`, `email`, and `id` for each participant.
`senders`	Users who send a message on the conversation	`JSON` array of objects containing `name`, `email`, and `id` for each participant who sent a message
`can_reply`	Whether The Page can reply to the conversation	`boolean`
`is_subscribed`	Whether you are subscribed to the conversation	`boolean`
`messages`	List of all messages in the conversation	`JSON` array of `message` objects. Each `message` object contains `id`, `created_time`, `tags`, `from`, `to`, and `message` fields. A message ID look like `m_id.388262297854964`.

Reply

Note that a page can only reply to a user's message. It cannot initiate a private message with a user. Also, a page can respond not more than twice to a user's message before the user has replied back.

You can reply to a user's message by issuing an HTTP POST to /CONVERSATION_ID/messages with the following parameters. A conversation ID look like t_id.216477638451347.

Parameter	Description	Type	Required
`message`	The body of reply	`string`	Y

If the reply is successful, you get following response.

Description	Description	Type
`id`	The ID of the reply message, e.g., `m_id.325810694131945`	`string`

settings

Update

You can change whether users can post to the Wall of a page by issuing a POST request to PAGE_ID/settings with the manage_pages permissions and the following parameters.

Parameter	Description	Type	Required
`setting`	Which single setting to update: `USERS_CAN_POST`, `USERS_CAN_POST_PHOTOS`, `USERS_CAN_TAG_PHOTOS`, `USERS_CAN_POST_VIDEOS`	`string`	Y
`value`	`true` or `false`	`boolean`	Y

If the setting has been changed successfully you will get the following return:

Description	Type
If the setting was successfully set or changed	`boolean`

statuses

Create

You can post a status message on a Page by issuing an HTTP POST request to PAGE_ID/feed with the publish_stream and manage_pages permissions and the following parameters.

Parameter	Description	Type	Required
`message`	Status Message content	`string`	yes

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

Name	Description	Type
`id`	The new status message ID	`string`

videos

Create

You can publish a video on a Page by issuing an HTTP POST request to https://graph-video.facebook.com/PAGE_ID/videos with the publish_stream and manage_pages permissions and the following parameters.

Parameter	Description	Type	Required
`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.

Name	Description	Type
`id`	The new video ID	`string`

tabs

Read

You can read the tabs for a Page by issuing an HTTP GET to /PAGE_ID/tabs with a Page Access Token. This will return the following fields.

Name	Description	Type
`id`	ID of the tab	`string`
`name`	Name of the tab	`string`
`link`	Link to the tab on Facebook	`string` containing the tab's URL
`application`	The `Application` providing the tab	object containing `id` and `name`
`custom_name`	The custom name of the tab. If this is not set, the name of the tab will be determined by the application.	`string`
`is_permanent`	Whether or not the tab is permanently installed	`boolean`
`position`	The order in which the tab appears on the `Page`'s profile	`integer`
`is_non_connection_landing_tab`	Whether this is the default landing tab for users who have not liked and are not admins of this `Page`	`boolean`

You can also retrieve certain specific tabs by issuing an HTTP GET to /TAB_ID.

Testing App Installs

You can test if a specific app is installed on a page profile tab by issuing an HTTP GET to PAGE_ID/tabs/APP_ID. If the app is installed, this will return the following fields.

Name	Description	Type
`id`	ID of the application tab	`string`
`name`	Name of the tab	`string`
`link`	Link to the tab on Facebook	`string` containing the tab's URL
`application`	The `Application` providing the tab	object containing `id` and `name`
`position`	The order in which the tab appears on the `Page`'s profile	`integer`

This request will work for any APP_ID and return the above fields is the app is installed on the page. If the app is not installed on the page, this request will return an empty data[] array.

You can also issue this same query with an app access token. In this case, you can query any PAGE_ID, and the above fields will be returned if your app is installed on the specified page. An empty data[] array is returned as usual if the app is not installed on the specified page.

Create

You can install a profile_tab at the end of the current list of installed tabs for a page by issuing an HTTP POST request to PAGE_ID/tabs with a Page Access Token:

Parameter	Description	Type	Required
`app_id`	ID of the application for which to install the tab.	`string`	Y

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

Description	Type
If the create succeeded	`boolean`

Update

You can update an installed profile_tab for a page by issuing an HTTP POST request to /PAGE_ID/tabs/TAB_ID with Page Access Token and the following parameters:

Parameter	Description	Type	Required
`position`	Order in which the tab will appear on the profile. Must be after permanent tabs and less than the number of installed tabs. Index starts at 0	`integer`	N
`custom_name`	Name to be used for the tab. If this is set to an empty string, the tab will use the application’s default tab name.	`string`	N
`is_non_connection_landing_tab`	Set this tab as the default landing tab for users who have not liked and are not admins of the Page. If provided, value must be `true`.	`boolean`	N
`custom_image_url`	URL for an image to be used as a custom icon for this Page app. Note that either `custom_image_url` or `custom_image` can be set, but not both.	`string`	N
`custom_image`	The name of an image file to be used as a custom icon for this Page app. Note that either `custom_image_url` or `custom_image` can be set, but not both.	`image file`	N

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

Description	Type
If the edit succeeded	`boolean`

Delete

You can delete an installed profile_tab where is_permanent is not true for a page by issuing an HTTP DELETE request to /PAGE_ID/tabs/TAB_ID object with a Page Access Token.

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

Description	Type
If the delete is successful	`boolean`

admins

Belongs

To check if a specific user is an admin of the Page, issue an HTTP GET request with the appropriate PAGE_ID, Page Access Token, and USER_ID to https://graph.facebook.com/PAGE_ID/admins/USER_ID

This returns an array of objects with the following fields:

Name	Description	Type
`id`	ID of the user	`string`
`name`	Name of the user	`string`

blocked

Read

You can get a list of users blocked for a page by issuing an HTTP GET request to PAGE_ID/blocked/ with the page admin access_token. This returns an array of objects with the following fields:

Name	Description	Type
`id`	ID of the user	`string`
`name`	Name of the user	`string`

Belongs

You can check if a user is blocked for a page by issuing an HTTP GET request to PAGE_ID/blocked/USER_ID with the page admin access_token.

If the user is not blocked from the page, a blank object will be returned. Otherwise, an object with the following fields will be returned.

Name	Description	Type
`id`	ID of the user	`string`
`name`	Name of the user	`string`

Create

You can block a user from posting content to your page by issuing an HTTP POST request to PAGE_ID/blocked with the the page admin access_token with the following parameters:

Parameter	Description	Type	Required
`uid`	Comma-separated list of the user IDs you wish to block	`string`	yes

This returns an array where the keys are the user IDs (string) and the values a boolean of whether or not the block was successful.

Delete

You can unblock a blocked user for your page by issuing an HTTP DELETE request to PAGE_ID/blocked with the page admin access_token with the following parameters:

Parameter	Description	Type	Required
`uid`	ID of the user you wish to unblock	`string`	yes

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

Description	Type
If the delete is successful	`boolean`

How-Tos

How to: Publish to a Page

How to upload a video to an Application, Group, or Page's wall using Graph API

Updated about a week ago

Concepts

Objects

Example

Fields

Real-Time Subscriptions

Connections

Page Access Tokens

Updating Page Attributes

Setting a Cover Photo

Hiding a Page Post

events

Create

feed

links

Create

notes

Create

photos

Create

posts

Create

questions

Create

Delete

milestones

Read

Create

Delete

offers

Read

Create

Delete

Messages

Read

Reply

settings

Update

statuses

Create

videos

Create

tabs

Read

Create

Update

Delete

admins

Belongs

blocked

Read

Belongs

Create

Delete

How-Tos