Graph API
Graph API Version

Facebook App

A Facebook app.

Reading

Get information about a Facebook app.

Permissions

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

Example

Graph API Explorer
GET /v21.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();
/* 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

Core
aam_rules
string

Rules of Auto Advanced Matching in FB SDKs

an_ad_space_limit
unsigned int32

The maximum number of Ad 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_events_config
ApplicationAppEventsConfig

Configuration for app events

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

Default
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

Core
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

CoreDefault
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

CoreDefault
namespace
string

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

CoreDefault
object_store_urls
ApplicationObjectStoreURLs

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

protected_mode_rules
ApplicationProtectedModeRules

protected_mode_rules

real_time_mode_devices
list<string>

List of real time hashed device

restrictions
ApplicationRestrictionInfo

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 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, OCULUS, SAMSUNG, XIAOMI}>

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
accounts
Edge<TestAccount>

Test User accounts associated with the app

ad_placement_groups
Edge<AdPlacementGroup>

Ad placement groups for publishing ads on this app

adnetworkanalytics_results
Edge<AdNetworkAnalyticsAsyncQueryResult>

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

aem_attribution
Edge<AEMAttribution>

aem_attribution

aem_conversion_configs
Edge<AEMConversionConfig>

The aggregated event measurement conversion value configs for this app

aem_conversion_filter
Edge<AEMConversionFilter>

Boolean for if product_set_id [fb_content_id] belongs to a certain catalog [catalog_id]

agencies
Edge<Business>

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

app_event_types
Edge<ApplicationAppEventTypes>

Info about App Events logged for the app

app_installed_groups
Edge<Group>

List of facebook groups the app is installed in

appassets
Edge<CanvasAppAsset>

appassets

button_auto_detection_device_selection
Edge<ButtonAutoDetectionDeviceSelection>

Whether to turn on auto device sampling.

cloudbridge_settings
Edge<CloudbridgeSetting>

cloudbridge_settings

da_checks
Edge<DACheck>

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

ios_skadnetwork_conversion_config
Edge<ConversionConfig>

ios_skadnetwork_conversion_config

mobile_sdk_gk
Edge<MobileSdkGk>

Gatekeeper for Mobile SDK

model_asset
Edge<SDKMLModel>

model_asset

monetized_digital_store_objects
Edge<MonetizedDigitalStoreObject>

List of digital store objects for this app monetized via Audience Network

object_types
Edge<Null>

Open Graph Object types associated with this app

objects
Edge<Null>

Open Graph objects

permissions
Edge<ApplicationPermission>

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

products
Edge<GamesIAPProduct>

In-app-purchaseable products associated with this app

purchases
Edge<GamesIAPOrder>

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

roles
Edge<ApplicationRoles>

The developer roles defined for this app

subscribed_domains
Edge<CTCertDomain>

subscribed_domains

subscribed_domains_phishing
Edge<CTCertDomain>

subscribed_domains_phishing

whatsapp_business_solutions
Edge<WhatsAppBusinessSolution>

Lists the WhatsApp Business Partner Solution objects that the application participate in.

Error Codes

ErrorDescription
100Invalid parameter
190Invalid OAuth 2.0 Access Token
200Permissions error
459The session is invalid because the user has been checkpointed
368The action attempted has been deemed abusive or is otherwise disallowed
2500Error parsing graph query
3000Reading insights of a Page, business, app, domain or event source group not owned by the querying user or application
104Incorrect signature

Creating

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,
}

Error Codes

ErrorDescription
415Two factor authentication required. User have to enter a code from SMS or TOTP code generator to pass 2fac. This could happen when accessing a 2fac-protected asset like a page that is owned by a 2fac-protected business manager.
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,
}

Error Codes

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
method
enum {INFERENCE, MANUAL, CONFIRMED_INFERENCE, BUTTON_INDEXING, UNKNOWN}

method

Required
event_name
string

event_name

Required
event_type
enum {CLICK, SELECTED, TEXT_CHANGED}

event_type

Required
app_version
string

app_version

Required
parameters
array<JSON object>

parameters

name
string

name

Required
path
array<JSON object>

path

Required
class_name
string

class_name

Required
index
int64

index

Required
id
int64

id

text
string

text

tag
string

tag

description
string

description

hint
string

hint

match_bitmask
int64

match_bitmask

path_type
enum {ABSOLUTE, RELATIVE}
Default value: "ABSOLUTE"

path_type

component_id
string

component_id

Required
path
array<JSON object>

path

Required
class_name
string

class_name

Required
index
int64

index

Required
id
int64

id

text
string

text

tag
string

tag

description
string

description

hint
string

hint

match_bitmask
int64

match_bitmask

component_id
string

component_id

Required
path_type
enum {ABSOLUTE, RELATIVE}
Default value: "ABSOLUTE"

path_type

screenshot_handle
string

screenshot_handle

dimensions
array<JSON object>

dimensions

top
int64

top

Required
left
int64

left

Required
width
int64

width

Required
height
int64

height

Required
activity_name
string

activity_name

mutation_method
enum {REPLACE, ADD, DELETE}

Detailed mutation 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,
}

Error Codes

ErrorDescription
105The number of parameters exceeded the maximum for this operation
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: enum,
}

Error Codes

ErrorDescription
100Invalid parameter
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 claim 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

engagement_type
string

Engagement type that MMP explicitly reports

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
used_install_referrer
boolean

Identifies whether MMP used the install referrer

view_attr_window
int64

Time window of view attribution

Return Type

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

Error Codes

ErrorDescription
100Invalid parameter

Updating

Update application information such as demographic restrictions.

Permissions

  • An app access token is required to update fields on an app.

Example

To update an app restrictions, such as age, send a POST request to /{app-id}:

curl -i -X POST "https://graph.facebook.com/{app-id}?restrictions={'age':'21+'}&access_token={app-access-token}"

On success your app receives this response:

{ "success": true }

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

Parameters

ParameterDescription
allow_cycle_app_secret
boolean
Default value: false

Allows for the application to cycle the secret

an_platforms
list<enum {ANDROID, DESKTOP, GALAXY, INSTANT_ARTICLES, IOS, MOBILE_WEB, OCULUS, UNKNOWN, XIAOMI}>

The platforms associated with the app in the AudienceNetwork product

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_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_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

contact_email
string

Email address users can use to contact developers

deauth_callback_url
URL

URL that is pinged whenever a person removes this app

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

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. Can be one or more of the following parameters: age, location, or type. age can be one of the following values: 13+, 16+, 17+, 18+, 19+, or 21+. location can be one or more country represented by the 2 letter country code. type can only be alcohol.

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

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,
}

Error Codes

ErrorDescription
104Incorrect signature
100Invalid parameter
200Permissions error
You can update an Application by making a POST request to /act_{ad_account_id}/subscribed_apps.

Parameters

ParameterDescription
app_id
string
Default value:

the id of app to be subscribed from ad account

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
success: bool,
}

Error Codes

ErrorDescription
100Invalid parameter
200Permissions error
80004There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting#ads-management.
190Invalid OAuth 2.0 Access Token

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,
}

Error Codes

ErrorDescription
100Invalid parameter
200Permissions error
190Invalid OAuth 2.0 Access Token
210User not visible
104Incorrect signature
You can dissociate an Application from an AdAccount by making a DELETE request to /act_{ad_account_id}/subscribed_apps.

Parameters

ParameterDescription
app_id
string
Default value:

the id of app to be unsubscribed from ad account

Return Type

Struct {
success: bool,
}

Error Codes

ErrorDescription
100Invalid parameter