Graph API Version

Permissions Reference - Facebook Login

Each permission has its own set of requirements and suggested use cases. All these permissions, except the default fields, require that you have Client OAuth Login enabled for your app on the Facebook Login tab of your app dashboard.

The default fields and the email permission do not require Login Review, but all other permissions do. Access to the Public Feed API is restricted to a limited set of media publishers and usage requires prior approval by Facebook.

Please see the details for each permission to learn more about how to use it in your app. Remember, all use of these permissions are subject to our Platform Policies and your own privacy policy.

User Data

Read Permissions - User Attributes

Read Permissions - User Activity

Read Permissions - User Events and Groups

Write Permission - User Events and Groups

Pages and Business Assets

Read Permissions

Write Permissions

Messenger Platform Permissions

Instagram Platform Permissions

Basic Permissions

Getting the user's default profile fields and requesting the email permission do not require login review.

Default Fields

The default fields are a subset of the parts of a person's public profile. These fields are the following properties on the User object:

  • id
  • first_name
  • last_name
  • middle_name
  • name
  • name_format
  • picture
  • short_name

On the web, the default fields are implied with every request and you don't need to declare them, although the best practice is to declare them with public_profile. On iOS and Android, you must manually request these fields with public_profile, as part of your login flow.

The id field is an app-scoped ID.

Review

Your app may use these fields without review from Facebook.

email

Provides access to the person's primary email address via the email property on the user object.

Do not spam users. Your use of email must comply with both Facebook policies and with the CAN-SPAM Act.

Note, even if you request the email permission it is not guaranteed you will get an email address. For example, if someone signed up for Facebook with a phone number instead of an email address, the email field may be empty.

Review

Your app may use this permission without review from Facebook.

Extended Profile Properties

The following permissions require approval prior to use in an app. Learn more about submitting for Login Review.

groups_access_member_info

Gives your app the ability to receive member-related data on group content when a member has granted the app permission to do so.

Review

If your app requests this permission Facebook will have to review how your app uses it.

When requesting this permission via App Review, please make sure your instructions are easily reproducible by our team.

Common Usage

Allow apps to get content posted in their group with user details

Help admins get aggregated insights about activity happening in their group

Sharing data between multiple businesses that you manage

Transfering or selling data obtained through third parties

Building or augmenting user profiles

Behavioral retargeting

Mapping user engagement across Groups

publish_to_groups

Gives an app the ability to post content into a group on behalf of a user who has granted the app this permission.

Review

If your app requests this permission Facebook will have to review how your app uses it.

When requesting this permission via App Review, please make sure your instructions are easily reproducible by our team.

Common Usage

Let people publish content from your app to their Facebook group.

Help people manage the content published to their group.

Automatically publish content without the person being aware or having control.

user_about_me

This permission was deprecated on April 4, 2018.

user_actions.books

This permission was deprecated on April 4, 2018.

user_actions.fitness

This permission was deprecated on April 4, 2018.

user_actions.music

This permission was deprecated on April 4, 2018.

user_actions.news

This permission was deprecated on April 4, 2018.

user_actions.video

This permission was deprecated on April 4, 2018.

user_actions:{app_namespace}


This permission is no longer available due to the deprecation of Custom Open Graph and Custom App Collections.


Provides access to all of the person's custom Open Graph actions in the given app.

Review

If your app requests this permission Facebook will have to review how your app uses it.

Common Usage

Personalize a person's experience based on their open graph actions published by another app.

user_age_range

Provides access to a person's age range.

Review

If your app requests this permission Facebook will have to review how your app uses it.

Common Usage

Your application includes content that is legally required to be age-gated, for example, gambling, gaming, or alcohol.

Your application includes content that is not suitable for the general Facebook audience, such as dating, mature, graphic or violent content.

Your application includes content that is directed at kids or teens.

No visible impact to the user experience based on someone's age range.

user_birthday

Access the date and month of a person's birthday. This may or may not include the person's year of birth, dependent upon their privacy settings and the access token being used to query this field.

Please note most integrations will only need age_range.

Review

If your app requests this permission Facebook will have to review how your app uses it.

When submitting for review, please be clear as to why age_range is not sufficient for your use case.

Common Usage

Provide age relevant content to people based on their date of birth information.

Provide age relevant content for anything where the age range is not sufficient.

Determine whether a person says they are under 18, over 18 or over 21. Please use the age_range instead.

user_education_history

This permission was deprecated on April 4, 2018.

user_events

Provides read-only access to the Events a person is hosting or has RSVP'd to. This permission is restricted to a limited set of partners and usage requires prior approval by Facebook.

Review

Requesting this permission requires you to submit your app for Login Review.

Common Usage

Reduce friction in the visibility of calendar and event information (e.g. device apps, planner apps, concert apps)

Does not allow you to create events. With the launch of v2.0, it is not possible to create events via the Graph API.

Allow someone to RSVP to events using your app.

user_friends

Provides access to the list of friends that also use your app. These friends can be found on the friends edge on the user object. This permission is restricted to a limited set of partners and usage requires prior approval by Facebook.

In order for a person to show up in one person's friend list, both people must have decided to share their list of friends with your app and not disabled that permission during login. Also both friends must have been asked for user_friends during the login process.

Review

Requesting this permission requires you to submit your app for Login Review.

Common Usage

Use the list of friends to create a social experience in your app.

user_games_activity

This permission was deprecated on April 4, 2018.

user_gender

Provides access to a person's gender.

Review

If your app requests this permission Facebook will have to review how your app uses it.

Common Usage

Your application needs gender to correctly render pronouns in certain languages, for example, when a bot messages the person.

Your application is personalized based on gender, for example, in shopping or fashion.

You want to display the person's gender to other people, for example, for dating.

No visible impact to the user experience based on gender.

Fill out a registration form or user profile without using the information to enhance the user experience.

user_groups

This permission was removed after Graph API v2.3.

user_hometown

Provides access to a person's hometown location through the hometown field on the User object. This is set by the user on the Profile.

Review

If your app requests this permission Facebook will have to review how your app uses it.

Common Usage

Personalize a person's experience based on where they lived or grew up.

Help people connect to others from their hometown.

user_likes

Provides access to the list of all Facebook Pages and Open Graph objects that a person has liked. This list is available through the likes edge on the User object. This permission is restricted to a limited set of partners and usage requires prior approval by Facebook.

Review

Requesting this permission requires you to submit your app for Login Review.

If your app requests this permission Facebook will have to [review] how your app uses it.

Common Usage

Creating a personalized experience by surfacing content related to a person's activities.

Visibly enable connections with other users with mutual interests.

Gate access to your app, or some content within your app based on whether or not someone has liked a page.

Provides access to the Facebook profile URL for another user of the app.

If your app requests this permission Facebook will have to review how your app uses it.

To provide a way for someone who uses your app to visit the Facebook profile of another person who uses your app, for example, for dating or local listings.

Attempting to programmatically determine someone's Facebook username or canonical user ID.

user_location

Provides access to a person's current city through the location field on the User object. The current city is set by a person on their Profile.

The current city is not necessarily the same as a person's hometown.

Review

If your app requests this permission Facebook will have to review how your app uses it.

Common Usage

Personalize a person's experience based on their current city.

Surface content relevant to their city.

Help people connect to others from their city.

user_managed_groups

This permission is being deprecated as Groups is moving to a new permission model for apps. Please continue to use user_managed_groups for testing your apps in dev mode. However, when submitting for review, please select the reviewable feature Groups API, and do not submit this user_managed_groups in your review.

Enables your app to read the Groups a person is an admin of through the groups edge on the User object.

This permission does not allow you to create groups on behalf of a person. It is not possible to create groups via the Graph API. This does not let you read the groups a user is just a member of.

Review

Deprecated

Limited Use

For testing only.

user_photos

Provides access to the photos a person has uploaded or been tagged in. This is available through the photos edge on the User object.

Review

Requesting this permission requires you to submit your app for Login Review. This permission is restricted to a limited set of partners and usage requires prior approval by Facebook.

Common Usage

Display a person's pictures on digital photo frame.

Help people export their photos for printing. Only offer this service for a person's personal and non-commercial use.

Access photos for use in a way that visibly enhances the in-app experience (e.g. photo editing, collage, slideshow, and face-in-hole apps).

Access a person's previous profile pictures.

Create albums on behalf of the user.

user_posts

Provides access to the posts on a person's Timeline. Includes their own posts, posts they are tagged in, and posts other people make on their Timeline.

Review

Requesting this permission requires you to submit your app for Login Review. This permission is restricted to a limited set of partners and usage requires prior approval by Facebook.

Common Usage

Provide creative content from Timeline posts.

Provide value to the user by visibly analyzing the content of the posts on their Timeline.

Non-visible use of this data such as sentiment analysis or guarding against spam bots.

user_relationship_details

This permission was deprecated on April 4, 2018.

user_relationships

This permission was deprecated on April 4, 2018.

user_religion_politics

This permission was deprecated on April 4, 2018.

user_status

This permission was removed after Graph API v2.3.

user_tagged_places

Provides access to the Places a person has been tagged at in photos, videos, statuses and links.

Review

Requesting this permission requires you to submit your app for Login Review. This permission is restricted to a limited set of partners and usage requires prior approval by Facebook.

Common Usage

Provide tailored content based on the places a person has been.

Recommend places to visit based on the places a person has previously been tagged at.

Show someone their checkin history on a map.

user_videos

Provides access to the videos a person has uploaded or been tagged in.

Review

Requesting this permission requires you to submit your app for Login Review. This permission is restricted to a limited set of partners and usage requires prior approval by Facebook.

Common Usage

Access videos for use videos in a way that visibly enhances the in-app experience: (e.g. editing, collage, portfolio, slideshow apps.)

Display a person's videos on a TV via a set top box, or display their videos on a digital photo frame.

user_website

This permission was deprecated on April 4, 2018.

user_work_history

This permission was deprecated on April 4, 2018.

read_custom_friendlists

This permission was deprecated on April 4, 2018.

read_insights

Provides read-only access to the Insights data for Pages, Apps and web domains the person owns.

Review

If your app requests this permission Facebook will have to review how your app uses it.

Common Usage

Integrate Facebook's app, page or domain insights into your own analytics tools.

Transfer or sell insights data to third parties.

Provide any non-visible use of insights.

read_audience_network_insights

Provides read-only access to the Audience Network Insights data for Apps the person owns.

Review

If your app requests this permission Facebook will have to review how your app uses it.

Common Usage

Integrate Facebook's app Audience Network insights into your own analytics tools.

Transfer or sell insights data to third parties.

Provide any non-visible use of insights.

read_mailbox

This permission was removed after Graph API v2.3.

### Pages and Business Assets

read_page_mailboxes

Provides the ability to read from the Page Inboxes of the Pages managed by a person. This permission is often used alongside the manage_pages permission.

This permission does not let your app read the page owner's mailbox. It only applies to the page's mailbox.

Review

If your app requests this permission Facebook will have to review how your app uses it.

Common Usage

Let someone manage the mailboxes of their Pages through your app.

read_stream

This permission was removed after Graph API v2.3.

manage_notifications

This permission was removed after Graph API v2.3.

manage_pages

Enables your app to retrieve Page Access Tokens for the Pages and Apps that the person administrates.

Apps need both manage_pages and publish_pages to be able to publish as a Page.

Review

If your app requests this permission Facebook will have to review how your app uses it. You can grant this permission on behalf of people listed within the Roles section of your App's Dashboard without review by Facebook.

When submitting for review, please make sure your instructions are easily reproducible by our team. For example, if your Page Management Tool has its own authentication system, please ensure you provide a working login (such as a username/password) to allow our review team to use your tool and test this functionality.

Common Usage

Publish content to Pages owned by the people who use your app. Publishing also requires the publish_pages permission.

Help people manage the posts, comments and likes published to their Pages.

publish_pages

When you also have the manage_pages permission, gives your app the ability to post, comment and like as any of the Pages managed by a person using your app.

Apps need both manage_pages and publish_pages to be able to publish as a Page.

Publishing as an individual personal account is not possible with this permission.

Review

If your app requests this permission Facebook will have to review how your app uses it.

When requesting this permission via App Review, please make sure your instructions are easily reproducible by our team.

Common Usage

Let people explicitly publish content from your app to any of the Facebook Pages they manage from within a custom composer.

Seamlessly like and comment on behalf of the Pages a person manages.

Automatically publish stories without the person being aware or having control.

Pre-fill the message parameter of posts with content a person didn’t create, even if the person can edit or remove the content before sharing.

rsvp_event

This permission was deprecated on April 4, 2018.

pages_show_list

Provides the access to show the list of the Pages that you manage.

Common Usage

Provides API access to your accounts for showing the list of the Pages that you manage

pages_manage_cta

Provides the access to manage call to actions of the Pages that you manage.

Common Usage

Provides API access to manage call to actions of the Pages that you manage

pages_manage_instant_articles

Lets your app manage Instant Articles on behalf of Facebook Pages administered by people using your app.

Review

If your app requests this permission Facebook will have to review how your app uses it. You can grant this permission on behalf of people listed within the Roles section of your app dashboard without needing review by Facebook.

If you want to use the Instant Articles Plugin for WordPress (or a similar tool) to publish blog posts as Instant Articles, you do not need to submit for review as long as all those for whom you want to publish are listed in the Roles section of your app dashboard.

When you submit for review, please make sure your instructions are easily reproducible by our team. For example, if your app has its own authentication system, please provide a working login information (such as a username/password) to allow our review team to use your tool and test this functionality.

Common Usage

Create and update Instant Articles for Pages owned by the people who use your app.

ads_read

Provides the access to Ads Insights API to pull ads report information for ad accounts you have access to.

This permission does not let you update purchase, update, or otherwise modify ads.

Common Usage

Provides API access to your ad performance data for use in custom dashboards and data analytics

ads_management

Provides the ability to both read and manage the ads for ad accounts you have access to. Please see Ads Management for details.

Common Usage

Programmatically create campaigns, manage ads , and fetch metrics

Build ad management tools that provide innovative solutions and differentiated value for advertisers

business_management

Read and write with Business Management API

Review

If your app requests this permission Facebook will have to review how your app uses it.

Common Usage

Manage business assets such as an ad account. Claiming ad accounts.

Performing general page management and administration only.

Messenger Platform Permissions

pages_messaging (Send/Receive API)

This allows you to send and receive messages through a Facebook Page. This permission cannot be used to send promotional or advertising content. Conversations through this API can only begin when someone indicates—through a Messenger plugin or directly messaging you—that they want to receive messages from you.

Review

If your app requests this permission Facebook will have to review how your app uses it.

Common Usage

Creating user-initiated interactive experiences

Confirming bookings, purchases, orders, etc.

Sending customer support messages

Up-selling or cross-selling products or services

Sending brand advertising, newsletters, announcements or spam

Messaging people without their consent

Instagram Platform Permissions

instagram_basic

Provides the ability to read Instagram accounts you have access to. Please see Instagram's Getting Started Guide for details.

Review

If your app requests this permission Facebook will have to review how your app uses it.

Common Usage

Get basic metadata of an Instagram Business Account.

instagram_manage_comments

Provides the ability to read Instagram accounts you have access to. Please see Instagram's Getting Started Guide for details.

Review

If your app requests this permission Facebook will have to review how your app uses it.

Common Usage

Read, update, delete comments of Instagram Business Accounts.

Read media objects, such as stories, of Instagram Business Accounts.

instagram_manage_insights

Provides the ability to read insights of Instagram account you have access to. Please see Instagram's Getting Started Guide for details.

Review

If your app requests this permission Facebook will have to review how your app uses it.

Common Usage

Get metadata of an Instagram Business Account.

Get data insights of an Instagram Business Account.

Get story insights of an Instagram Business Account.