There are three access levels to the Marketing APIs. You can upgrade access after you meet criteria described later. Note that calls on ANY access level are against production data.
Try and test apps with the API.
Test, iterate, build apps with up to 25 external accounts.
Support unlimited accounts and be nominated to Facebook Marketing Partner program.
Default for all apps. Use if you are starting to build a tool. Open to all developers, so you can build end-to-end workflows before you get full permissions. Use the API as admin and access up to 5 ad accounts for people who are admins or advertisers. To set up the ad account list, see Standard Accounts.
Some API calls are not available with Development or Basic access because they may belong to multiple accounts, or the affected account can't be identified programmatically.
To scale out to a limited set of initial customers.
Once you have an app, apply for basic access through your app's 'Status and Review' panel. Submit an application for the 'Ads Management Basic Access' Feature. See Basic Application. To check if you have basic access, see app dashboard, 'Status and Review' with 'Ads Management Basic Access':
For heavy ad demands; no limit on number of customer accounts. You get this level only after acceptance to the basic level, you cannot skip levels. Submit your app to Standard Access.
Facebook responds with an approval or denial, and information if your app is not qualified for standard access. A denial does not revoke basic access.
To check for standard access, go to app dashboard, 'Status and Review' and you see:
Up to 5 accounts in the account list associated with your app. API calls from app admins or developers and on behalf of ad account admins or advertisers.
25 ad accounts, defined by the account list associated with your app.
Manage unlimited ad accounts with Marketing API app
Heavily rate-limited per ad account. For development only. Not for production apps running for live advertisers.
Moderately rate limited per ad account
Lightly rate limited per ad account
Can create 1 system user and 1 admin system user
Can create 3 system users and 1 admin system user
Can create 10 system users and 1 admin system user
Cannot create pages through the API.
Cannot create pages through the API.
Can create pages through the API.
To apply for basic access, go to app, 'Status and Review' and create a new submission:
Submit apps for 'Ads Management Basic Access':
After your app is accepted, make API calls for up to 25 ad accounts. To define these accounts, set up an account list. You still need to ask for
ads_management permission for Ads Management) or
ads_read permission for Ads Insights.
If you use the Pages API, request
manage_pages permissions to manage page posts for each page. If your app uses the
manage_pages permission, you need a separate app review from Marketing API access.
We automatically add accounts that you make API calls against to your account lists, up to the maximum number for your access level. If you exceed this limit, API calls return an error. Use the Ads API account configuration tool to add or remove accounts from this list.
In your app dashboard, go to Apps > Settings > Advanced. Under Advertising Accounts click Marketing API. The account configuration tool opens.
Enter in an account ID. You should enter a numeric value; do not include
act_ from the account ID. Check the account IDs match exactly. When you reach your maximum,
Add is disabled.
Using Marketing API with business accounts
Someone grants your app access to manage their ads. If the ad accounts belong to a business in Business Manager, ask the business admins to check that people using your app can access the ad accounts in your app. Sharing Logins is not supported; instead you should use Business Manager.
Use development access to build an application
Learn how to develop on the API, build and test your application, test it, and add features to expand our ecosystem's capabilities. You should use development access to:
Evaluating acceptance for access
There are several factors we evaluate and the specific details for each level are above.
Time to review apps for basic and standard access?
Going from development to basic access requires review in about 3 business days. Review times depend on the load of apps being reviewed.
Basic to standard access requires more in-depth business review, averaging two weeks but depends on the complexity of the app and its business case.
Existing standard access and creating new applications
All new App ID default to development access and must go through the access levels, regardless of access of previous apps.
Becoming a Facebook Marketing Partner and Badging
Developers with Standard access are not automatically included in the Facebook Marketing Program. After you get Standard access, you can be nominated to become a Facebook Marketing Partner, and get a badge and speciality designations for your expertise. You can benefit from credibility, marketing support, training and other benefits, see FMD Program.
Use the bug tool to file issues and the Facebook Marketing Developer community to ask questions. Additional resources here:
You can get access this way in advanced scenarios. Typically it's easier to get this token in Ads App Tool when you create a new app. If you are use the Facebook SDKs and want to manually get a token, see Marketing API, SDKs. See:Ads App Tool
To manually get a token with the API, see Understanding Access Tokens, Video
For apps to manage ads, someone must grant the app
ads_read extended permission. Use
ads_read if you only need Ad Insights API access, to pull reporting information, see Ads Insights API. Use
ads_management when you need to read, create and update ads.
Depending on API you use, you need to ask for different permissions:
- Ads Management
- Business Manager API
- Audience Management
- Insights API
Note the following values from your App Summary shown in examples below:
scope parameter to prompt someone for
ads_read permissions. Your app gets access when someone clicks
https://www.facebook.com/<API_VERSION>/dialog/oauth? client_id=<YOUR_APP_ID> &redirect_uri=<YOUR_URL> &scope=ads_management
When inputting the YOUR_URL field, put a trailing
/. e.g. http://www.facebook.com/
Get a test user access token with Graph API Explorer:
Check the properties in Access Token Debugger
Expires. See Long-Lived Access Token.
Check the properties of this page access token in Access Token Debugger:
If the user clicks the Allow button when you prompt for the extended permissions, the user is redirected to a URL that contains the value of the redirect_uri parameter and an authorization code:
Build a URL that includes the endpoint for getting a token, your app ID, your site URL, your app secret, and the authorization code you just received. The URL will be similar to the following:
https://graph.facebook.com/<API_VERSION>/oauth/access_token? client_id=<YOUR_APP_ID> &redirect_uri=<YOUR_URL> &client_secret=<YOUR_APP_SECRET> &code=<AUTHORIZATION_CODE>
The response should contain the access token for the user. For additional information, see the authentication guide.
The token should be stored in your database for subsequent API calls.
You should regularly check for validity of the token, and if necessary prompt the user for permission. Even a persistent token can become invalid in a few cases including the following:
As access tokens can be invalidated or revoked anytime, your app should be written to expect that and have a flow to re-request permission from the user. When a user starts your web app, check the validity of the token you have for that user and send them through the authentication flow to get an updated token if necessary. If this is not possible for your app (e.g., API calls are not directly triggered by a user interface, or are made by periodically run scripts) a different way to prompt the user may be necessary. For example, your app could email instructions to the user.