Application
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.
Example
The Graffiti application:
https://graph.facebook.com/2439131959
Fields
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 |
|
daily_active_users_rank | Ranking of this app vs other apps comparing daily active users | 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 |
|
monthly_active_users_rank | Ranking of this app vs other apps comparing monthly active users | 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_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
Migrations
Read
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 |
Create
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.
Restrictions
Read
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 |
Create
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.
Properties
Read
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.
Create
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.
Connections
The application object has the following connections:
| Name | Description | Permissions | Returns |
| accounts | Test User accounts associated with the app. | App |
|
| achievements | Achievements registered for the app. | app |
|
| banned | Banned users from your app | Any valid app |
|
| groups | Groups for this app | App |
|
| insights | Usage metrics for this application. |
|
|
| payment_currencies | Open Graph currency objects associated with this application | app |
|
| 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 |
|
| videos | The videos uploaded to an application. |
|
|
Application Page Access Tokens
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.
accounts
Create
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 |
Delete
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.
banned
Read
Get list
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 |
Test whether user is banned
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 |
Create/Ban
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. 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 |
Delete/Un-ban
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.
groups
Please see the section on App and Game Groups for more information.
Read All Groups
Applications can get all the groups that belong to an application by issuing a GET request to /APP_ID/groups with an app access_token.
If the action is successful, the response will be an array that contains elements with the following properties:
| Name | Description | Type |
|---|---|---|
id |
The id of the group. | string |
name |
The name of the group. | string |
Create
Applications create a group issuing a POST request to /APP_ID/groups with an app access_token. Optionally, a user can be set as an admin of a group with the manage_groups permission.
| Parameter | Description | Type | Required |
|---|---|---|---|
name |
A name for the group. | string |
yes |
description |
A description for the group. | string |
no |
privacy |
The privacy setting for the group. | string (open, closed, secret) |
no (default: closed) |
admin |
The user ID of the admin. | string |
no |
If the action is successful, the response will contain:
| Name | Description | Type |
|---|---|---|
id |
The id of the group. | string |
Delete
Applications delete a group issuing a DELETE request to /APP_ID/groups/GROUP_ID with an app access_token.
If the group has no members, the group will be irreversibly deleted. If the group has members, the group will no longer be associated with the application and become a normal Facebook Group.
If the action is successful, the response will contain true.
payment_currencies
Create/Update
To map an Open Graph currency object to your app, issue an HTTP POST request to APP_ID/payment_currencies with an app access token. You must specify the following parameter:
| Parameter | Description | Type | Required |
|---|---|---|---|
currency_url |
The URL of an Open Graph fbpayments:currency object |
string |
yes |
You'll get the following value in return. Note that you should perform a Read to verify whether the POST made the expected change.
| Description | Type |
|---|---|
true or an error, depending on whether the request was well-formed. |
boolean |
Read
To get the list of currencies mapped to your application, issue an HTTP GET request to APP_ID/payment_currencies with an app access token. The first currency listed will be treated as your app's default currency.
An array is returned, each element being an object with the following properties.
| Name | Description | Type |
|---|---|---|
currency_id |
Open Graph ID of the currency object | int |
currency_url |
The canonical URL of the currency object, from itsog:url field |
string |
currency_title |
The og:title property specified in the currency object |
string |
currency_description |
The og:description from the currency object |
string |
Delete
To remove a currency association from your app, make an HTTP DELETE request to APP_ID/payment_currencies with an app access token.
| Parameter | Description | Type | Required |
|---|---|---|---|
currency_url |
The URL of an Open Graph fbpayments:currency object |
string |
yes |
The return takes the following form. Note that a return of true does not indicate that the deletion succeeded; to verify, read the app's currencies using the GET endpoint described above.
| Description | Type |
|---|---|
true, or an error depending on whether the request was well-formed. |
boolean |
For more details on the currency mapping feature, see the App Currency documentation.
roles
Read
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 |
Create
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.
Delete
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 |
staticresources
Get
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 |
subscriptions
Create / Update
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.
Delete
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.
translations
Create
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 |
Delete
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 |
scores
Read
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 |
Delete
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 |
achievements
Read
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 |
Create
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. |
Delete
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
- The app will no longer be able to publish that achievement for a user.
- The point value of the achievement is deducted from the app’s achievements point total.
- All existing user achievements for that achievement will not show up in the UI though they will still be available via the API.
Update
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.
videos
Create
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 |
Updated about 3 months ago