Graph API Version

Facebook App

A Facebook app.

Reading

A Facebook app

Permissions

  • An app access token can be used to view all fields for an app.

Example

Graph API Explorer
GET /v5.0/{application-id} HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{application-id}',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/{application-id}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{application-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:@"/{application-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 app ID

aam_rules
string

Rules of Auto Advanced Matching in FB SDKs

an_ad_space_limit
unsigned int32

The maximum number ofAd Spaces allowed for each Audience Network supported platform

an_platforms
list<enum>

The platforms associated with the app in the Audience Network product. Not enforced, but when present, it can be used to provide the user with platform specific information for the app and its placements

app_domains
list<string>

Domains and subdomains this app can use

app_install_tracked
bool

Whether the app install is trackable or not

app_name
string

App name

app_signals_binding_ios
list<Binding>

List of app event bindings for iOS app

app_type
unsigned int32

App type

auth_dialog_data_help_url
string

The URL of a special landing page that helps people who are using an app begin publishing Open Graph activity

auth_dialog_headline
string

One line description of an app that appears in the Login Dialog

auth_dialog_perms_explanation
string

The text to explain why an app needs additional permissions. This appears in the Login Dialog

auth_referral_default_activity_privacy
string

The default privacy setting selected for Open Graph activities in the Auth Dialog

auth_referral_enabled
unsigned int32

Indicates whether Authenticated Referrals are enabled

auth_referral_extended_perms
list<string>

Extended permissions that a person can choose to grant when Authenticated Referrals are enabled

auth_referral_friend_perms
list<string>

Basic friends permissions that a user must grant when Authenticated Referrals are enabled

auth_referral_response_type
string

The format that an app receives for the authentication token from the Login Dialog

auth_referral_user_perms
list<string>

Basic user permissions that a user must grant when Authenticated Referrals are enabled

canvas_fluid_height
bool

Indicates whether the app uses fluid or settable height values for Canvas

canvas_fluid_width
unsigned int32

Indicates whether the app uses fluid or fixed width values for Canvas

canvas_url
string

The non-secure URL from which Canvas app content is loaded

category
string

The category of the app

client_config
map

Config data for the client

company
string

The company the app belongs to

configured_ios_sso
bool

True if the app has configured Single Sign On on iOS

contact_email
string

Email address listed for people using the app to contact developers

created_time
datetime

Timestamp that indicates when the app was created

creator_uid
id

User ID of the creator of this app

daily_active_users
numeric string

The number of daily active users the app has

daily_active_users_rank
unsigned int32

Ranking of this app vs other apps comparing daily active users

deauth_callback_url
string

URL that is pinged whenever a person removes the app

default_share_mode
string

The platform that should be used to share content

description
string

The description of the app, as provided by the developer

financial_id
string

The ID for the corresponding audience network financial entity.

hosting_url
string

Webspace created with one of our hosting partners for this app

icon_url
string

The URL of this app's icon

ios_bundle_id
list<string>

Bundle ID of the associated iOS app

ios_supports_native_proxy_auth_flow
bool

Whether to support the native proxy login flow

ios_supports_system_auth
bool

Whether to support the iOS integrated Login Dialog

ipad_app_store_id
string

ID of the app in the iPad App Store

iphone_app_store_id
string

ID of the app in the iPhone App Store

latest_sdk_version
ApplicationSDKInfo

App latest sdk version

link
string

A link to the app on Facebook

logging_token
string

To use for logging purposes

logo_url
string

The URL of the app's logo

migrations
map<string, bool>

Status of migrations for this app

mobile_profile_section_url
string

Mobile URL of the app section on a person's profile

mobile_web_url
string

URL to which Mobile users will be directed when using the app

monthly_active_users
numeric string

The number of monthly active users the app has

monthly_active_users_rank
unsigned int32

Ranking of this app vs other apps comparing monthly active users

name
string

The name of the app

namespace
string

The string appended to apps.facebook.com/ to navigate to the app's canvas page

object_store_urls

Mobile store URLs for the app

page_tab_default_name
string

The title of the app when used in a Page Tab

page_tab_url
string

The non-secure URL from which Page Tab app content is loaded

photo_url
string

The URL of the app photo

privacy_policy_url
string

The URL that links to a Privacy Policy for the app

profile_section_url
string

URL of the app section on a user's profile for the desktop site

property_id
string

The monetization property which owns this app

real_time_mode_devices
list<string>

List of real time hashed device

restrictions

Demographic restrictions for the app

restrictive_data_filter_params
string

Params used to filter out restrictive data

secure_canvas_url
string

The secure URL from which Canvas app content is loaded

secure_page_tab_url
string

The secure URL from which Page Tab app content is loaded

server_ip_whitelist
string

App requests must originate from this comma-separated list of IP addresses

social_discovery
unsigned int32

Indicates whether app usage stories show up in the Ticker or News Feed

subcategory
string

The subcategory the app can be found under

suggested_events_setting
string

Settings for suggested events

supported_platforms
list<enum {WEB, CANVAS, MOBILE_WEB, IPHONE, IPAD, ANDROID, WINDOWS, AMAZON, SUPPLEMENTARY_IMAGES, GAMEROOM, INSTANT_GAME}>

All the platform the app supports

terms_of_service_url
string

URL to Terms of Service that appears in the Login Dialog

url_scheme_suffix
string

URL scheme suffix

user_support_email
string

Main contact email for this app where people can receive support

user_support_url
string

URL shown in the Canvas footer that people can visit to get support for the app

website_url
string

URL of a website that integrates with this app

weekly_active_users
numeric string

The number of weekly active users the app has

Edges

EdgeDescription

Test User accounts associated with the app

Obtain the results of an async Audience Network query for this publisher entity

The businesses which are not owner but can advertise for this app

Info about App Events logged for the app

Insights data for this app

List of facebook groups the app is installed in

appassets

The ad accounts which are authorized to advertise for this app

List of people banned from this app

Whether to turn on auto device sampling.

Custom audience third party ID

A list of results after running Dynamic Ads checks on this app.

Events

Full app indexing information for the application for a specific app version

Gatekeeper for Mobile SDK

model_asset

Edge

Open Graph currency objects associated with this app

The status of permissions that are have been submitted for Login Review

In-app-purchaseable products associated with this app

In-app-purchaseable products of this app owned by the user

The developer roles defined for this app

Edge

Scores for the user and their friends

Deprecated

subscribed_domains

subscribed_domains_phishing

Edge

All of the subscriptions this app has for real-time notifications

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
190Invalid OAuth 2.0 Access Token
3000Reading insights of a Page, business, app, domain or event source group not owned by the querying user or application
294Managing advertisements requires an access token with the extended permission for ads_management

Creating

You can make a POST request to client_apps edge from the following paths:
When posting to this edge, an Application will be created.

Parameters

ParameterDescription
app_id

App ID.

Required

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
access_status: string,
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
You can make a POST request to owned_apps edge from the following paths:
When posting to this edge, an Application will be created.

Parameters

This endpoint doesn't have any parameters.

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
access_status: string,
}

Validation Rules

ErrorDescription
100Invalid parameter
You can make a POST request to app_indexing edge from the following paths:
When posting to this edge, an Application will be created.

Parameters

ParameterDescription
app_version
string

The version of the app being indexed

Required
device_session_id
string

Device session id of the uploading device

extra_info
string

Extra information about the app index

platform
enum {ANDROID, IOS}

The platform of the app being indexed

Required
request_type
enum {APP_INDEXING, PLUGIN, BUTTON_SAMPLING}
Default value: "APP_INDEXING"

Type of the app indexing request

tree
JSON object

The UI component tree of the app

Required
screenname
string

screenshot
string

view
list<JSON encoded app UI component>

Required

Return Type

Struct {
success: bool,
is_app_indexing_enabled: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
You can make a POST request to codeless_event_mappings edge from the following paths:
When posting to this edge, an Application will be created.

Parameters

ParameterDescription
mappings
array<JSON object>

The event to UI component mappings of the app

Required
mutation_method
enum {REPLACE, ADD, DELETE}

Detailed mutaiton type like replace, add

Required
platform
enum {ANDROID, IOS}

The platform of the app being indexed

Required
post_method
enum {EYMT, CODELESS}
Default value: "CODELESS"

Whether the api is called by codeless or EYMT

Return Type

Struct {
num_updated: int32,
num_invalid: int32,
}

Validation Rules

ErrorDescription
100Invalid parameter
105The number of parameters exceeded the maximum for this operation
You can make a POST request to mmp_auditing edge from the following paths:
When posting to this edge, an Application will be created.

Parameters

ParameterDescription
advertiser_id
string

Apple's Advertising Identifier (IDFA) or Google Android's advertising ID. You can see how Facebook fetches this on iOS or on Android

attribution
string

mobile_cookie from the person's device. Use this only on Android or iOS devices before iOS 6. The format for this should look something like DDDECD0A-C076-4050-8CE8-C20EC3FC2BD3

attribution_model
string

attribution model that clients selected to be respected by MMP

auditing_token
string

Token provided in cliam response sent to MMP

click_attr_window
int64

Time window of click attribution

custom_events
list<CustomEvent>

Custom app events that mmp are sending auditing events for

_eventName
RegexParam

Event name, must match the regular expression /^[0-9a-zA-Z_][0-9a-zA-Z _-]{0,39}$/

Required
_eventName_md5
RegexParam

MD5 hash of the event name, must match the regular expression /^[A-Fa-f0-9]{32}$/

_valueToSum
float

Values to Sum

_logTime
int64

Time to Log

_implicitlyLogged
int64

Whether this is implicitly logged

_isTimedEvent
boolean

Whether this is a timed event

_session_id
string

_app_user_id
string

decline_reason
string

Reason that MMP rejected Facebook ads claim

event
string

Event type that Facebook claimed for

Required
event_reported_time
int64

Time that event reported to MMP

fb_ad_id
int64

FBID of the ads in Facebook claim

Required
fb_click_time
int64

Ad click time in Facebook claim

fb_view_time
int64

Ad view time in Facebook claim

is_fb
boolean

Result that whether MMP attribute the event to Facebook ads

Required
view_attr_window
int64

Time window of view attribution

Return Type

Struct {
success: bool,
} Or Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
You can make a POST request to full_app_indexing_infos edge from the following paths:
When posting to this edge, an Application will be created.

Parameters

ParameterDescription
app_version
string

App Version

Required
full_app_indexing_info_classes
array<JSON object>

Array of full app indexing information for classes

Required

Return Type

Struct {
num_updated: int32,
is_app_indexing_enabled: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
43000Codeless Event Tracking set up is not enabled.
You can make a POST request to button_indexing edge from the following paths:
When posting to this edge, an Application will be created.

Parameters

ParameterDescription
app_version
string

app version

Required
device_id
string

id for device

extinfo
string

extra info

indexed_button_list
array<JSON object>

button list sent from app

Required

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
You can make a POST request to page_activities edge from the following paths:
When posting to this edge, an Application will be created.

Parameters

ParameterDescription
advertiser_tracking_enabled
boolean

A person can choose to enable ad tracking on iOS 6+, and that choice is stored within the phone. You should fetch that and return it to Facebook so we know not to use the data for optimization. We will, however, use the data to report on a conversion. See here for an example of how Facebook fetches that variable. For devices running less than iOS 6, this query parameter can default to 1. Use 0 for disabled, 1 for enabled

application_tracking_enabled
boolean

A person can choose to enable ad tracking on an app level. Your SDK should allow an app developer to put an opt-out setting into their app. Use this field to specify the person's choice. Use 0 for disabled, 1 for enabled

custom_events
list<CustomEvent>

Custom events reported

_eventName
RegexParam

Event name, must match the regular expression /^[0-9a-zA-Z_][0-9a-zA-Z _-]{0,39}$/

Required
_eventName_md5
RegexParam

MD5 hash of the event name, must match the regular expression /^[A-Fa-f0-9]{32}$/

_valueToSum
float

Values to Sum

_logTime
int64

Time to Log

_implicitlyLogged
int64

Whether this is implicitly logged

_isTimedEvent
boolean

Whether this is a timed event

_session_id
string

_app_user_id
string

logging_source
enum {MESSENGER_BOT}

Specifies the event source

logging_target
enum {APP, APP_AND_PAGE, PAGE}
Default value: "APP"

whether the event is logged to app level or page level or both

page_id
int64

Specifies the Page ID associated with the messenger bot that logs the event

page_scoped_user_id
int64

Specifies the page scoped User ID associated with the messenger bot that logs the event

Required

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter

Updating

Permissions

  • An app access token is required to update fields on an app.
You can update an Application by making a POST request to /{application_id}/codeless_event_bindings.

Parameters

ParameterDescription
bindings
array<JSON object>

Bindings to update

Required
mutation_method
enum {REPLACE, ADD, DELETE}

Mutation method to be used

Required
platform
enum {ANDROID, IOS}

Application platform

Required

Return Type

Struct {
num_updated: int32,
}

Validation Rules

ErrorDescription
100Invalid parameter
You can update an Application by making a POST request to /{application_id}.

Parameters

ParameterDescription
an_platforms
list<enum {IOS, ANDROID, MOBILE_WEB, DESKTOP, INSTANT_ARTICLES, UNKNOWN}>

The platforms associated with the app in the AudienceNetwork product

android_class_name
string

The Main Activity you want Facebook to launch

android_key_hash
list<string>

The app key hash for this app's Android native implementation

android_key_hashes
list<string>

SELF_EXPLANATORY

android_package_name
string

Unique app identifier used to open your app

android_sso
boolean

Will launch from Android Notifications

app_domains
list<string>

Specifies a list of domains that correspond to this app. Subdomains of domains in this array are also considered to belong to this app

app_name
string

App name

app_type
boolean

App type

auth_dialog_data_help_url
URL

The URL of a special landing page that helps users begin publishing Open Graph activity

auth_dialog_headline
string

One line description of this app that appears in the Login Dialog

auth_dialog_perms_explanation
string

The text to explain why an app needs additional permissions. This appears in the Login Dialog

auth_referral_default_activity_privacy
string

The default privacy setting selected for Open Graph activities in the Auth Dialog

auth_referral_enabled
boolean

Enables or disables Authenticated Referrals

auth_referral_extended_perms
list<string>

Extended permissions that a person can choose to grant when Authenticated Referrals are enabled

auth_referral_friend_perms
list<string>

Basic friends permissions that a person must grant when Authenticated Referrals are enabled

auth_referral_response_type
string

The format of the authentication token this app receives from the Login Dialog

auth_referral_user_perms
list<string>

Basic permissions that a person must grant when Authenticated Referrals are enabled

canvas_fluid_height
boolean

Indicates whether this app uses fluid or settable height values for Canvas

canvas_fluid_width
boolean

Indicates whether this app uses fluid or fixed width values for Canvas

canvas_url
URL

The non-secure URL from which Canvas app content is loaded

category
string

The category of this app

configured_ios_sso
boolean

Enables or disables SSO on iOS for this app

contact_email
string

Email address users can use to contact developers

created_time
time

Timestamp that indicates when this app was created

creator_uid
int

User ID of the creator of this app (employee-only)

deauth_callback_url
URL

URL that is pinged whenever a person removes this app

hosting_url
URL

Webspace created with one of our hosting partners for this app

ios_bundle_id
list<string>

Bundle ID of the associated iOS app

ipad_app_store_id
string

ID of this app in the iPad App Store

iphone_app_store_id
string

ID of this app in the iPhone App Store

migrations
JSON-encoded string

Update the status of each platform migration

mobile_web_url
URL

URL that mobile users will be directed to when using this app

namespace
string

The string appended to apps.facebook.com/ to navigate to this app's Canvas page

page_tab_default_name
string

The title of this app as it appears in a Page Tab

page_tab_url
URL

The non-secure URL from which Page Tab app content is loaded

privacy_policy_url
URL

The URL that links to a privacy policy for this app

restrictions
JSON-encoded string

Update demographic restrictions for this app

secure_canvas_url
URL

The secure URL from which Canvas app content is loaded

secure_page_tab_url
URL

The secure URL from which Page Tab app content is loaded

server_ip_whitelist
list<string>

App requests must originate from this comma-separated list of IP addresses

social_discovery
boolean

Indicates whether app stories show up in ticker or News Feed

subcategory
string

The subcategory this app can be found under

terms_of_service_url
URL

URL to Terms of Service that appears in the Login Dialog

url_scheme_suffix
string

URL scheme suffix

user_support_email
string

Main contact email for this app where people can receive support

user_support_url
URL

URL shown in the Canvas footer that people can visit to get support for this app

website_url
URL

URL of a website that integrates with this app

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
You can update an Application by making a POST request to /{application_id}/leaderboards_set_score.

Parameters

ParameterDescription
extra_data
string

Extra information associated with the score

name
string

The name of the leaderboard

Required
player_id
instant_game_player_id ID

The app-scoped ID of the player to post the score for

Required
score
int64

An integer score

Required

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
success: bool,
}

Validation Rules

ErrorDescription
3410Games player ID cannot be found.
100Invalid parameter
3412Player is not active.
200Permissions error
You can update an Application by making a POST request to /{application_id}/leaderboards_delete_entry.

Parameters

ParameterDescription
name
string

name of the leaderboard

Required
player_id
instant_game_player_id ID

player id that the leaderboard entry owned by

Required

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
success: bool,
}

Validation Rules

ErrorDescription
3407Games leaderboard name not found.
3411Games entry does not exist in this leaderboard.
3410Games player ID cannot be found.

Deleting

You can dissociate an Application from a Page by making a DELETE request to /{page_id}/subscribed_apps.

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {
success: bool,
messaging_success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
210User not visible
80001There have been too many calls to this Page account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.