An application registered on Facebook Platform as represented in the Graph API. Applications a user administers can be retrieved via the /accounts connection on the User object.
To create, administer or delete applications developers must go to the App Dashboard.
The Graffiti application:
https://graph.facebook.com/2439131959
The application object has the following fields:
| Name | Description | Permissions | Returns |
id | The application ID | No |
|
name | The title of the application | No |
|
description | The description of the application written by the 3rd party developers | No |
|
category | The category of the application | No |
|
company | The company the application belongs to | No |
|
icon_url | The URL of the application's icon | No |
|
subcategory | The subcategory of the application | No |
|
link | A link to the | No |
|
logo_url | The URL of the application's logo | No |
|
daily_active_users | The number of daily active users the application has | No |
|
weekly_active_users | The number of weekly active users the application has | No |
|
monthly_active_users | The number of monthly active users the application has | No |
|
migrations | Migrations settings for app profile (Editable via API) | App |
|
namespace | The namespace for the app (Editable via API) | No |
|
restrictions | Demographic restrictions set for this app (Editable via API) | App | Object with one or more of the following fields: |
app_domains | Domains and subdomains this app can use (Editable via API) | App |
|
auth_dialog_data_help_url | The URL of a special landing page that helps users of an app begin publishing Open Graph activity (Editable via API) | App |
|
auth_dialog_description | The description of an app that appears in the Auth Dialog (Editable via API) | App |
|
auth_dialog_headline | One line description of an app that appears in the Auth Dialog (Editable via API) | App |
|
auth_dialog_perms_explanation | The text to explain why an app needs additional permissions that appears in the Auth Dialog (Editable via API) | App |
|
auth_referral_user_perms | Basic user permissions that a user must grant when Authenticated Referrals are enabled (Editable via API) | App |
|
auth_referral_friend_perms | Basic friends permissions that a user must grant when Authenticated Referrals are enabled (Editable via API) | App |
|
auth_referral_default_activity_privacy | The default privacy setting selected for Open Graph activities in the Auth Dialog (Editable via API) | App |
|
auth_referral_enabled | Indicates whether Authenticated Referrals are enabled (Editable via API) | App |
|
auth_referral_extended_perms | Extended permissions that a user can choose to grant when Authenticated Referrals are enabled (Editable via API) | App |
|
auth_referral_response_type | The format that an app receives the Auth token from the Auth Dialog in (Editable via API) | App |
|
canvas_fluid_height | Indicates whether app uses fluid or settable height values for Canvas (Editable via API) | App |
|
canvas_fluid_width | Indicates whether app uses fluid or fixed width values for Canvas (Editable via API) | App |
|
canvas_url | The non-secure URL from which Canvas app content is loaded (Editable via API) | App |
|
contact_email | Email address listed for users to contact developers (Editable via API) | App |
|
created_time | Unix timestamp that indicates when the app was created | App |
|
creator_uid | User ID of the creator of this app | App |
|
deauth_callback_url | URL that is pinged whenever a user removes the app (Editable via API) | App |
|
iphone_app_store_id | ID of the app in the iPhone App Store | App |
|
hosting_url | Webspace created with one of our hosting partners for this app | App |
|
mobile_web_url | URL to which Mobile users will be directed when using the app (Editable via API) | App |
|
page_tab_default_name | The title of the app when used in a Page Tab (Editable via API) | App |
|
page_tab_url | The non-secure URL from which Page Tab app content is loaded (Editable via API) | App |
|
privacy_policy_url | The URL that links to a Privacy Policy for the app (Editable via API) | App |
|
secure_canvas_url | The secure URL from which Canvas app content is loaded (Editable via API) | App |
|
secure_page_tab_url | The secure URL from which Page Tab app content is loaded (Editable via API) | App |
|
server_ip_whitelist | App requests must originate from this comma-separated list of IP addresses (Editable via API) | App |
|
social_discovery | Indicates whether app usage stories show up in the Ticker or News Feed (Editable via API) | App |
|
terms_of_service_url | URL to Terms of Service which is linked to in Auth Dialog (Editable via API) | App |
|
user_support_email | Main contact email for this app (Editable via API) | App |
|
user_support_url | URL of support for users of an app shown in Canvas footer (Editable via API) | App |
|
website_url | URL of a website that integrates with this app (Editable via API) | App |
|
You can choose the properties you want returned using the fields query parameter
https://graph.facebook.com/APP_ID?fields=id,name
To retrieve a list of migration settings from an app, issue an HTTP GET with an app access token to https://graph.facebook.com/APP_ID?fields=migrations
You get the following returned:
| Name | Description | Type |
|---|---|---|
migrations |
Array of all migrations and enabled/disabled | array |
id |
App ID | string |
To set a list of migrations for an app, issue an HTTP POST with an app access token to https://graph.facebook.com/APP_ID?migrations={"MIGRATION_NAME":1/0}
This returns true if successful.
See examples here.
To retrieve a list of demographic restrictions on an app, issue an HTTP GET with an app access token to https://graph.facebook.com/APP_ID?fields=restrictions
This will return a object with zero or more of the following fields, depending on which restrictions are set:
| Name | Description | Type |
|---|---|---|
location |
Restriction based on location, such as 'DE' for apps restricted to Germany | string |
age |
Minimum age restriction | string |
age_distribution |
Restriction based on an age range | string |
id |
App ID; read-only field. | string |
type |
Always application for apps; read-only field. |
string |
To set a list of restrictions for an app, issue an HTTP POST with an app access token to https://graph.facebook.com/APP_ID?restrictions={"RESTRICTION":"VALUE"}. More than one value can be set at a time in the JSON object for the value of there restrictions parameter.
This returns true if successful.
See examples here.
To retrieve a list of properties from an app, issue an HTTP GET with an app access token to https://graph.facebook.com/APP_ID?fields=PROPERTY_NAME using the property values above in a comma-separated list. The returned values for all properties are listed in the table above.
To set properties for an app, issue an HTTP POST with an app access token to https://graph.facebook.com/APP_ID?PROPERTY_1=PROPERTY_VALUE&PROPERTY_2=PROPERTY_VALUE2 using the same properties and formats as in the table above. Not all app properties can be edited via the API, please refer to the properties in the table above for an indication of whether a property can be edited or not. Array properties can be unset by passing an empty array.
This returns true if successful.
The application object has the following connections:
| Name | Description | Permissions | Returns |
| accounts | Test User accounts associated with the app. | App |
|
| banned | Banned users from your app | Any valid app |
|
| insights | Usage metrics for this application. |
|
|
| payments | The list of Facebook Credits orders associated with the application. | app |
|
| picture | The application's profile picture with maximum dimensions of 75x75 pixels suitable for embedding as the source of an image tag. | Publicly available | An HTTP 302 with the location set to the picture URL. |
| roles | The developer roles defined for this application. | App |
|
| staticresources | Usage stats about the canvas application's static resources, such as javascript and CSS, and which ones are being flushed to browsers early. | Application owner |
|
| subscriptions | All of the subscriptions this application has for real-time notifications. | application |
|
| translations | The translated strings for this application. | application |
|
| scores | Scores for the user and their friends. | user |
|
| achievements | Achievements registered for the app. | app | Not yet implemented |
| videos | The videos uploaded to an application. |
|
|
To perform the following operations as an Application Page, and not the current user, you must use the Application's Page access token, not the user access token commonly used for modifying Graph API objects nor the Application access token. 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 an access_token for each Page.
Note: Applications that are configured as Native/Desktop apps will not be able to make API calls that require an application access_token.
You can create a test account for an application by issuing an HTTP POST request to APP_ID/accounts/test-users with an application access token (i.e. a token created using the app secret, not an application Page access token as described above). You can specify the following parameters.
| Parameter | Description | Type | Required |
|---|---|---|---|
installed |
Install app for the test user upon creation | boolean |
no |
permissions |
List of extended permissions app granted for the new test user if installed is true |
string |
no |
name |
A name for the test user. The specified name will also be used in the email address assigned to the test user. | string |
no |
If the create is successful, you get the following return.
| Name | Description | Type |
|---|---|---|
id |
The new test user ID | string |
access_token |
Test user access token to make API calls | string |
login_url |
Test user automatic login URL. Expires after first use or within an hour for security reasons. | string |
email |
The new test user email | string |
password |
The new test user password | string |
You can delete a test account by issuing an HTTP DELETE request to TEST_USER_ID with a user or application access token.
If the delete is successful, you get the following return.
| Description | Type |
|---|---|
| If the delete succeeded | boolean |
See Test User accounts for more details on managing test accounts.
You can retrieve a list of banned users for an app by issuing an HTTP GET request to APP_ID/banned with an application access token (i.e. a token created using the app secret, not an application Page access token as described above).
You get the following return.
| Parameter | Description | Type |
|---|---|---|
name |
Name of banned user | string |
uid |
User id of banned user | string |
You can test if a given user is banned for an app by issuing an HTTP GET request to APP_ID/banned/USER_ID with an application access token (i.e. a token created using the app secret, not an application Page access token as described above).
You get the following return.
| Parameter | Description | Type |
|---|---|---|
name |
Name of banned user | string |
uid |
User id of banned user | string |
You can ban a user for an app by issuing an HTTP POST request to APP_ID/banned?uid=USER_ID1,USER_ID2 with an application access token (i.e. a token created using the app secret, not an application Page access token as described above). You can specify the following parameters.
| Parameter | Description | Type | Required |
|---|---|---|---|
uid |
User ID of user account | string |
yes |
If the ban is successful, you get the following return.
| Description | Type |
|---|---|
| If ban succeeded | boolean |
You can un-ban a user account by issuing an HTTP DELETE request to USER_ID with an application access token.
If the un-banning is successful, you get the following return.
| Description | Type |
|---|---|
| If un-ban succeeded | boolean |
See this blog post for more details on retrieving, banning, testing, and un-banning users.
You can create a link, post or status message by issuing an HTTP POST request to the APP_ID/feed connection. To see more details please see links, posts, and status messages documentation.
To impersonate the Application when posting to the wall (i.e. post as the Application, and not the current user), you must use an Application Page access_token with the manage_pages and publish_stream permissions, as described under Application Access Tokens above.
You can post a link on the application's profile page by issuing an HTTP POST request to APP_ID/feed with the publish_stream 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 |
You can create a post on an application's profile page by issuing an HTTP POST request to APP_ID/feed (not PROFILE_ID/posts) with the publish_stream permissions and the following parameters.
| Parameter | Description | Type | Required |
|---|---|---|---|
message |
Post message | string |
yes |
link |
Post URL | string |
yes |
picture |
Post thumbnail image | string |
no |
name |
Post name | string |
no |
caption |
Post caption | string |
no |
description |
Post description | string |
no |
actions |
Post actions | array of objects containing name and link |
no |
privacy |
Post privacy settings | string |
no |
If the create is successful, you get the following return.
| Name | Description | Type |
|---|---|---|
id |
The new post ID | string |
You can retrieve a list of all users who have a role defined for an application by issuing an HTTP GET request to APP_ID/roles with an app access token. This will return an array of objects with the following fields.
| Parameter | Description | Type |
|---|---|---|
app_id |
Application ID being queried | string |
user |
User ID | string |
role |
User's defined role for this application | string |
You can define a role for a user by issuing an HTTP POST request to APP_ID/roles with a user access token for an administrator of the app, specifying the following fields.
| Parameter | Description | Type |
|---|---|---|
user |
User ID to have a role added to the app | string |
role |
Role the user should assume, one of 'administrators', 'developers', 'testers' or 'insights users' | string |
Response:
| Description | Type |
|---|---|
| true or error depending on whether the role creation was successful. | boolean |
The user that has been added will be sent a request via the App Dashboard.
You can remove a defined user role from an app by issuing an HTTP DELETE request to /APP_ID/roles with a user access token for an administrator of the app, specifying the following parameter.
| Name | Description | Type | Required |
|---|---|---|---|
user |
User ID whose role should be removed | string |
yes |
Response:
| Description | Type |
|---|---|
| true or error depending on whether the delete was successful. | boolean |
Gets usage statistics for the static resources used by your Canvas IFrame application. These statistics are collected for the purpose of flushing some of them to the browser early, to improve application performance.
| Name | Description | Type |
|---|---|---|
usage_stats |
An array, keyed by static resource URL, whose values are fractions of page loads that used each static resource. | array |
flushed_resources |
An array of static resource URLs, which is a subset of those in the usage_stats array, that are currently being flushed early for users who are using the application. | array |
You can post a status message on an application's profile page by issuing an HTTP POST request to APP_ID/feed with the publish_stream 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 |
You can set up a subscription by issuing an HTTP POST request to APP_ID/subscriptions with an application page access token and the following parameters.
| Parameter | Description | Type | Required |
|---|---|---|---|
object |
Object to monitor - user, permissions, or page. |
string |
yes |
fields |
List of properties for the object to monitor. | string |
array |
callback_url |
A callback URL to which Facebook will post subscription updates. | string |
yes |
verify_token |
Token sent in the verification request. | string |
no |
Note that you must first set up an endpoint URL to handle subscription verification and updates. For details see the Real-time API subscriptions documentation.
Your create is successful if you do not get an error.
You can delete subscriptions by issuing an HTTP DELETE request to APP_ID/subscriptions with an application access token.
| Parameter | Description | Type | Required |
|---|---|---|---|
object |
Object to monitor - user, permissions, or page. If no object is specified all subscriptions are deleted. |
string |
no |
Your create is successful if you do not get an error.
See the Real-time API documentation for more details on managing subscriptions.
You can upload application strings for translation by issuing an HTTP POST request to APP_ID/translations with an application access token.
| Parameter | Description | Type | Required |
|---|---|---|---|
native_strings |
A JSON-encoded array of strings to translate. Each element of the string array is an object, with text storing the actual string, description storing the description of the text. |
array |
yes |
If the create is successful, you get the following return.
| Name | Description | Type |
|---|---|---|
id |
The number of strings uploaded | number |
You can delete a translation string by issuing an HTTP DELETE request to APP_ID/translations with an application access token.
| Parameter | Description | Type | Required |
|---|---|---|---|
native_hashes |
An array of native hashes. The native hash is a unique identifier of the native string and a description and is generated by the Translations application. | array |
yes |
If the delete is successful, you get the following return.
| Name | Description | Type |
|---|---|---|
id |
The number of strings deleted | number |
You can read the scores for the user and their friends for your app by issuing an HTTP GET request to /APP_ID/scores with the user access_token for that app. This returns the list of scores for the user and their friends who have a
uthorized the app. You can use this api to create leaderboard for the user and their friends.
The API returns an array of objects containing the following data:
| Name | Description | Type |
|---|---|---|
| user | User associated with the scores. | object containing the name and id for the user. |
| score | Numeric score. | integer |
| application | App associated with the score. | object containing the name and id of the app. |
| type | type of the data which is "score". | string |
You can delete all the scores for your app by issuing an HTTP DELETE request to /APP_ID/scores with the app access_token for that app. This will reset the scores for your app. Use this if you'd like to periodically reset your game's scores and leaderboards.
Response
| Description | Type |
|---|---|
| true or error depending on whether the delete was successful. | boolean |
You can get all achievements for an app by issuing an HTTP GET request to /APP_ID/achievements with an app access_token. This will return an array of achievement objects where each achievement object has the following fields.
| Name | Description | Type |
|---|---|---|
| id | ID of the achievement object. | string |
| type | The value should be games.achievement. |
string |
| title | Achievement’s title. | string |
| url | The unique URL of the achievement. | string |
| description | An achievement’s description. | string |
| image | image for the achievement. | an array of objects, containing a URL for the image. |
| points | Number of points that this achievement is worth. Total points per game may not exceed 1000 points limit, which we enforce. | an object containing points |
| updated_time | Time when the achievement was last updated. | string containing an ISO-8601 datetime |
| context | contains context of the achievement for the associated app. | array containing the display_order |
You can register an achievement for a game by issuing an HTTP POST to APP_ID/achievements with an app access_token and the following parameters.
| Name | Description | Type | Required |
|---|---|---|---|
| achievement | Unique URL to the achievement. | string |
yes |
| display_order | Order of this achievement as it shows up in the achievement stories UI (low to high). For example a display order of 100 will be displayed in the UI before 200. We use this value to surface achievements according to the order the developer has specified. Please make sure this value is unique and increments in the correct order for your achievements. | integer |
no |
Response:
| Description | Type |
|---|---|
| true or error depending on whether the registration was successful. | boolean |
| Error Code | Description |
|---|---|
| 100 | Service error |
| 3401 | If an app tries to register more than the maximum number(1000) of achievements. |
| 3402 | When the app tries to register an achievement that would raise the app’s point total above the 1000-point limit. |
You can un-register an achievement for a game by issuing an HTTP DELETE request to /APP_ID/achievements with an app access_token and the following parameter.
| Name | Description | Type | Required |
|---|---|---|---|
| achievement | The unique URL to the achievement. | string |
yes |
Response
| Description | Type |
|---|---|
| true or error depending on whether the delete was successful. | boolean |
When a developer deletes an achievement, it un-registers it from the app which means
A developer may update the <meta> tag property values of their achievement by forcing a re-scrape of it’s Open Graph URL using the Facebook Linter. Please note that after a significant number of publishes, the property values are locked and cannot be edited.
A developer may update the custom properties of an achievement registration (e.g. display_order) by re-POSTing with the same achievement parameter value, but with an updated custom registration property value.
You can publish a video to an Application by issuing an HTTP POST request to https://graph-video.facebook.com/PAGE_ID/videos with the publish_stream permission 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 |