# Meta / Facebook Developer Docs Mirror -- Full Content > Full text of every page in this mirror, for LLMs that want the whole corpus in one request. See /llms.txt for just the page index. --- # Batch Requests Source: https://developers.facebook.com/docs/graph-api/batch-requests Mirror: https://nermalcat69.github.io/meta-developer-docs/docs/graph-api/batch-requests.html # Batch Requests Send a single HTTP request that contains multiple Facebook Graph API calls. Independent operations are processed in parallel while dependent operations are processed sequentially. Once all operations are complete, a consolidated response is passed back to you and the HTTP connection is closed. The ordering of responses correspond with the ordering of operations in the request. You should process responses accordingly to determine which operations were successful and which should be retried in a subsequent operation. ### Limitations * Batch requests are limited to 50 requests per batch. Each call within the batch is counted separately for the purposes of calculating API call limits and resource limits. For example, a batch of 10 API calls will count as 10 calls and each call within the batch contributes to CPU resource limits in the same manner. Please see our [Rate Limiting Guide](https://developers.facebook.com/docs/graph-api/overview/rate-limiting) for more information. * Batch requests cannot include multiple [Adsets](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign) under the same [Campaign](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group). Learn more about [batching Marketing API requests](https://developers.facebook.com/docs/marketing-api/asyncrequests). ## Batch Request A batch request takes a JSON object consisting of an array of your requests. It returns an array of logical HTTP responses represented as JSON arrays. Each response has a status code, an optional headers array, and an optional body (which is a JSON encoded string). To make a batched request, send a `POST` request to an endpoint where the `batch` parameter is your JSON object. ``` POST /ENDPOINT?batch=[JSON-OBJECT] ``` **Sample Batch Request** In this example, we are getting information about two Pages that our app manages. *Formatted for readability.* ``` curl -i -X POST 'https://graph.facebook.com/me?batch= [ { "method":"GET", "relative_url":"PAGE-A-ID" }, { "method":"GET", "relative_url":"PAGE-B-ID" } ] &include_headers=false // Included to remove header information &access_token=ACCESS-TOKEN' ``` Once all operations are complete, a response is sent with the result of each operation. Because the headers returned can sometimes be much larger than the actual API response, you might want to remove them for efficiency. To include header information, remove the `include_headers` parameter or set it to `true`. **Sample Response** The body field contains a string encoded JSON object: ``` [ { "code": 200, "body": "{ \"name\": \"Page A Name\", \"id\": \"PAGE-A-ID\" }" }, { "code": 200, "body": "{ \"name\": \"Page B Name\", \"id\": \"PAGE-B-ID\" }" } ] ``` ## Complex Batch Requests It is possible to combine operations that would normally use different HTTP methods into a single batch request. While `GET` and `DELETE` operations can only have a `relative_url` and a `method` field, `POST` and `PUT` operations may contain an optional `body` field. The body should be formatted as a raw HTTP POST string, similar to a URL query string. **Sample Request** The following example publishes a post to a Page we manage and have publish permissions and then the Page's feed in a single operation: ``` curl "https://graph.facebook.com/PAGE-ID?batch= [ { "method":"POST", "relative_url":"PAGE-ID/feed", "body":"message=Test status update" }, { "method":"GET", "relative_url":"PAGE-ID/feed" } ] &access_token=ACCESS-TOKEN" ``` The output of this call would be: ``` [ { "code": 200, "headers": [ { "name":"Content-Type", "value":"text/javascript; charset=UTF-8"} ], "body":"{\"id\":\"…\"}" }, { "code": 200, "headers": [ { "name":"Content-Type", "value":"text/javascript; charset=UTF-8" }, { "name":"ETag", "value": "…" } ], "body": "{\"data\": [{…}]} } ] ``` The following example creates a new ad for a campaign, and then gets the details of the newly created object. Note the **URLEncoding** for the body param: ``` curl \ -F 'access_token=...' \ -F 'batch=[ { "method":"POST", "name":"create-ad", "relative_url":"11077200629332/ads", "body":"ads=%5B%7B%22name%22%3A%22test_ad%22%2C%22billing_entity_id%22%3A111200774273%7D%5D" }, { "method":"GET", "relative_url":"?ids={result=create-ad:$.data.*.id}" } ]' \ https://graph.facebook.com ``` The following example adds multiple pages to a Business Manager: ``` curl \ -F 'access_token=' \ -F 'batch=[ { "method":"POST", "name":"test1", "relative_url":"/owned_pages", "body":"page_id=" }, { "method":"POST", "name":"test2", "relative_url":"/owned_pages", "body":"page_id=" }, { "method":"POST", "name":"test3", "relative_url":"/owned_pages", "body":"page_id=" }, ]' \ "https://graph.facebook.com/v12.0" ``` Where: * `` is an access token with the `business_management` permission. * `` is the ID of the Business Manager to which the pages should be claimed. * `` are the Page IDs to be claimed. ## Errors Its possible that one of your requested operations may throw an error. This could be because, for example, you don't have permission to perform the requested operation. The response is similiar to the standard Graph API, but encapsulated in the batch response syntax: ``` [ { "code": 403, "headers": [ {"name":"WWW-Authenticate", "value":"OAuth…"}, {"name":"Content-Type", "value":"text/javascript; charset=UTF-8"} ], "body": "{\"error\":{\"type\":\"OAuthException\", … }​}" } ] ``` Other requests within the batch should still complete successfully and will be returned, as normal, with a `200` status code. ## Timeouts Large or complex batches may timeout if it takes too long to complete all the requests within the batch. In such a circumstance, the result is a partially-completed batch. In a partially-completed batch, requests that are completed successful will return the normal output with the `200` status code. Responses for requests that are not successful will be `null`. You can retry any unsuccessful request. ## Batch calls with JSONP The Batch API supports JSONP, just like the rest of the Graph API - the JSONP callback function is specified using the `callback` query string or form post parameter. ## Using Multiple Access Tokens Individual requests of a single batch request can specify its own access tokens as a query string or form post parameter. In that case the top level access token is considered a fallback token and is used if an individual request has not explicitly specified an access token. This may be useful when you want to query the API using several different User or Page access tokens, or if some of your calls need to be made using an app access token. You must include an access token as a top level parameter, even when all individual requests contain their own tokens. ## Upload Binary Data You can upload multiple binary items as part of a batch call. In order to do this, you need to add all the binary items as multipart/mime attachments to your request, and need each operation to reference its binary items using the `attached_files` property in the operation. The `attached_files` property can take a comma separated list of attachment names in its value. The following example shows how to upload 2 photos in a single batch call: ``` curl -F 'access_token=…' \ -F 'batch=[{"method":"POST","relative_url":"me/photos","body":"message=My cat photo","attached_files":"file1"},{"method":"POST","relative_url":"me/photos","body":"message=My dog photo","attached_files":"file2"},]' \ -F 'file1=@cat.gif' \ -F 'file2=@dog.jpg' \ https://graph.facebook.com ``` --> --- # Changelog Source: https://developers.facebook.com/docs/graph-api/changelog Mirror: https://nermalcat69.github.io/meta-developer-docs/docs/graph-api/changelog.html # Changelog | | | | --- | --- | | The latest Graph API version is: | `v25.0` | The Graph API and Marketing API changelogs document [versioned](https://developers.facebook.com/docs/graph-api/changelog#versioned) and [out-of-cycle](https://developers.facebook.com/docs/graph-api/changelog#outofcycle) changes, respective to the API. ### Related Changelogs * [Instagram Platform Changelog](https://developers.facebook.com/docs/instagram-platform/changelog) * [Marketing API Changelog](https://developers.facebook.com/docs/marketing-api/marketing-api-changelog) * [Messenger Platform Changelog](https://developers.facebook.com/docs/messenger-platform/changelog/) (includes Instagram Messaging) * [WhatsApp Business Platform Changelog](https://developers.facebook.com/docs/whatsapp/business-platform/changelog) ### Versioned Changes Versioned changes are changes introduced with the release of a new API [version](https://developers.facebook.com/docs/apps/versions). Versioned changes typically apply to the newest version immediately and often will apply to other versions at a future date. The changelog accompanying each release indicates which changes apply to the current release and which changes apply to other versions. Refer to our [Upgrade Guide](https://developers.facebook.com/docs/apps/upgrading) to learn how to upgrade to a new API version. ### Out-Of-Cycle Changes Out-of-cycle changes are changes introduced outside of our normal, versioned release schedule and typically do not apply to a specific version. Instead, out-of-cycle changes usually apply to all API versions immediately. Because of this, out-of-cycle changes are introduced infrequently. ## Available Graph API Versions | Version | Date Introduced | Available Until | | --- | --- | --- | | [v25.0](https://developers.facebook.com/docs/graph-api/changelog/version25.0) | February 18, 2026 | TBD | | [v24.0](https://developers.facebook.com/docs/graph-api/changelog/version24.0) | October 8, 2025 | TBD | | [v23.0](https://developers.facebook.com/docs/graph-api/changelog/version23.0) | May 29, 2025 | TBD | | [v22.0](https://developers.facebook.com/docs/graph-api/changelog/version22.0) | January 21, 2025 | TBD | | [v21.0](https://developers.facebook.com/docs/graph-api/changelog/version21.0) | October 2, 2024 | TBD | | [v20.0](https://developers.facebook.com/docs/graph-api/changelog/version20.0#graph-api) | May 21, 2024 | September 24, 2026 | | [v19.0](https://developers.facebook.com/docs/graph-api/changelog/version19.0#graph-api) | January 23, 2024 | May 21, 2026 | | [v18.0](https://developers.facebook.com/docs/graph-api/changelog/version18.0#graph-api) | September 12, 2023 | January 26, 2026 | | [v17.0](https://developers.facebook.com/docs/graph-api/changelog/version17.0#graph-api) | May 23, 2023 | September 12, 2025 | | [v16.0](https://developers.facebook.com/docs/graph-api/changelog/version16.0#graph-api) | February 2, 2023 | May 14, 2025 | | [v15.0](https://developers.facebook.com/docs/graph-api/changelog/version15.0#graph-api) | September 15, 2022 | November 20, 2024 | | [v14.0](https://developers.facebook.com/docs/graph-api/changelog/version14.0#graph-api) | May 25, 2022 | September 17, 2024 | | [v13.0](https://developers.facebook.com/docs/graph-api/changelog/version13.0#graph-api) | February 8, 2022 | May 28, 2024 | ## Available Marketing API Versions Marketing API [version auto-upgrade](https://developers.facebook.com/docs/marketing-api/versions#version-auto-upgrade) will release on May 14, 2024. | Version | Date Introduced | Available Until | | --- | --- | --- | | [v25.0](https://developers.facebook.com/docs/marketing-api/marketing-api-changelog/version25.0) | February 18, 2026 | TBD | | [v24.0](https://developers.facebook.com/docs/marketing-api/marketing-api-changelog/version24.0) | October 8, 2025 | October 6, 2026 | | [v23.0](https://developers.facebook.com/docs/marketing-api/marketing-api-changelog/version23.0) | May 29, 2025 | June 9, 2026 | ## Out-Of-Cycle Changes * [2023 out-of-cycle changes](https://developers.facebook.com/docs/graph-api/changelog/non-versioned-changes/nvc-2023) --- # Debug Requests Source: https://developers.facebook.com/docs/graph-api/guides/debugging Mirror: https://nermalcat69.github.io/meta-developer-docs/docs/graph-api/guides/debugging.html # Debug Requests ## Graph API Debug Mode When Debug Mode is enabled, Graph API response may contain additional fields that explain potential issues with the request. To enable debug mode, use the `debug` query string parameter. For example: cURLAndroid SDKObjective-CJava SDKPHP SDK ``` curl -i -X GET \ "https://graph.facebook.com/{user-id} ?fields=friends &debug=all &access_token={your-access-token}" ``` ``` GraphRequest request = GraphRequest.newMeRequest( accessToken, new GraphRequest.GraphJSONObjectCallback() { @Override public void onCompleted(JSONObject object, GraphResponse response) { // Insert your code here } }); Bundle parameters = new Bundle(); parameters.putString("fields", "friends"); parameters.putString("debug", "all"); request.setParameters(parameters); request.executeAsync(); ``` ``` FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc] initWithGraphPath:@"/{user-id}" parameters:@{ @"fields": @"friends",@"debug": @"all",} HTTPMethod:@"GET"]; [request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) { // Insert your code here }]; ``` ``` FB.api( '/{user-id}', 'GET', {"fields":"friends","debug":"all"}, function(response) { // Insert your code here } ); ``` ``` try { // Returns a `FacebookFacebookResponse` object $response = $fb->get( '/{user-id}', '{access-token}' ); } catch(FacebookExceptionsFacebookResponseException $e) { echo 'Graph returned an error: ' . $e->getMessage(); exit; } catch(FacebookExceptionsFacebookSDKException $e) { echo 'Facebook SDK returned an error: ' . $e->getMessage(); exit; } $graphNode = $response->getGraphNode(); ``` If `user_friends` permission was not granted, this produces the following response: ``` { "data": [ ], "__debug__": { "messages": [ { "message": "Field friends is only accessible on User object, if user_friends permission is granted by the user", "type": "warning" }, { "link": "https://developers.facebook.com/docs/apps/changelog#v2_0", "message": "Only friends who have installed the app are returned in versions greater or equal to v2.0.", "type": "info" } ] } } ``` The `debug` parameter value can be set to "all" or to a minimal requested severity level that corresponds to `type` of the message: | Debug Param Value | What Will Be Returned | | --- | --- | | all | All available debug messages. | | info | Debug messages with type *info* and *warning*. | | warning | Only debug messages with type *warning*. | Debug information, when available, is returned as a JSON object under the `__debug__` key in the `messages` array. Every element of this array is a JSON object that contains the following fields: | Field | Datatype | Description | | --- | --- | --- | | message | String | The message. | | type | String | The message severity. | | link | String | [Optional] A URL pointing to related information. | You can also use Debug Mode with [Graph API Explorer](https://developers.facebook.com/tools/explorer). ### Determining Version used by API Requests When you're building an app and making Graph API requests, you might find it useful to determine what API version you're getting a response from. For example, if you're making calls without a version specified, the API version that responds may not be known to you. The Graph API supplies a request header with any response called `facebook-api-version` that indicates the exact version of the API that generated the response. For example, a Graph API call that generates a request with v2.0 produces the following HTTP header: ``` facebook-api-version:v2.0 ``` This `facebook-api-version` header allows you to determine whether API calls are being returned from the version that you expect. ### Debug Info for Reporting Bugs When [reporting a bug](https://developers.facebook.com/bugs/) in the Graph API, we include some additional request headers to send with your bug report to help us pinpoint and reproduce your issue. These request headers are `X-FB-Debug`, `x-fb-rev`, and `X-FB-Trace-ID`. --- # Field Expansion Source: https://developers.facebook.com/docs/graph-api/guides/field-expansion Mirror: https://nermalcat69.github.io/meta-developer-docs/docs/graph-api/guides/field-expansion.html # Field Expansion If you test the `GET /me/feed` query in the Graph API Explorer, you will noticed that the request returned many objects and paginated the results. This is common for most edges. #### Example Response ``` { "data": [ { "created_time": "2021-04-30T01:37:07+0000", "message": "I'll never forget it has a head.", "id": "10211998223264288_10222340566616408" }, ... { "created_time": "2021-04-25T22:29:26+0000", "message": "Things you hear at my house: \"I accidentally made a cake.\"", "id": "10211998223264288_10222314489524497" } ], "paging": { "previous": "https://graph.facebook.com///feed?access_token=&pretty=0&__previous=1&since=1627322627&until&__paging_token=enc_AdB2fX...", "next": "https://graph.facebook.com///feed?access_token=&pretty=0&until=1619389766&since&__paging_token=enc_AdAamX...&__previous" } } ``` Field expansion allows you not only to limit the number of objects returned but also perform nested requests. ## Limiting Results Limiting allows you to control the number of objects returned in each set of paginated results. To limit results, add a `.limit()` argument to any field or edge. For example, performing a GET request on your `/feed` edge may return hundreds of Posts. You can limit the number of Posts returned for each page of results by doing this: ``` curl -i -X GET "https://graph.facebook.com//?fields=feed.limit(3)&access_token=" ``` This returns all of the Posts on your User node, but limits the number of objects in each page of results to three. Notice that instead of specifying the Feed edge in the path URL (`/user/feed`), you specify it in the `fields` parameter (`?fields=feed`), which allows you to append the `.limit(3)` argument. Here are the query results: ``` { "feed": { "data": [ { "created_time": "2021-12-12T01:24:21+0000", "message": "This picture of my grandson with Santa", "id": "" }, { "created_time": "2021-12-11T23:40:17+0000", "message": ":)", "id": "" }, { "created_time": "2021-12-11T23:31:38+0000", "message": "Thought you might enjoy this.", "id": "" } ], "paging": { "previous": "https://graph.facebook.com///feed?format=json&limit=3&since=1542820440&access_token=&__paging_token=enc_AdC...&__previous=1", "next": "https://graph.facebook.com///feed?format=json&limit=3&access_token=&until=1542583212&__paging_token=enc_AdD..." } }, "id": "" } ``` As you can see, only three objects appear in this page of paginated results. However, the response included a `next` field and URL which you can use to fetch the next page. ## Nested Requests The field expansion feature of the Graph API allows you to effectively nest multiple graph queries into a single call. For example, in a single call, you can ask for the first N photos of the first K albums. The response maintains the data hierarchy so developers do not have to weave the data together on the client. This is different from the [batch requests](https://developers.facebook.com/docs/graph-api/making-multiple-requests/) feature which allows you to make multiple, potentially unrelated, Graph API calls in a single request. Here is the general format that field expansion takes: ``` GET graph.facebook.com/?fields=<{} ``` `` in this case would be one or more (comma-separated) fields or edges from the parent node. `` would be one or more (comma-separated) fields or edges from the first level node. There is no limitation to the amount of nesting of levels that can occur here. You can also use a `.limit(n)` argument on each field or edge to restrict how many objects you want to get. This is easier to understand by seeing it in action, so here's an example query that will retrieve up to five posts your published, with the text from each individual post. ``` GET graph.facebook.com/me?fields=posts.limit(5){message} ``` We can then extend this a bit more and for each post object, we get the text and privacy setting of each post. By default the `privacy` field returns an object that contains information about five key:value pairs, `allow`, `deny`, `description`, `friends`, and `value`. In this query we only want one returned, the `value` key:value pair. ``` GET graph.facebook.com/me?fields=posts.limit(5){message,privacy{value}​} ``` Now we can extend it again by retrieving the name of each photo, the picture URL, and the people tagged: ``` GET graph.facebook.com /me?fields=albums.limit(5){name, photos.limit(2){name, picture, tags.limit(2)}​},posts.limit(5) ``` Let's look at an example using cursor-based pagination: ``` GET graph.facebook.com /me?fields=albums.limit(5){name,photos.limit(2).after(MTAyMTE1OTQwNDc2MDAxNDkZD){name,picture,tags.limit(2)}​},posts.limit(5) ``` You can see how field expansion can work across nodes, edges, and fields to return really complex data in a single request. #### Limitations * Certain resources, including most of Marketing API, are unable to utilize field expansion on some or all connections. ## Field Aliases Many nodes and edges allow you to provide aliases for fields by using the `as` parameter. This will return data using fields that you already have in your application logic. For example, you can retrieve an image in two sizes and alias the returned object fields as `picture_small` and `picture_larger`: ``` /me?fields=id,name,picture.width(100).height(100).as(picture_small),picture.width(720).height(720).as(picture_large) ``` On success, Graph API returns this result: ``` { "id": "993363923726", "name": "Benjamin Golub", "picture_small": { "data": { "height": 100, "is_silhouette": false, "url": "https://fbcdn-profile-a.akamaihd.net/hprofile-ak-xft1/v/t1.0-1/p100x100/11700890_10100330450676146_2622493406845121288_n.jpg?oh=82b9abe469c78486645783c9e70e8797&oe=561D10AE&__gda__=1444247939_661c0f48363f1d1a7d42b6f836687a04", "width": 100 } }, "picture_large": { "data": { "height": 720, "is_silhouette": false, "url": "https://fbcdn-profile-a.akamaihd.net/hprofile-ak-xft1/v/t1.0-1/11700890_10100330450676146_2622493406845121288_n.jpg?oh=dd86551faa2de0cd6b359feb5665b0a5&oe=561E0B46&__gda__=1443979219_f1abbbdfb0fb7dac361d7ae02b460638", "width": 720 } } } ``` Please note that not all nodes and edges support field aliasing. Endpoints that do not support aliasing will return an error. For example, the `User` node does not support aliasing, so if you tried to alias the `name` field as `my_name` you would receive an error like this: ``` { "error": { "message": "(#100) Unknown fields: my_name.", "type": "OAuthException", "code": 100 } } ``` ## Next Steps * Learn about [Paginated Results](https://developers.facebook.com/docs/graph-api/results). --- # Get Started Source: https://developers.facebook.com/docs/graph-api/get-started Mirror: https://nermalcat69.github.io/meta-developer-docs/docs/graph-api/get-started.html # Get Started This guide explains how to get started with receiving data from the Facebook Social Graph. ## Before You Start You will need: * [Register as a Meta Developer](https://developers.facebook.com/docs/development/register) * A [Meta App](https://developers.facebook.com/docs/development/create-an-app) – This app will be for testing so there is no need to involve your app code when creating this Meta App. * The [Graph API Explorer tool](https://developers.facebook.com/tools/explorer) open in a separate browser window * A brief understanding of the structure of the Meta's social graph from our [Graph API Overview](https://developers.facebook.com/docs/graph-api/overview#nodes) guide ## Your First Request ### Step 1: Open the Graph API Explorer tool [Open the Graph API Explorer in a new browser window.](https://developers.facebook.com/tools/explorer) This allows you to execute the examples as you read this tutorial. The explorer loads with a default query with the `GET` method, the lastest version of the Graph API, the `/me` node and the `id` and `name` fields in the [Query String Field](https://developers.facebook.com/docs/graph-api/guides/explorer#query-string-field), and your Facebook App. ![](https://scontent.fdel1-2.fna.fbcdn.net/v/t39.2365-6/232068365_563091814813799_6070357364579520404_n.png?_nc_cat=100&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=e280be&_nc_ohc=moTpOtRzxaYQ7kNvwG_elbW&_nc_oc=Adoonxszl1ZfGW7c3qJx-8JcTkerx8bJbutRw_VhVzGfjEnbS9k9_6bLMSzvV88ZnKEkjUVl111Y54g9Ir2EPm0G&_nc_zt=14&_nc_ht=scontent.fdel1-2.fna&_nc_gid=uTUq3huEuuLS0jLLeAKRJg&_nc_ss=7b2a8&oh=00_AQB9-2vZYV8AuWYCtXlNbfgfsl6HECz-3XDUj-_tfRAS3Q&oe=6A606BE4) ### Step 2. Generate an Access Token Click the **Generate Access Token** button. A **Log in With Facebook** window will pop up. This popup is your app asking for your permission to get your name and profile picture from Facebook. | | | | --- | --- | | This flow is our [Facebook Login](https://developers.facebook.com/docs/facebook-login) product that allows a person to log into an app using their Facebook credentials. Facebook Login allows an app to ask a person to access the person's Facebook data, and for the person to accept or decline access. Your name and profile picture are public, to allow people to find you on Facebook, so no additional requirements are needed to run this request. Click **Continue as...** A User Access Token is created. This token contains information such as the app making the request, the person using the app to make a request, if the access token is still valid (it expires in about an hour), the expiration time, and the scope of data the app can request. In this request the scope is `public_profile` which includes your name and profile picture. | | | | | | --- | --- | | | Click the information circle icon next to the acces token to view the token's information. | ### Step 3. Submit the Request Click the **Submit** button in the upper right corner. #### What You Should See In the [Response Window](https://developers.facebook.com/docs/graph-api/guides/explorer#response-window), you will see a JSON response with your Facebook User ID and your name. ![](https://scontent.fdel1-7.fna.fbcdn.net/v/t39.2365-6/232902382_904467853476103_7217229934737479641_n.png?_nc_cat=105&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=e280be&_nc_ohc=5zRqxgIhzEoQ7kNvwH8g8fo&_nc_oc=AdqDHVysAMcBSeyn0XHdo8EZvudW7WBysldPY-QFB11Maw2dVCF1W-CxYZCtfeo46yR-XIInA5I36-_GDY8K_tml&_nc_zt=14&_nc_ht=scontent.fdel1-7.fna&_nc_gid=uTUq3huEuuLS0jLLeAKRJg&_nc_ss=7b2a8&oh=00_AQAyFii0b43Z8VK2vBD74xOqnyv9lENnjK7L6IAwO03rMA&oe=6A604863) If you remove `?fields=id,name` from the query string field and click **Submit**, you will see the same result since `name` and `id` are the User node fields returned by default. ## Your Second Request ### Step 1. Let's Add a Field Let's make the First Request a little more complex by adding another field, `email`. There are two ways to add fields: * Click the search dropdown menu in the [Node Field Viewer](https://developers.facebook.com/docs/graph-api/guides/explorer#node-field-viewer) to the left of the response window * Start typing in the query string field. Let's add the `email` field and click **Submit**. #### What You Should See While the call did not fail, only the `name` and `id` fields were returned along with a debug message. Click the (Show) link to debug the request. ![](https://scontent.fdel1-3.fna.fbcdn.net/v/t39.2365-6/233410295_959323958245691_7180707304587023135_n.png?_nc_cat=104&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=e280be&_nc_ohc=CUWgRQHR0YIQ7kNvwG8QeYQ&_nc_oc=Adoltxpo6rT85DD6aqT1VdGwfzR0AkyUuBTtWZyTiJDZFi-E6MXXI_PUGOr6YigQ0fe4Ib_qywbWYkh24ylRWw06&_nc_zt=14&_nc_ht=scontent.fdel1-3.fna&_nc_gid=uTUq3huEuuLS0jLLeAKRJg&_nc_ss=7b2a8&oh=00_AQDIvN8IqNwyF2bGOgxq7NTILhuMrMfmrgojPB5Egc4LDg&oe=6A604656) Almost all nodes and fields need a specific permission to access them. The debug message is telling you that you need to give your app permission to access the email address that you have associated with your Facebook account. ### Step 2. Add a Permission | | | | --- | --- | | In the right side panel, under **Permissions**, click the **Add a Permission** dropdown menu. Click **User Data Permissions** and select **email**. Generate A New User Access Token Because you are changing the scope of the access token, you need to create a new one. Click **Generate Access Token**. Just like your first request, you must give your app permission to access your email in the Facebook Login dialog. Once the new token has been created, click **Submit**. Now all fields in your request will be returned. | | Try getting your Facebook posts. [See the steps.](https://developers.facebook.com/docs/graph-api/get-started#) #### Links in the Response Notice that `id` values returned in the response window are links. These links can represent nodes, such as User, Page, or Post. If you click on a link, the ID will replace the contents of the query string field. Now you can run requests on that node. Because this node is connected to the parent node, a Post of a User, you may not need to add permissions. You can click on a Post ID now since we will be using it in the next example. Notice: Some IDs are a combination of the parent ID and a new ID string. For example, a User's Post will have a Post ID that looks something like this: `1028223264288_102224043055529` where `1028223264288` is the User ID. ## Let's Look at an Edge The User node does not have many edges that can return data. Access to User objects can only be given by the User who owns the object. In most cases, a User owns an object if they created it. For example, if you publish a post you can see information about the post such as when it was created, text, photos, and links shared in the post, and the number of reactions the post received. If you comment on your post, you will be able to get that comment, but if another person publishes a comment on your post, you will not be able to see the comment or who published it. Try getting the number of reactions for one of your posts. You will want to take a look at the [Object Reactions reference.](https://developers.facebook.com/docs/graph-api/reference/v13.0/object/reactions) [See the steps.](https://developers.facebook.com/docs/graph-api/get-started#) ## Get the Code for your Request The explorer tool lets you test requests and once you have a successful response, you can get the code to insert into your app code. At the bottom of the response window, click **Get Code**. The explorer offers Android, iOS, JavaScript, PHP, and cURL code. The code is pre-selected so you can just copy and paste. ![](https://scontent.fdel1-2.fna.fbcdn.net/v/t39.2365-6/231948896_1065545040645743_5920314088559660186_n.png?_nc_cat=101&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=e280be&_nc_ohc=ve-H6BRcqdoQ7kNvwF6IAl4&_nc_oc=Adr4vVeUWw1v4Z-7z_sy9yced_kgIIzeUBLU1gFpZrf8PgurVBVlsWGE7e6noipgmg1Ciy78VdZoBIabtiRbUW3_&_nc_zt=14&_nc_ht=scontent.fdel1-2.fna&_nc_gid=uTUq3huEuuLS0jLLeAKRJg&_nc_ss=7b2a8&oh=00_AQAPbL2xDK6gBdXwZIrvQnlRheMDSDjRTYdFQsnvaeRF_Q&oe=6A606C6C) We recommend that you implement the Facebook SDK for your app. This SDK will include Facebook Login which allows your app to ask for permissions and get access tokens. ## Learn More You can use the Graph API Explorer to test any request for Users, Pages, Groups, and more. Visit the [reference](https://developers.facebook.com/docs/graph-api/reference) for each node or edge to determine the permission and access token type required. | | | | --- | --- | | * [Access Token](https://developers.facebook.com/docs/facebook-login/access-tokens) * [Facebook Login](https://developers.facebook.com/docs/facebook-login) * [Facebook SDKs](https://developers.facebook.com/docs#apis-and-sdks) | * [Graph API References](https://developers.facebook.com/docs/graph-api/reference) * [Graph API Explorer Guide](https://developers.facebook.com/docs/graph-api/guides/explorer) * [Login Security](https://developers.facebook.com/docs/facebook-login/security) * [Permissions Reference](https://developers.facebook.com/docs/permissions/reference) | --- # Graph API Source: https://developers.facebook.com/docs/graph-api Mirror: https://nermalcat69.github.io/meta-developer-docs/docs/graph-api.html If you are a Facebook user and are having trouble signing into your account, visit our [Help Center](https://www.facebook.com/help/1573156092981768/). # Graph API | | | | --- | --- | | **The latest version is**: | `v25.0` | The Graph API is the primary way for apps to read and write to the Facebook social graph. All of our SDKs and products interact with the Graph API in some way, and our other APIs are extensions of the Graph API, so understanding how the Graph API works is crucial. If you are unfamiliar with the Graph API, we recommend that you start with these documents: 1. [Overview](https://developers.facebook.com/docs/graph-api/overview) – Learn how the Graph API is structured, and how it works. 2. [Get Started](https://developers.facebook.com/docs/graph-api/get-started) – Explore the Graph API endpoints using the Graph API Explorer tool and run your first request. 3. [Batch requests](https://developers.facebook.com/docs/graph-api/batch-requests) – Learn how to send multiple API requests in one call. 4. [Debug requests](https://developers.facebook.com/docs/graph-api/guides/debugging) – Learn how to debug API requests. 5. [Handle errors](https://developers.facebook.com/docs/graph-api/guides/error-handling) – Learn how to handle common errors encountered when using the Graph API. 6. [Field expansion](https://developers.facebook.com/docs/graph-api/guides/field-expansion) – Learn how to limit the number of objects returned in a request and perform nested requests. 7. [Secure requests](https://developers.facebook.com/docs/graph-api/guides/secure-requests) – Learn how to make secure requests to the Graph API. 8. [Resumable Uploads API](https://developers.facebook.com/docs/graph-api/guides/upload) – Learn how to upload files to the Graph API. #### [Reference](https://developers.facebook.com/docs/graph-api/reference) Learn how to read our reference documents so you can easily find what you're looking for. ## Where to Start We strongly recommend you start with the [**Graph API Overview**](https://developers.facebook.com/docs/graph-api/overview) to learn the structure of the Facebook Social Graph. --- # Graph API Explorer Guide Source: https://developers.facebook.com/docs/graph-api/guides/explorer Mirror: https://nermalcat69.github.io/meta-developer-docs/docs/graph-api/guides/explorer.html # Graph API Explorer Guide | | | | --- | --- | | The Graph API Explorer tool allows you to construct and perform Graph API queries and see their responses for any apps on which you have an admin, developer, or tester role. | [Open the Graph API Explorer tool](https://developers.facebook.com/tools/explorer) | ## Common Uses * Quickly generate access tokens * Get code samples for your queries * Generate debug information to include in support requests * Test API queries with your production app's settings including permissions, features, and settings for your use cases * Test API queries with your test or development app using permission and features on test users or test data ## Requirements * A [Facebook Developer Account](https://developers.facebook.com/apps) * An app for which you have a role, such as an [admin, developer, or tester role](https://developers.facebook.com/docs/apps#roles) ## Components ### Access Token When you get an access token, it is displayed in the upper right of the tool. This is the token that is included in your Graph API query. You can copy this token and use it in your app to test your code. Click the information icon to see information about the current token, including the app that it's tied to, and any permissions that have been granted by the User who is using the app (which is you). You can generate a new access token if the token has expired or if you add new permissions. ### Meta App The Meta App dropdown menu in the upper right displays all the apps on which you have an admin, developer, or tester role. Use the dropdown to select the app settings that you wish to test. ### User or Page The User or Page dropdown menu allows you to get and exchange App, User, and Page access tokens for the currently selected app. You can also use it to uninstall your app from your User node, which destroys the current access token. ### Permissions The Permission dropdown menu allows you to select permissions, such as `email`, `pages_show_list`, and `ads_management` permissions. This allows the current app user (which is you) to grant the app specific permissions. Only grant permissions that your app actually needs. If your app is in development, you can grant your app any permission and your queries respect them for data owned by people with a role on your app. If your app is live, however, granting a permission that your app has not been approved for by the [App Review](https://developers.facebook.com/docs/apps/review) process causes your query to fail whenever you submit it. ### Query string Field When you first enter the tool a default query appears. You can edit the query by typing in a new one, or by searching for and selecting fields in the field viewer after executing the query. You can also use the dropdown menus to switch between operation methods, and target different versions of the Graph API. If you click the star icon at the end of the query field, the query is saved as a favorite. You can view your favorite queries by clicking the book icon. ### Node Field Viewer When you submit a `GET` query on a node, the field viewer located in the left side of the window displays the name of the node and the fields returned by the Graph API. You can modify your query by searching for and selecting new fields, clicking the plus icon, and choosing from available fields, or unchecking unnecessary fields. These actions dynamically update your query in the query string field. ### Response Window The response, located below the query string, shows the results returned from your last submitted query. ### Get Code If you are happy with your query, click the Get Code button located in the botton center below the response, to generate sample code based on the query. Typically you won't be able to copy and paste the sample code directly in your code base, but it gives you a useful starting point. ### Copy Debug Information If your query keeps failing and you can't figure out why, and you decide to contact Developer Support, click this button, located at the bottom center, to copy your query and response details to your clipboard. You can submit this information with your support request to help us figure out what's going on. ### Save Session Click the Save Session button, located at the bottom center, to save the state of your query, with the access token removed. Include the link to this session if you decide to contact Developer Support. ## Sample Query Try executing the default query that appears when you first load the Graph API Explorer. If you haven't already, [open the Graph API Explorer in a new window](https://developers.facebook.com/tools/explorer), select the app you want to test from the application dropdown menu, and get a User access token. The default query appears in the query string field: ``` GET https://developers.facebook.com/v25.0/me?fields=id,name ``` The default query is requesting the `id` and `name` fields on the `/me` node, which is a special node that maps to either the `/User` or `/Page` node identified by the token. Since your are using a User access token, this maps to your User node. The `id` and `name` fields are publicly available and can be returned if the User has granted your app the `default` or `public_profile` permissions. These permissions are pre-approved for all apps (you can confirm this by clicking the information icon in the **Access Token Field**), so you don't have to grant your app any additional permissions for the query to work. Click **Get Access Token** and confirm that you want to grant your app access to your publicly available User information. Submit your query, and you should see your app-scoped User ID and name appear in the response window. --- # Graph API overview Source: https://developers.facebook.com/docs/graph-api/overview Mirror: https://nermalcat69.github.io/meta-developer-docs/docs/graph-api/overview.html # Graph API overview The Graph API is the primary way to get data into and out of the Facebook platform. It's an HTTP-based API that apps can use to programmatically query data, post new stories, manage ads, upload photos, and perform a wide variety of other tasks. The Graph API is named after the idea of a "social graph" — a representation of the information on Facebook. It's composed of nodes, edges, and fields. Typically you use nodes to get data about a specific object, use edges to get collections of objects on a single object, and use fields to get data about a single object or each object in a collection. Throughout our documentation, we may refer to both a node and edge as an "endpoint". For example, "send a `GET` request to the User endpoint". ## HTTP All data transfers conform to HTTP/1.1, and all endpoints require HTTPS. Because the Graph API is HTTP-based, it works with any language that has an HTTP library, such as cURL and urllib. This means you can use the Graph API directly in your browser. For example, requesting this URL in your browser... ... is equivalent to performing this cURL request: ``` curl -i -X GET "https://graph.facebook.com/facebook/picture?redirect=false" ``` We have also enabled the `includeSubdomains` HSTS directive on `facebook.com`, but this should not adversely affect your Graph API calls. ## Host URL All requests are passed to the `graph.facebook.com` host URL. ## Access Tokens Access tokens allow your app to access the Graph API. Almost all Graph API endpoints require an access token of some kind, so each time you access an endpoint, your request may require one. They typically perform two functions: * They allow your app to access a User's information without requiring the User's password. For example, your app needs a User's email to perform a function. If the User agrees to allow your app to retrieve their email address from Facebook, the User will not need to enter their Facebook password for your app to get their email address. * They allow us to identify your app, the User who is using your app, and the type of data the User has permitted your app to access. Visit our [access token documentation](https://developers.facebook.com/docs/facebook-login/access-tokens) to learn more. ## Nodes A node is an individual object with a unique ID. For example, there are many User node objects, each with a unique ID representing a person on Facebook. Pages, Posts, Photos, and Comments are just some of the nodes of the Facebook Social Graph. The following cURL example represents a call to the User node. ``` curl -i -X GET \ "https://graph.facebook.com/USER-ID?access_token=ACCESS-TOKEN" ``` This request would return the following data by default, formatted using JSON: ``` { "name": "Your Name", "id": "YOUR-USER-ID" } ``` ### Node metadata The `metadata` paramater is deprecated in Graph API v25.0 and no longer returns metadata about the targeted node. Use the [Graph API Explorer](https://developers.facebook.com/tools/explorer/) or API references instead. The parameter will be deprecated for all versions May 19, 2026. You can get a list of all fields, including the field name, description, and data type, of a node object, such as a User, Page, or Photo. Send a `GET` request to an object ID and include the `metadata=1` parameter: ``` curl -i -X GET \ "https://graph.facebook.com/USER-ID? metadata=1&access_token=ACCESS-TOKEN" ``` The resulting JSON response will include the `metadata` property that lists all the supported fields for the given node: ``` { "name": "Jane Smith", "metadata": { "fields": [ { "name": "id", "description": "The app user's App-Scoped User ID. This ID is unique to the app and cannot be used by other apps.", "type": "numeric string" }, { "name": "age_range", "description": "The age segment for this person expressed as a minimum and maximum age. For example, more than 18, less than 21.", "type": "agerange" }, { "name": "birthday", "description": "The person's birthday. This is a fixed format string, like `MM/DD/YYYY`. However, people can control who can see the year they were born separately from the month and day so this string can be only the year (YYYY) or the month + day (MM/DD)", "type": "string" }, ... ``` ## /me The `/me` node is a special endpoint that translates to the object ID of the person or Page whose access token is currently being used to make the API calls. If you had a User access token, you could retrieve a User's name and ID by using: ``` curl -i -X GET \ "https://graph.facebook.com/me?access_token=ACCESS-TOKEN" ``` ## Edges An edge is a connection between two nodes. For example, a User node can have photos connected to it, and a Photo node can have comments connected to it. The following cURL example will return a list of photos a person has published to Facebook. ``` curl -i -X GET \ "https://graph.facebook.com/USER-ID/photos?access_token=ACCESS-TOKEN" ``` Each ID returned represents a Photo node and when it was uploaded to Facebook. ``` { "data": [ { "created_time": "2017-06-06T18:04:10+0000", "id": "1353272134728652" }, { "created_time": "2017-06-06T18:01:13+0000", "id": "1353269908062208" } ], } ``` ## Fields Fields are node properties. When you query a node, or an edge, it returns a set of fields by default, as the examples above show. However, you can specify which fields you want returned by using the `fields` parameter and listing each field. This overrides the defaults and returns only the fields you specify, and the ID of the object, which is always returned. The following cURL request includes the `fields` parameter and the User's name, email, and profile picture. ``` curl -i -X GET \ "https://graph.facebook.com/USER-ID?fields=id,name,email,picture&access_token=ACCESS-TOKEN" ``` #### Data returned ``` { "id": "USER-ID", "name": "EXAMPLE NAME", "email": "EXAMPLE@EMAIL.COM", "picture": { "data": { "height": 50, "is_silhouette": false, "url": "URL-FOR-USER-PROFILE-PICTURE", "width": 50 } } } ``` ### Complex parameters Most parameter types are straightforward primitives such as `bool`, `string` and `int`, but there are also `list` and `object` types that can be specified in the request. The `list` type is specified in JSON syntax, for example: `["firstitem", "seconditem", "thirditem"]` The `object` type is also specified in JSON syntax, for example: `{"firstkey": "firstvalue", "secondKey": 123}` ## Publishing, Updating, and Deleting Visit our [Facebook Sharing guide](https://developers.facebook.com/docs/sharing) to learn how to publish to a User's Facebook or our [Pages API documentation](https://developers.facebook.com/docs/pages) to publish to a Page's Facebook feed. Some nodes allow you to update fields with `POST` operations. For example, you could update your `email` field like this: ``` curl -i -X POST \ "https://graph.facebook.com/USER-ID?email=YOURNEW@EMAILADDRESS.COM&access_token=ACCESS-TOKEN" ``` ### Read-After-Write For create and update endpoints, the Graph API can immediately read a successfully published or updated object and return any fields supported by the corresponding read endpoint. By default, an ID of the object created or updated will be returned. To include more information in the response, include the `fields` parameter in your request and list the fields you want returned. For example, to publish the message "Hello" to a Page's feed, you could make the following request: ``` curl -i - X POST "https://graph.facebook.com/PAGE-ID/feed?message=Hello& fields=created_time,from,id,message&access_token=ACCESS-TOKEN" ``` *The above code example is formatted for readability.* This would return the specified fields as a JSON-formatted response, like this: ``` { "created_time": "2017-04-06T22:04:21+0000", "from": { "name": "My Facebook Page", "id": "PAGE-ID" }, "id": "POST_ID", "message": "Hello", } ``` Refer to each endpoint's [reference documentation](https://developers.facebook.com/docs/graph-api/reference) to see if it supports **read-after-write** and what fields are available. #### Errors If the read fails for any reason (for example, requesting a non-existent field), the Graph API will respond with a standard error response. Visit our [Handling Errors guide](https://developers.facebook.com/docs/graph-api/guides/error-handling) for more information. You can usually delete a node, such as a Post or Photo node, by performing a DELETE operation on the object ID: ``` curl -i -X DELETE \ "https://graph.facebook.com/PHOTO-ID?access_token=ACCESSS-TOKEN" ``` Usually you can only delete nodes that you created, but check each node's reference guide to see requirements for delete operations. ## Webhooks You can be notified of changes to nodes or interactions with nodes by subscribing to webhooks. See [Webhooks](https://developers.facebook.com/docs/graph-api/webhooks). ## Versions The Graph API has multiple versions with quarterly releases. You can specify the version in your calls by adding "v" and the version number to the start of the request path. For example, here's a call to version 4.0: ``` curl -i -X GET \ "https://graph.facebook.com/v4.0/USER-ID/photos ?access_token=ACCESS-TOKEN" ``` If you do not include a version number we will default to the oldest available version, so it's recommended to include the version number in your requests. You can read more about versions in our [Versioning guide](https://developers.facebook.com/docs/graph-api/guides/versioning) and learn about all available versions in the [Graph API Changelog](https://developers.facebook.com/docs/graph-api/changelog). ## Facebook APIs, SDKs, and Platforms Connect interfaces and develop across platforms using Facebook's various [APIs, SDKs, and platforms](https://developers.facebook.com/docs#apis-and-sdks). ## Next Steps [**Get Started with Graph API**](https://developers.facebook.com/docs/graph-api/get-started) – Let's explore the Facebook Social Graph using the Graph Explorer tool and run a couple requests to get data. --- # Handling Errors Source: https://developers.facebook.com/docs/graph-api/guides/error-handling Mirror: https://nermalcat69.github.io/meta-developer-docs/docs/graph-api/guides/error-handling.html # Handling Errors Requests made to our APIs can result in several different error responses. The following document describes the recovery tactics and provides a list of error values with a map to the most common recovery tactic to use. ## Error Responses The following represents a common error response resulting from a failed API request: ``` { "error": { "message": "Message describing the error", "type": "OAuthException", "code": 190, "error_subcode": 460, "error_user_title": "A title", "error_user_msg": "A message", "fbtrace_id": "EJplcsCHuLu" } } ``` * `message`: A human-readable description of the error. * `code`: An error code. Common values are listed below, along with common recovery tactics. * `error_subcode`: Additional information about the error. Common values are listed below. * `error_user_msg`: The message to display to the user. The language of the message is based on the locale of the API request. * `error_user_title`: The title of the dialog, if shown. The language of the message is based on the locale of the API request. * `fbtrace_id`: Internal support identifier. When [reporting a bug](https://developers.facebook.com/bugs/) related to a Graph API call, include the `fbtrace_id` to help us find log data for debugging. However, this ID will expire shortly. To help the support team reproduce your issue, please attach a saved [graph explorer session](https://developers.facebook.com/tools/explorer/). ### Error Codes | Code or Type | Name | What To Do | | --- | --- | --- | | OAuthException | | If no subcode is present, the login status or access token has expired, been revoked, or is otherwise invalid. [Get a new access token](https://developers.facebook.com/docs/facebook-login/access-tokens#errors). If a subcode is present, see the subcode. | | 102 | API Session | If no subcode is present, the login status or access token has expired, been revoked, or is otherwise invalid. [Get a new access token](https://developers.facebook.com/docs/facebook-login/access-tokens#errors). If a subcode is present, see the subcode. | | 1 | API Unknown | Possibly a temporary issue due to downtime. Wait and retry the operation. If it occurs again, check that you are requesting an existing API. | | 2 | API Service | Temporary issue due to downtime. Wait and retry the operation. | | 3 | API Method | Capability or permissions issue. Make sure your app has the necessary capability or permissions to make this call. | | 4 | API Too Many Calls | Temporary issue due to throttling. Wait and retry the operation, or examine your API request volume. | | 17 | API User Too Many Calls | Temporary issue due to throttling. Wait and retry the operation, or examine your API request volume. | | 10 | API Permission Denied | Permission is either not granted or has been removed. [Handle the missing permissions](https://developers.facebook.com/docs/facebook-login/permissions#handling). | | 190 | Access token has expired | [Get a new access token](https://developers.facebook.com/docs/facebook-login/access-tokens#errors). | | 200-299 | API Permission (Multiple values depending on permission) | Permission is either not granted or has been removed. [Handle the missing permissions](https://developers.facebook.com/docs/facebook-login/permissions#handling). | | 341 | Application limit reached | Temporary issue due to downtime or throttling. Wait and retry the operation, or examine your API request volume. | | 368 | Temporarily blocked for policies violations | Wait and retry the operation. | | 506 | Duplicate Post | Duplicate posts cannot be published consecutively. Change the content of the post and try again. | | 1609005 | Error Posting Link | There was a problem scraping data from the provided link. Check the URL and try again. | ### Authentication Error Subcodes | Code | Name | What To Do | | --- | --- | --- | | 458 | App Not Installed | The User has not logged into your app. Reauthenticate the User. | | 459 | User Checkpointed | The User needs to log in at https://www.facebook.com or https://m.facebook.com to correct an issue. | | 460 | Password Changed | On iOS 6 and above, if the person logged in using the OS-integrated flow, direct them to Facebook OS settings on the device to update their password. Otherwise, they must log in to the app again. | | 463 | Expired | Login status or access token has expired, been revoked, or is otherwise invalid. [Handle expired access tokens](https://developers.facebook.com/docs/facebook-login/access-tokens#errors). | | 464 | Unconfirmed User | The User needs to log in at https://www.facebook.com or https://m.facebook.com to correct an issue. | | 467 | Invalid Access Token | Access token has expired, been revoked, or is otherwise invalid. [Handle expired access tokens](https://developers.facebook.com/docs/facebook-login/access-tokens#errors). | | 492 | Invalid Session | User associated with the Page access token does not have an appropriate role on the Page. | ### Rate Limiting Error Codes Visit the [Graph API Rate Limits guide](https://developers.facebook.com/docs/graph-api/overview/rate-limiting) for more information about Rate Limiting Error Codes. --- # Introduction Source: https://developers.facebook.com/docs/license Mirror: https://nermalcat69.github.io/meta-developer-docs/docs/license.html # Introduction In countries with financial services advertising regulations, Meta may require advertisers to verify their identity and financial license. Regulators will provide Meta with a dataset of financial licenses, which Meta uses to validate licenses submitted by advertisers. This document covers how regulators securely share license data with Meta and the technical specifications for integration. ## Overview The integration works as follows: 1. **Meta provides SFTP credentials** - Meta sends login details to the regulator's confirmed email address. 2. **Regulator uploads two files** - A `config.json` (metadata) and a **CSV file** (license data) are uploaded to Meta's secure SFTP server. [Instructions](https://developers.facebook.com/docs/license/upload) for uploading files. 3. **Meta ingests the data** - Files are processed periodically. 4. **Regulator regularly uploads** - Regulators are responsible for routinely uploading updated files weekly. ## What is config.json? The `config.json` file is a manifest containing metadata required for processing. It must be included with every upload. ### Fields | Field | Type | Required | Description | Allowed Values | | --- | --- | --- | --- | --- | | version | string | Yes | Schema version used for the license CSV file. | "v1" | | load\_type | string | Yes | Whether this is a **full** dataset or an **incremental** update (deltas only). | "full", "incremental" | | mode | string | Yes | * Validation: CSV file is checked for correctness and integrity, but not ingested. * Ingestion: CSV file is validated (using the same checks as validation mode), then ingested into the pipeline | "validation", "ingestion" | | support\_email\_addresses | array of string | Yes | Monitored email addresses that Meta can use for outreach around data ingestion. | | ### Example ``` 1. { 2. "version": "v1", 3. "load_type": "full", 4. "mode": "ingestion", 5. "support_email_addresses": [ 6. "support@domain.com", 7. "support2@domain.com" 8. ] 9. } ``` ## License Data (CSV) License data is provided as a CSV file. The file can have any name. There are two load types: * **Full Load** - Contains the complete set of all license data. * **Incremental Load** - Contains only the changes (deltas) since the last upload. ### General Rules * Column headers must be on the **first row**. * All column headers must be **unique**. * All **required columns** must be present. * Each row must have a unique `Credential_Id`. * Row-level errors do **not** block the entire file. Valid rows are still ingested. For example, if 50 out of 100,000 rows have errors, the remaining 99,950 rows are processed normally. ## Full Load Schema (V1) | Column | Required | Type | Description | Format / Allowed Values | Example | | --- | --- | --- | --- | --- | --- | | Credential\_Id | Yes | string | Unique identifier for the license. Displayed on published financial services ads. | Max 200 characters | 123456789 | | License\_Status | Yes | string | Status of the license. | ACTIVE, INACTIVE, LEGALLY\_EXEMPT | ACTIVE | | Licensee\_Name | Yes | string | Name under which the license is registered. | Max 200 characters | Jane Doe | | Licensee\_Type | Yes | string | Type of entity holding the license. | INDIVIDUAL, FIRM, UNKNOWN\* | INDIVIDUAL | | License\_Expiration\_Date | No | number | Expiration date of the license. | Unix timestamp | 946684800 | | Address\_Line\_1 | No | string | Primary street address. | Max 200 characters | 123 Main St | | Address\_Line\_2 | No | string | Secondary street address. | Max 200 characters | Suite 100 | | City | No | string | City, locality, town, or municipality. | Max 200 characters | San Francisco | | State | No | string | State, province, prefecture, county, or region. | Max 200 characters | CA | | Country\_Code | No | string | Licensee's country. | ISO 3166-1 alpha-2 (max 2 chars) | US | | Postal\_Code | No | string | Postal code. | Max 12 chars | 94016 | | Phone\_Numbers | At least one must be provided: Phone\_Numbers, Email\_Addresses, or Website\_URLs. | string | Phone numbers registered on the license. | Semicolon-delimited; E.164 format; max 16 chars each (includes + prefix) | +15551234567;+15559876543 | | Email\_Addresses | At least one must be provided: Phone\_Numbers, Email\_Addresses, or Website\_URLs. | string | Email addresses registered on the license. | Semicolon-delimited; max 254 chars each | jane.doe@gmail.com;info@firm.com | | Website\_URLs | At least one must be provided: Phone\_Numbers, Email\_Addresses, or Website\_URLs. | string | Websites registered on the license. Must be prepended with "http://" or "https://". | Semicolon-delimited; max 2000 chars each | https://www.example.com;https://www.example2.com | To prevent impersonation, fraud, and abuse on Meta's advertising platforms, a connection check is essential. The uploaded financial license data must provide at least one of the following for each license: phone numbers, email addresses, or website URLs to perform this check. This ensures that the advertiser attempting to advertise is using a license connected to the entity in the verification. ## Incremental Schema (V1) The incremental schema uses the **same columns** as the full load schema, plus one additional required column: | Column | Required | Type | Description | Allowed Values | | --- | --- | --- | --- | --- | | Operation | Yes | string | The operation to perform on this row. | UPSERT, DELETE | ### Operation Rules * **UPSERT** - Adds a new license or updates an existing one. Follows the same required/optional field rules as the full load schema. * **DELETE** - Removes a license. Only `Credential_Id` is required; all other fields are optional. ### Example Incremental Load Scenario An initial data set contains three licenses: A, B, C. The following changes occur afterward: * License B is updated. * License C is deleted. * License D is added. The incremental CSV would contain: | Credential\_Id | Operation | ... | | --- | --- | --- | | B | UPSERT | (other fields) | | C | DELETE | | | D | UPSERT | (other fields) | License A is **not included** because it had no changes. The timestamp of your last ingested dataset is available via the `ingestion_history/` folder on SFTP (see below). ## SFTP Upload & Ingestion Process ### How to Upload 1. Log into the SFTP server using the credentials Meta provided. 2. Upload both `config.json` and your CSV data file to your **default directory**. 3. Wait for processing. Files can be validated several times a day using `validation` mode in `config.json` but data can only be ingested once daily. ### What Happens After Upload * After processing, both files are **automatically moved** to either a `validation_history/` or `ingestion_history/` directory, depending on the mode set in `config.json`. If the uploaded CSV file contains any row-level errors, such as missing required values or invalid values, a separate CSV file detailing those errors will be generated. Before performing an ingestion, use `validation` mode to confirm your files will be processed correctly. * Each run creates a timestamped folder (e.g., `2026-03-11T12-23-56Z/`) containing the exact files used in the history directory. * If your files are still in the default directory (not in `ingestion_history/` or `validation_history/`), processing has not occurred yet. * **Retention:** The SFTP server retains files for 30 days only. ### Example: Before & After Ingestion Below illustrates the file structure before and after a new ingestion on 3/11/26 involving `data1.csv` and `config.json` with mode `ingestion`. ### Before Ingestion ``` 1. config.json 2. data1.csv 3. ingestion_history/ 4. └── 2026-03-06T04-20-17Z/ 5. ├── config.json 6. ├── license_data.csv 7. ├── csv_errors.csv 8. validation_history/ 9. └── 2026-03-11T05-18-14Z/ 10. ├── config.json 11. ├── data1.csv 12. ├── csv_errors.csv 13. └── 2026-03-06T01-15-24Z/ 14. ├── config.json 15. ├── license_data.csv 16. ├── csv_errors.csv ``` ### After Ingestion ``` 1. ingestion_history/ 2. └── 2026-03-11T12-23-56Z/ 3. ├── config.json 4. ├── data1.csv 5. └── 2026-03-06T04-20-17Z/ 6. ├── config.json 7. ├── license_data.csv 8. ├── csv_errors.csv 9. validation_history/ 10. └── 2026-03-11T05-18-14Z/ 11. ├── config.json 12. ├── data1.csv 13. ├── csv_errors.csv 14. └── 2026-03-06T01-15-24Z/ 15. ├── config.json 16. ├── license_data.csv 17. ├── csv_errors.csv ``` To trigger another ingestion, upload new files to your default directory again. ## Important Notes * **Processing time:** Data may take up to 1 day to appear in Meta's system after ingestion. --- # Paginated Results Source: https://developers.facebook.com/docs/graph-api/results Mirror: https://nermalcat69.github.io/meta-developer-docs/docs/graph-api/results.html # Paginated Results We cover the basics of Graph API terminology and structure in the [Graph API overview](https://developers.facebook.com/docs/graph-api/overview). This document goes into more detail about the results from your API requests. ## Traversing Paged Results When making an API request to a node or edge, you usually don't receive all of the results of that request in a single response. This is because some responses could contain thousands of objects so most responses are paginated by default. ### Cursor-based Pagination Cursor-based pagination is the most efficient method of paging and should always be used when possible. A cursor refers to a random string of characters which marks a specific item in a list of data. The cursor will always point to the item, however it will be invalidated if the item is deleted or removed. Therefore, your app shouldn't store cursors or assume that they will be valid in the future. When reading an edge that supports cursor pagination, you see the following JSON response: ``` { "data": [ ... Endpoint data is here ], "paging": { "cursors": { "after": "MTAxNTExOTQ1MjAwNzI5NDE=", "before": "NDMyNzQyODI3OTQw" }, "previous": "https://graph.facebook.com/{your-user-id}/albums?limit=25&before=NDMyNzQyODI3OTQw" "next": "https://graph.facebook.com/{your-user-id}/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE=" } } ``` A cursor-paginated edge supports the following parameters: * `before` : This is the cursor that points to the start of the page of data that has been returned. * `after` : This is the cursor that points to the end of the page of data that has been returned. * `limit` : This is the maximum number of objects that *may* be returned. A query may return fewer than the value of `limit` due to filtering. Do not depend on the number of results being fewer than the `limit` value to indicate that your query reached the end of the list of data, use the absence of `next` instead as described below. For example, if you set `limit` to 10 and 9 results are returned, there may be more data available, but one item was removed due to privacy filtering. Some edges may also have a maximum on the `limit` value for performance reasons. In all cases, the API returns the correct pagination links. * `next` : The Graph API endpoint that will return the next page of data. If not included, this is the last page of data. Due to how pagination works with visibility and privacy, it is possible that a page may be empty but contain a `next` paging link. Stop paging when the `next` link no longer appears. * `previous` : The Graph API endpoint that will return the previous page of data. If not included, this is the first page of data. Don't store cursors. Cursors can quickly become invalid if items are added or deleted. ### Time-based Pagination Time pagination is used to navigate through results data using Unix timestamps which point to specific times in a list of data. When using an endpoint that uses time-based pagination, you see the following JSON response: ``` { "data": [ ... Endpoint data is here ], "paging": { "previous": "https://graph.facebook.com/{your-user-id}/feed?limit=25&since=1364849754", "next": "https://graph.facebook.com/{your-user-id}/feed?limit=25&until=1364587774" } } ``` A time-paginated edge supports the following parameters: * `until` : A Unix timestamp or [`strtotime`](http://php.net/manual/en/function.strtotime.php?fbclid=IwZXh0bgNhZW0CMTEAYnJpZBExdDFTU2F3MEdKRXZxdWxzRXNydGMGYXBwX2lkATAAAR6WGNNTYBqkKYnABEs58GAdm5eG1M89yAAcLSnEOLxE8Rvg9M9PPmxj5E--kw_aem_m2gBCjToGxXrrnCbFop6Ng) data value that points to the end of the range of time-based data. * `since` : A Unix timestamp or [`strtotime`](http://php.net/manual/en/function.strtotime.php?fbclid=IwZXh0bgNhZW0CMTEAYnJpZBExdDFTU2F3MEdKRXZxdWxzRXNydGMGYXBwX2lkATAAAR6WGNNTYBqkKYnABEs58GAdm5eG1M89yAAcLSnEOLxE8Rvg9M9PPmxj5E--kw_aem_m2gBCjToGxXrrnCbFop6Ng) data value that points to the start of the range of time-based data. * `limit` : This is the maximum number of objects that *may* be returned. A query may return fewer than the value of `limit` due to filtering. Do not depend on the number of results being fewer than the `limit` value to indicate your query reached the end of the list of data, use the absence of `next` instead as described below. For example, if you set `limit` to 10 and 9 results are returned, there may be more data available, but one item was removed due to privacy filtering. Some edges may also have a maximum on the `limit` value for performance reasons. In all cases, the API returns the correct pagination links. * `next` : The Graph API endpoint that will return the next page of data. * `previous` : The Graph API endpoint that will return the previous page of data. For consistent results, specify both `since` and `until` parameters. Also, it is recommended that the time difference is a maximum of 6 months. ### Offset-based Pagination Offset pagination can be used when you do not care about chronology and just want a specific number of objects returned. Only use this if the edge does not support cursor or time-based pagination. An offset-paginated edge supports the following parameters: * `offset` : This offsets the start of each page by the number specified. * `limit` : This is the maximum number of objects that *may* be returned. A query may return fewer than the value of `limit` due to filtering. Do not depend on the number of results being fewer than the `limit` value to indicate that your query reached the end of the list of data, use the absence of `next` instead as described below. For example, if you set `limit` to 10 and 9 results are returned, there may be more data available, but one item was removed due to privacy filtering. Some edges may also have a maximum on the `limit` value for performance reasons. In all cases, the API returns the correct pagination links. * `next` : The Graph API endpoint that will return the next page of data. If not included, this is the last page of data. Due to how pagination works with visibility and privacy, it is possible that a page may be empty but contain a `next` paging link. Stop paging when the `next` link no longer appears. * `previous` : The Graph API endpoint that will return the previous page of data. If not included, this is the first page of data. Note that if new objects are added to the list of items being paged, the contents of each offset-based page will change. Offset based pagination is not supported for all API calls. To get consistent results, we recommend you to paginate using the previous/next links we return in the response. For objects that have many items returned, such as [comments](https://developers.facebook.com/docs/graph-api/reference/object/comments) which can number in the tens of thousands, you may encounter limits while paging. The API will return an error when your app has reached the cursor limit: ``` { "error": { "message": "(#100) The After Cursor specified exceeds the max limit supported by this endpoint", "type": "OAuthException", "code": 100 } } ``` ## Next Steps Now that you are more familiar with the Graph API visit our [Graph Explorer Tool Guide](https://developers.facebook.com/docs/graph-api/explorer) to explore the Graph without writing code, [Common Uses](https://developers.facebook.com/docs/graph-api/using-graph-api/common-scenarios) to view the most common tasks performed, and [the SDKs available](https://developers.facebook.com/docs/graph-api/using-graph-api/using-with-sdks). --- # Platform Versioning Source: https://developers.facebook.com/docs/graph-api/guides/versioning Mirror: https://nermalcat69.github.io/meta-developer-docs/docs/graph-api/guides/versioning.html # Platform Versioning Facebook's Platform supports versioning so that app builders can roll out changes over time. This document explains how SDKs and APIs affected by versions and how to use those versions in your requests. ## Versioning Not all APIs and SDKs share the same versioning system. For example, the Graph API is versioned with a different pace and numbering compared to the Facebook SDK for iOS. All Facebook SDKs support the ability to interact with different versions of our APIs. Multiple versions of APIs or SDKs can exist at the same time with different functionality in each version. ### What is the latest Graph API Version? The latest Graph API version is `v25.0` ### Why do we have versions? The goal for having versioning is for developers building apps to be able to understand in advance when an API or SDK might change. They help with web development, but are critical with mobile development because a person using your app on their phone may take a long time to upgrade (or may never upgrade). Each version will remain for at least 2 years from release giving you a solid timeline for how long your app will remain working, and how long you have to update it to newer versions. ### Version Schedules Each version is guaranteed to operate for at least two years. **A version will no longer be usable two years after the date that the subsequent version is released.** For example, if API version v2.3 is released on March 25th, 2015 and API version v2.4 is released August 7th, 2015 then v2.3 would expire on August 7th, 2017, two years after the release of v2.4. For APIs, once a version is no longer usable, any calls made to it will be defaulted to the next oldest, usable version. Here is a timeline example: ![](https://scontent.fdel1-6.fna.fbcdn.net/v/t39.2178-6/10333112_605697729514600_969655318_n.png?_nc_cat=106&_nc_map=urlgen_bucketless&ccb=1-7&_nc_ohc=H-lEk5SXuUAQ7kNvwH4vRPQ&_nc_oc=AdqEubUvoDJYjxtUyPhftc6FHy3hZC1EnWY7JnbRV92QkF0HvW1ZTVDOr770y0zo18o7vPjF0CvA--PrDLhwTZbl&_nc_zt=14&_nc_ht=scontent.fdel1-6.fna&_nc_gid=UTttoeYniesd7U19bz0Zww&_nc_ss=7b2a8&stp=dst-emg0_fr_q75_tt6&ur=34156e&_nc_sid=3fabc8&oh=00_AQA4aDRCH92omp69nhXlR8opziF8sNi5OGfVuxQzseSBKA&oe=6A4BFA4B) For SDKs, a version will always remain available as it is a downloadable package. However, the SDK may rely upon APIs or methods which no longer work, so you should assume an end-of-life SDK is no longer functional. You can find specific information about our version timelines, changes, and release dates on our [changelog page](https://developers.facebook.com/docs/graph-api/changelog). ### Will everything remain completely unchanged in a version? Facebook does reserve the right to make changes in any API in a short period of time for issues related to security or privacy. These changes don't happen often, but they do happen. ### What happens if I don't specify a version for an API? We refer to an API call made without specifying a version as an **unversioned** call. For example, let's say the current version is v4.0. The call is as follows: ``` curl -i -X "https://graph.facebook.com/v4.0/{my-user-id}&access_token={access-token}" ``` The same unversioned call is as follows: ``` curl -i -X "https://graph.facebook.com/{my-user-id}&access_token={access-token}" ``` An unversioned call uses the version set in the app dashboard **Upgrade API Version** card under **Settings > Advanced**. In following example, the version set in the app dashboard is v2.10 and the unversioned call is equivalent to: ``` curl -i -X "https://graph.facebook.com/v2.10/{my-user-id}&access_token={access-token}" ``` We recommend you always specify the version where possible. #### Limitations * You can not make unversioned API calls to the Facebook JavaScript SDK. ### Can my app make calls to versions older than the current version? You can specify older versions in your API calls as long as they are available and your app has made calls to that version. For example, if your app was created after v2.0 was released and makes calls using v2.0, it will be able to make calls to v2.0 until the version expires even after newer versions have been released. If you created your app after v2.0 but did not make any calls until v2.2, your app will not be able to make calls using v2.0 or to v2.1. It will only be able to make calls using v2.2 and newer versions. ### Marketing API Versioning The [Marketing API](https://developers.facebook.com/docs/marketing-apis) has its own versioning scheme. Both version numbers and their schedules are different from the Graph API's state of things. [Learn more about Marketing API Versioning](https://developers.facebook.com/docs/marketing-api/versions) ## Making Versioned Requests ### Graph API Whether core or extended, almost all Graph API endpoints are available through a versioned path. We've a [full guide to using versions with the Graph API](https://developers.facebook.com/docs/graph-api/quickstart#versions) in our [Graph API quickstart guide](https://developers.facebook.com/docs/graph-api/quickstart). ### Dialogs Versioned paths aren't just true for API endpoints, they're also true for dialogs and social plugins. For example, if you want to generate the Facebook Login dialog for a web app, you can prepend a version number to the endpoint that generates the dialog: ``` https://www.facebook.com/v25.0/dialog/oauth? client_id={app-id} &redirect_uri={redirect-uri} ``` ### Social Plugins If you're using the HTML5 or xfbml versions of [our social plugins](https://developers.facebook.com/docs/plugins/), the version rendered will be determined by the version specified when you're [initialising the JavaScript SDK](https://developers.facebook.com/docs/graph-api/guides/versioning#jssdk). If you're inserting an iframe or plain link version of one of our plugins, you'd prepend the version number to the source path of the plugin: ``` ``` ## Making Versioned Requests from SDKs If you're using the Facebook SDK for iOS, Android or JavaScript, making versioning calls is largely automatic. Note that this is distinct from each SDKs own versioning system. ### JavaScript The JavaScript SDK can only use different API versions if you're [using the `sdk.js` path](https://developers.facebook.com/docs/apps/changelog/#v2_0_js_sdk). If you're using `FB.init()` from the [JavaScript SDK](https://developers.facebook.com/docs/javascript), you need to use the version parameter, like this: ``` FB.init({ appId : '{app-id}', version : 'v25.0' }); ``` If you set the version flag in the init, then any calls to [`FB.api()`](https://developers.facebook.com/docs/javascript/reference/FB.api) will automatically have the version prepended to the path that's called. The same is true for any dialogs for Facebook Login that happen to get called. You will get the Facebook Login dialog for that version of the API. If you need to, you can override a version by just prepending the version to the path of the endpoint in the `FB.api()` call. ### iOS Each version of the Facebook SDK for iOS that's released is tied to the version that's available on the date of release. This means that if you're upgrading to a new SDK you're also upgrading to the latest API version as well (although you can manually specify any earlier, available API version with [`[FBSDKGraphRequest initWithGraphPath]`](https://developers.facebook.com/docs/reference/ios/current/class/FBSDKGraphRequest/#initWithGraphPath:parameters:)). The API version is listed with the release of each version of the [Facebook SDK for iOS](https://developers.facebook.com/docs/ios). Much like the JavaScript SDK, the version is prepended to any calls you make to the graph API through the Facebook SDK for iOS. For example, if `v2.7` was the most recent version of the API, the call `/me/friends` - used in the following code sample - will actually call `/v2.7/me/friends`: ``` [[[FBSDKGraphRequest alloc] initWithGraphPath:@"me/friends" parameters:@{@"fields": @"cover,name,start_time"}] startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) { (...) }]; ``` You can override the version of the call with [`[FBSDKGraphRequestConnection overrideVersionPartWith]`](https://developers.facebook.com/docs/reference/ios/current/class/FBSDKGraphRequestConnection/#overrideVersionPartWith:). ### Android Each version of the Facebook SDK for Android that's released is tied to the version that's available on the date of release. This means that if you're upgrading to a new SDK you're also upgrading to the latest API version as well (although you can manually specify any earlier, available API version with `GraphRequest.setVersion()`). The API version is listed with the release of each version of the Facebook SDK for Android. Much like the JavaScript SDK, the version is prepended to any calls you make to the graph API through the Facebook SDK for Android. For example, if `v2.7` was the most recent version of the API, the call `/me` - used in the following code sample - will actually call `/v2.7/me`: ``` GraphRequest request = GraphRequest.newGraphPathRequest ( accessToken, "/me/friends", new GraphRequest.GraphJSONObjectCallback() { @Override public void onCompleted( JSONObject object, GraphResponse response) { // Application code } }); Bundle parameters = new Bundle(); parameters.putString("fields", "id,name,link"); request.setParameters(parameters); request.executeAsync(); ``` You can override the version of the call with `GraphRequest.setVersion()`. --- # Rate Limits Source: https://developers.facebook.com/docs/graph-api/overview/rate-limiting Mirror: https://nermalcat69.github.io/meta-developer-docs/docs/graph-api/overview/rate-limiting.html # Rate Limits A rate limit is the number of API calls an app or user can make within a given time period. If this limit is exceeded or if CPU or total time limits are exceeded, the app or user may be throttled. API requests made by a throttled user or app will fail. All API requests are subject to rate limits. Graph API requests are subject to [Platform Rate Limits](https://developers.facebook.com/docs/graph-api/overview/rate-limiting#platform-rate-limits), while Marketing API and Instagram Platform requests are subject to [Business Use Case (BUC) Rate Limits](https://developers.facebook.com/docs/graph-api/overview/rate-limiting#buc-rate-limits). Pages API requests are subject to either Platform or BUC Rate Limits, depending on the token used in the request; requests made with [application](https://developers.facebook.com/docs/facebook-login/access-tokens#apptokens) or [user access tokens](https://developers.facebook.com/docs/facebook-login/access-tokens#usertokens) are subject to Platform Rate Limits, while requests made with [system user](https://developers.facebook.com/docs/marketing-api/businessmanager/systemuser#generate-token) or [page access tokens](https://developers.facebook.com/docs/facebook-login/access-tokens#pagetokens) are subject to Business Use Case Rate Limits. Real time rate limit usage statistics are described in headers that are included with most API responses once enough calls have been made to an endpoint. Platform Rate Limit usage statistics are also displayed in the [App Dashboard](https://developers.facebook.com/apps/). Once a rate limit is reached, any subsequent requests made by your app will fail and the API will return an error code until enough time has passed for the call count to drop below the limit. If both Platform and Business Use Case rate limits can be applied to a request, BUC rate limits will be applied. ## Platform Rate Limits Platform Rate Limits are tracked on an individual application or user level, depending on the type of token used in the request. ### Applications Graph API requests made with an [application access token](https://developers.facebook.com/docs/facebook-login/access-tokens#apptokens) are counted against that app's rate limit. An app's call count is the number of calls it can make during a rolling one hour window and is calculated as follows: `Calls within one hour = 200 * Number of Users` The Number of Users is based on the number of unique daily active users an app has. In cases where there are slow periods of daily usage, such as if your app has high activity on weekends but low activity over weekdays, the weekly and monthly active Users are used to calculate the number of Users for your app. Apps with high daily engagement will have higher rate limits than apps with low daily engagement, regardless of the actual number of app installs. Note that this is not a per User limit but a limit on calls made by your app. Any individual User can make more than 200 calls per hour using your app, as long as the total calls from your app does not exceed the app maximum. For example, if your app has 100 Users, your app can make 20,000 calls per hour. However, your top ten most engaged Users could make 19,000 of those calls. ### Users Graph API requests made with a [user access token](https://developers.facebook.com/docs/facebook-login/access-tokens#usertokens) are counted against that user's call count. A user's call count is the number of calls a user can make during a rolling one hour window. Due to privacy concerns, we do not reveal actual call count values for users. Note that a user's call count can be spread over multiple apps. For example, a user could make X calls through App1 and Y calls through App2. If X+Y exceeds the user's call count that user will be rate limited. This does not necessarily mean that any app is doing something wrong; it could be that the user is using multiple apps or is misusing the API. ### Headers Endpoints that receive enough requests from your app will include a `X-App-Usage` or `X-Ad-Account-Usage` (for v3.3 and older Ads API calls) HTTP header in their responses. The header will contain a JSON-formatted string that describes current application rate limit usage. #### Header Contents | Key | Value Description | | --- | --- | | `call_count` | A whole number expressing the percentage of calls made by your app over a rolling one hour period. | | `total_cputime` | A whole number expressing the percentage of CPU time allotted for query processing. | | `total_time` | A whole number expressing the percentage of total time allotted for query processing. | #### X-Ad-Account-Usage Header Contents | Key | Value Description | | --- | --- | | `acc_id_util_pct` | The percentage of calls made for this ad account before the rate limit is reached. | | `reset_time_duration` | Time duration (in seconds) it takes to reset the current rate limit to 0. | | `ads_api_access_tier` | Tiers allows your app to access the Marketing API. By default, apps are in the `development_access` tier. `Standard_access` enables lower rate limiting. To get a higher rate limit and get to the standard tier, you can apply for the "Advanced Access" to the [Ads Management Standard Access](https://developers.facebook.com/docs/marketing-api/overview/authorization#layer-2--access-levels--permissions--and-features) feature. | #### Total CPU Time The amount of CPU time the request takes to process. When `total_cputime` reaches 100, calls may be throttled. #### Total Time The length of time the request takes to process. When `total_time` reaches 100, calls may be throttled. #### Sample X-App-Usage Header Value ``` x-app-usage: { "call_count": 28, //Percentage of calls made "total_time": 25, //Percentage of total time "total_cputime": 25 //Percentage of total CPU time } ``` #### Sample X-Ad-Account-Usage Header Value ``` x-ad-account-usage: { "acc_id_util_pct": 9.67, //Percentage of calls made for this ad account. "reset_time_duration": 100, //Time duration (in seconds) it takes to reset the current rate limit score. "ads_api_access_tier": 'standard_access' //Tiers allows your app to access the Marketing API. standard_access enables lower rate limiting. } ``` ### Dashboard The [app dashboard](https://developers.facebook.com/apps/) displays the number of rate limited app users, the app's current Application Rate Limits usage percentage, and displays average activity for the past 7 days. In the **Application Rate Limit** card, click **View Details** and hover over any point on the graph to see more details about usage for that particular moment. Because usage depends on call volume, this graph may not show a full 7 days. Apps with a higher volume of calls will show more days. ### Error Codes When an app or user has reached their rate limit, requests made by that app or user will fill and the API will respond with an error code. #### Throttle Error Codes | Error Code | Description | | --- | --- | | `4` | Indicates that the app whose token is being used in the request has reached its rate limit. | | `17` | Indicates that the User whose token is being used in the request has reached their rate limit. | | `17 with subcode 2446079` | Indicates that the token being used in the Ads API v3.3 or older request has reached its rate limit. | | `32` | Indicates that the User or app whose token is being used in the Pages API request has reached its rate limit. | | `613` | Indicates that a custom rate limit has been reached. To help resolving this issue, visit the supporting docs for the specific API you are calling for custom rate limits that may be applied. | | `613 with subcode 1996` | Indicates that we have noticed inconsistent behavior in the API request volume of your app. If you have made any recent changes that affect the number of API requests, you may be encountering this error. | #### Sample Response ``` { "error": { "message": "(#32) Page request limit reached", "type": "OAuthException", "code": 32, "fbtrace_id": "Fz54k3GZrio" } } ``` ### Facebook Stability Throttle Codes | Error Code | Description | | --- | --- | | `throttled` | Whether the query is throttled or not. Values: `True`, `False` | | `backend_qps` | First throttling factor `backend_qps`. Supported values: * `actual_score`—Actual `backend_qps` of this app. Value: `8` * `limit`—`backend_qps` limit of this app. Value: `5` * `more_info`—Queries need a large number of backend requests to handle. We suggest to send fewer queries or simplify queries with narrower time ranges, fewer object IDs, and so on. | | `complexity_score` | Second throttling factor `complexity_score`. Supported values: * `actual_score`—Actual `complexity_score` of this app. Value: `0.1` * `limit`—`complexity_score` limit of this app. Value: `0.01` * `more_info`—High `complexity_score` means your queries are very complex and request large amounts of data. We suggest to simplify queries with shorter time ranges, fewer object IDs, metrics or breakdowns, and so on. Split large, complex queries into multiple smaller queries and space them out. | ### Best Practices * When the limit has been reached, stop making API calls. Continuing to make calls will continue to increase your call count, which will increase the time before calls will be successful again. * Spread out queries evenly to avoid traffic spikes. * Use filters to limit the data response size and avoid calls that request overlapping data. * Check the `X-App-Usage` HTTP header to see how close your app is to its limit and when you can resume making calls when the limit has been reached. * If Users are being throttled, be sure your app is not the cause. Reduce the user's calls or spread the user's calls more evenly over time. ## Business Use Case Rate Limits All Marketing API requests, and Pages API requests made with a system or page access token, are subject to Business Use Case (BUC) Rate Limits, and depend on the endpoints you are querying. For Marketing API, the rate limit is applied to the ad account across the same Business Use Case. For example, all endpoints with the Ads Management business use case will share the total quota within the same ad account. If a certain endpoint makes a lot of API requests and causes throttling, other endpoints configured with the same business use case will also receive rate limiting errors. The quota depends on the app's Marketing API Access Tier. The standard access Marketing API tier will have more quotas than the development access Marketing API tier. By default, an new app should be on the development tier. If you need to upgrade to get more rate limiting quota, upgrade to Advanced Access of [Ads Management Standard Access](https://developers.facebook.com/docs/features-reference/ads-management-standard-access/) in App Review. | | | | --- | --- | | * [Ad Insights](https://developers.facebook.com/docs/graph-api/overview/rate-limiting#ads-insights) * [Ads Management](https://developers.facebook.com/docs/graph-api/overview/rate-limiting#ads-management) * [Catalog](https://developers.facebook.com/docs/graph-api/overview/rate-limiting#catalog) * [Custom Audience](https://developers.facebook.com/docs/graph-api/overview/rate-limiting#custom-audience) * [Instagram Platform](https://developers.facebook.com/docs/graph-api/overview/rate-limiting#instagram-platform) * [Lead Generation](https://developers.facebook.com/docs/graph-api/overview/rate-limiting#leadgen) | * [Messenger](https://developers.facebook.com/docs/graph-api/overview/rate-limiting#messenger) * [Pages](https://developers.facebook.com/docs/graph-api/overview/rate-limiting#pages) * [Spark AR Commerce Effect Management](https://developers.facebook.com/docs/graph-api/overview/rate-limiting#spark-ar) * [WhatsApp Business Management API](https://developers.facebook.com/docs/graph-api/overview/rate-limiting#wa-biz-api) | ### Ads Insights Requests made by your app to the Ads Insights API are counted against the app's rate limit metrics such as call count, total CPU time and total time. An app's call count is the number of calls it can make during a rolling one hour window and is calculated as follows: For apps with [Standard Access](https://developers.facebook.com/docs/graph-api/overview/access-levels/#standard-access) to the Ads Management Standard Access feature: `Calls within one hour = 600 + 400 * Number of Active ads - 0.001 * User Errors` For apps with [Advanced Access](https://developers.facebook.com/docs/graph-api/overview/access-levels/#advanced-access) to the Ads Management Standard Access feature: `Calls within one hour = 190000 + 400 * Number of Active ads - 0.001 * User Errors` The Number of Active ads is the number of ads currently running per ad account. User Errors is the number of errors received when calling the API. To get a higher rate limit, you can apply for the [Ads Management Standard Access](https://developers.facebook.com/docs/marketing-api/overview/authorization#layer-2--access-levels--permissions--and-features) feature. Rate limiting may also be subject to the total CPU time and total wall time during a rolling one hour window. For more details, check the HTTP [`X-Business-Use-Case`](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/#headers-2) header `total_cputime` and `total_time`. If you are receiving rate limiting errors, you can also refer to `estimated_time_to_regain_access` in the [`X-Business-Use-Case`](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/#headers-2) header for the estimated blocking time. ### Ads Management Requests made by your app to the Ads Management API are counted against the app's rate limit metrics such as call count, total CPU time and total time. An app's call count is the number of calls it can make during a rolling one hour window and is calculated as follows: For apps with [Standard Access](https://developers.facebook.com/docs/graph-api/overview/access-levels/#standard-access)to the Ads Management Standard Access feature: `Calls within one hour = 300 + 40 * Number of Active ads` For apps with [Advanced Access](https://developers.facebook.com/docs/graph-api/overview/access-levels/#advanced-access) to the Ads Management Standard Access feature: `Calls within one hour = 100000 + 40 * Number of Active ads` The Number of Active Ads is the number of ads for each ad account. Rate limiting may also be subject to the total CPU time and total wall time during a rolling one hour window. For more details, check the HTTP [`X-Business-Use-Case`](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/#headers-2) header `total_cputime` and `total_time`. If you are receiving rate limiting errors, you can also refer to `estimated_time_to_regain_access` in the [`X-Business-Use-Case`](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/#headers-2) header for the estimated blocking time. ### Catalog #### Catalog Batch Requests made by your app are counted against the rate limit metrics such as call count, total CPU time and total time your app can make in a rolling one minute period per each catalog ID and is calculated as follows: `Calls within one minute = 8 + 8 * log2(DA impressions + PDP visits)` The DA impressions and PDP visits are a number of dynamic ads impressions and product detail page visits of the individual catalog with intent in the last 28 days. The more users see products from your catalogs, the more call quota is allocated. | Type of Call | Endpoint | | --- | --- | | POST | /{catalog\_id}/items\_batch | | POST | /{catalog\_id}/localized\_items\_batch | | POST | /{catalog\_id}/batch | #### Catalog Management Requests made by your app are counted against the number of calls your app can make in a rolling one hour period per each catalog ID and is calculated as follows: `Calls within one hour = 20,000 + 20,000 * log2(DA impressions + PDP visits)` The DA impressions and PDP visits are a number of dynamic ads impressions and product detail page visits of the business (on all catalogs) with intent in the last 28d. The more users see products from your catalogs, the more call quota is allocated. This formula is applied on various catalog endpoints. For more information on how to get your current rate usage, see [Headers](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/#headers). Rate limiting may also be subject to the total CPU time and total wall time during a rolling one hour window. For more details, check the HTTP [`X-Business-Use-Case`](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/#headers-2) header `total_cputime` and `total_time`. If you are receiving rate limiting errors, you can also refer to `estimated_time_to_regain_access` in the [`X-Business-Use-Case`](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/#headers-2) header for the estimated blocking time. ### Custom Audience Requests made by your app to the Custom Audience API are counted against the app's rate limit metrics such as call count, total CPU time and total time. An app's call count is the number of calls it can make during a rolling one hour window and is calculated as follows but will never exceed 700000: For apps with [Standard Access](https://developers.facebook.com/docs/graph-api/overview/access-levels/#standard-access) to the Ads Management Standard Access feature: `Calls within one hour = 5000 + 40 * Number of Active Custom Audiences` For apps with [Advanced Access](https://developers.facebook.com/docs/graph-api/overview/access-levels/#advanced-access) to the Ads Management Standard Access feature: `Calls within one hour = 190000 + 40 * Number of Active Custom Audiences` The Number of Active Custom Audiences is the number of active [custom audiences](https://developers.facebook.com/docs/marketing-api/audiences-api) for each ad account. Rate limiting may also be subject to the total CPU time and total wall time during a rolling one hour window. For more details, check the HTTP [`X-Business-Use-Case`](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/#headers-2) header `total_cputime` and `total_time`. If you are receiving rate limiting errors, you can also refer to `estimated_time_to_regain_access` in the [`X-Business-Use-Case`](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/#headers-2) header for the estimated blocking time. ### Instagram Platform Calls to the Instagram Platform endpoints, excluding messaging, are counted against the calling app's call count. An app's call count is unique for each app and app user pair, and is the number of calls the app has made in a rolling 24 hour window. It is calculated as follows: `Calls within 24 hours = 4800 * Number of Impressions` The Number of Impressions is the number of times any content from the app user's Instagram professional account has entered a person's screen within the last 24 hours. #### Notes * Business Discovery and Hashtag Search API are subject to [Platform Rate Limits](https://developers.facebook.com/docs/graph-api/overview/rate-limiting#platform-rate-limits). ### Messaging Rate Limits Calls to the Instagram messaging endpoints are counted against the number of calls your app can make per Instagram professional account and the API used. #### Conversations API * Your app can make 2 calls per second per Instagram professional account. #### Private Replies API * Your app can make 100 calls per second per Instagram professional account for private replies to Instagram Live comments * Your app can make 750 calls per hour per Instagram professional account for private replies to comments on Instagram posts and reels #### Send API * Your app can make 100 calls per second per Instagram professional account for messages that contain text, links, reactions, and stickers * Your app can make 10 calls per second per Instagram professional account for messages that contain audio or video content ### LeadGen Requests made by your app to the LeadGen API are counted against the app's call count. An app's call count is the number of calls it can make during a rolling 24 hour window and is calculated as follows: `Calls within 24 hours = 4800 * Leads Generated` The Number of Leads Generated is the number of leads generated per Page for this Ad Account over the past 90 days. ### Messenger Platform Rate limits for the Messenger Platform are dependent on the API used and, in some instances, the message content. ### Messenger API Requests made by your app are counted against the number of calls your app can make in a rolling 24 hour period and is calculated as follows: `Calls within 24 hours = 200 * Number of Engaged Users` The Number of Engaged Users is the number of people the business can message via Messenger. **Conversations API** * Your app can make 2 calls per second per Facebook Page **Send API** * Your app can make 300 calls per second per Facebook Page for messages that contain text, links, reactions, and stickers * Your app can make 10 calls per second per Facebook Page account for messages that contain audio or video content * Your app may be rate limited if too many messages are being sent to a single thread **Private Replies API** * Your app can make 750 calls per hour per Facebook Page for private replies to comments on Instagram posts and reels ### Messenger API for Instagram Requests made by your app are counted against the number of calls your app can make per Instagram professional account and the API used. **Conversations API** * Your app can make 2 calls per second per Instagram professional account **Send API** * Your app can make 300 calls per second per Instagram professional account for messages that contain text, links, reactions, and stickers * Your app can make 10 calls per second per Instagram professional account for messages that contain audio or video content * Your app may be rate limited if too many messages are being sent to a single thread **Private Replies API** * Your app can make 100 calls per second per Instagram professional account for private replies to Instagram Live comments * Your app can make 750 calls per hour per Instagram professional account for private replies to comments on Instagram posts and reels ### Pages The Page Rate Limits may use either the Platform or BUC rate limit logic depending on the type of token used. Any Pages API calls that are made using a [Page](https://developers.facebook.com/docs/facebook-login/access-tokens#pagetokens) or [system user access token](https://developers.facebook.com/docs/marketing-api/businessmanager/systemuser#systemusertoken) use the rate limit calculation below. Any calls made with [application](https://developers.facebook.com/docs/facebook-login/access-tokens#apptokens) or [user access tokens](https://developers.facebook.com/docs/facebook-login/access-tokens#usertokens) are subject to application or User rate limits. Requests made by your app to the Pages API using a Page access token or system User access token are counted against the app's call count. An app's call count is the number of calls it can make during a rolling 24 hour window and is calculated as follows: `Calls within 24 hours = 4800 * Number of Engaged Users` The Number of Engaged Users is the number of Users who engaged with the Page per 24 hours. Requests made by your app to the Pages API using a User access token or App access token follow the [Platform Rate Limit logic](https://developers.facebook.com/docs/graph-api/overview/rate-limiting#platform-rate-limits). To avoid [rate limiting](https://developers.facebook.com/docs/graph-api/overview/rate-limiting#pages) issues when using the [Page Public Access Content feature](https://developers.facebook.com/docs/pages/overview/permissions-features#features), using a [system user access token](https://www.facebook.com/business/help/503306463479099) is recommended. ### Spark AR Commerce Effect Management Requests made by your app to any Commerce endpoints are counted against the app's call count. An app's call count is the number of calls it can make during a rolling one hour window and is calculated as follows: `Calls within one hour = 200 + 40 * Number of Catalogs` The Number of Catalogs is the total number of catalogs across all commerce accounts managed by your app. ### Threads Calls to the Threads API are counted against the calling app's call count. An app's call count is unique for each app and app user pair and is the number of calls the app has made in a rolling 24-hour window. It is calculated as follows: `Calls within 24 hours = 4800 * Number of Impressions` The Number of Impressions is the number of times any content from the app user's Threads account has entered a person's screen within the last 24 hours. Rate limiting may also be subject to total CPU time per day: `720000 * number_of_impressions for total_cputime 2880000 * Number of Impressions for total_time` **Note:** The minimum value for impressions is 10 (so if the impressions is less than 10 we default to 10). ### WhatsApp Business Management API Requests made by your app on your WhatsApp Business Account (WABA) are counted against your app's request count. An app's request count is the number of requests it can make during a rolling one hour. For the following endpoints, your app can make 200 requests per hour, per app, per WABA, by default. For active WABAs with at least one registered phone number, your app can make 5000 requests per hour, per app, per active WABA. | Type of request | Endpoint | | --- | --- | | `GET` | `/` | | `GET`, `POST`, and `DELETE` | `//assigned_users` | | `GET` | `//phone_numbers` | | `GET`, `POST`, and `DELETE` | `//message_templates` | | `GET`, `POST`, and `DELETE` | `//subscribed_apps` | | `GET` | `/` | For the following [Credit Line API](https://developers.facebook.com/docs/whatsapp/embedded-signup/manage-accounts/share-and-revoke-credit-lines) requests, your app can make 5000 requests per hour. | Type of request | Endpoint | | --- | --- | | `GET` | `//extendedcredits` | | `POST` | `//whatsapp_credit_sharing_and_attach` | | `GET` and `DELETE` | `/` | | `GET` | `//owning_credit_allocation_configs` | For more information on how to get your current rate usage, see [Headers](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/#headers). ### Headers All API responses made by your app that are rate limited using the BUC logic include an `X-Business-Use-Case-Usage` (for v3.3 and older Ads API calls) HTTP header with a JSON-formatted string that describes current application rate limit usage. This header can return up to 32 objects in one call. #### X-Business-Use-Case Usage Header Contents | Error Code | Value Description | | --- | --- | | `business-id` | The ID of the business associated with the token making the API calls. | | `call_count` | A whole number expressing the percentage of allowed calls made by your app over a rolling one hour period. | | `estimated_time_to_regain_access` | Time, in minutes, until calls will not longer be throttled. | | `total_cputime` | A whole number expressing the percentage of CPU time allotted for query processing. | | `total_time` | A whole number expressing the percentage of total time allotted for query processing. | | `type` | Type of rate limit applied. Value can be one of the following: `ads_insights`, `ads_management`, `custom_audience`, `instagram`, `leadgen`, `messenger`, or `pages`. | | `ads_api_access_tier` | For `ads_insights` and `ads_management` types only. Tiers allows your app to access the Marketing API. By default, apps are in the `development_access` tier. `Standard_access` enables lower rate limiting. To get a higher rate limit and get to the standard tier, you can apply for the "Advanced Access" to the [Ads Management Standard Access](https://developers.facebook.com/docs/marketing-api/overview/authorization#layer-2--access-levels--permissions--and-features) feature. | #### Total CPU Time The amount of CPU time the request takes to process. When total\_cputime reaches 100, calls may be throttled. #### Total Time The length of time the request takes to process. When total\_time reaches 100, calls may be throttled. #### Ads API Access Tier For `ads_insights` and `ads_management` types only. Tiers allows your app to access the Marketing API. By default, apps are in the `development_access` tier. `Standard_access` enables lower rate limiting. To get a higher rate limit and get to the standard tier, you can apply for the "Advanced Access" to the [Ads Management Standard Access](https://developers.facebook.com/docs/marketing-api/overview/authorization#layer-2--access-levels--permissions--and-features) feature. #### Sample X-Business-Use-Case-Usage Header Value ``` x-business-use-case-usage: { "{business-object-id}": [ { "type": "{rate-limit-type}", //Type of BUC rate limit logic being applied. "call_count": 100, //Percentage of calls made. "total_cputime": 25, //Percentage of the total CPU time that has been used. "total_time": 25, //Percentage of the total time that has been used. "estimated_time_to_regain_access": 19, //Time in minutes to regain access. "ads_api_access_tier": "standard_access" //Tiers allows your app to access the Marketing API. standard_access enables lower rate limiting. } ], "66782684": [ { "type": "ads_management", "call_count": 95, "total_cputime": 20, "total_time": 20, "estimated_time_to_regain_access": 0, "ads_api_access_tier": "development_access" } ], "10153848260347724": [ { "type": "ads_insights", "call_count": 97, "total_cputime": 23, "total_time": 23, "estimated_time_to_regain_access": 0, "ads_api_access_tier": "development_access" } ], "10153848260347724": [ { "type": "pages", "call_count": 97, "total_cputime": 23, "total_time": 23, "estimated_time_to_regain_access": 0 } ], ... } ``` ### Error Codes When your app reaches its Business Use Case rate limit, subsequent requests made by your app will fail and the API will respond with an error code. | Error Code | BUC Rate Limit Type | | --- | --- | | `error code 80000, error subcode 2446079` | Ads Insights | | `error code 80004, error subcode 2446079` | Ads Management | | `error code 80003, error subcode 2446079` | Custom Audience | | `error code 80002` | Instagram | | `error code 80005` | LeadGen | | `error code 80006` | Messenger | | `error code 32` | Page calls made with a User access token | | `error code 80001` | Page calls made with a Page or System User access token | | `error code 17, error subcode 2446079` | V3.3 and Older Ads API excluding Ads Insights | | `error code 80008` | WhatsApp Business Management API | | `error code 80014` | Catalog Batch | | `error code 80009` | Catalog Management | #### SampleError Code Message ``` { "error": { "message": "(#80001) There 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.", "type": "OAuthException", "code": 80001, "fbtrace_id": "AmFGcW_3hwDB7qFbl_QdebZ" } } ``` ### Best Practices * When the limit has been reached, stop making API calls. Continuing to make calls will continue to increase your call count, which will increase the time before calls will be successful again. * Check the `X-Business-Use-Case-Usage` HTTP header to see how close your ad account is to its limit and when you can resume making calls. * Verify the error code and API endpoint to confirm the throttling type. * Switch to other ad accounts and come back to this account later. * It is better to create a new ad than to change existing ones. * Spread out queries evenly between two time intervals to avoid sending traffic in spikes. * Use filters to limit the data response size and avoid calls that request overlapping data. ## FAQ #### What do we consider an API call? All calls count towards the rate limits, not just individual API requests. For example, you can make a single API request specifying multiple IDs, but each ID counts as one API call. The following table illustrates this concept. | Example Request(s) | Number of API Calls | | --- | --- | | `GET https://graph.facebook.com/photos?ids=4` `GET https://graph.facebook.com/photos?ids=5` `GET https://graph.facebook.com/photos?ids=6` | 3 | | `GET https://graph.facebook.com/photos?ids=4,5,6` | 3 | We strongly recommend specifying multiple IDs in one API request when possible, as this improves performance of your API responses. #### I'm building a scraper, is there anything else I should worry about? If you are building a service that scrapes data, please read [our scraping terms](https://www.facebook.com/apps/site_scraping_tos_terms.php?hc_location=ufi). --- # Secure Graph API Calls Source: https://developers.facebook.com/docs/graph-api/guides/secure-requests Mirror: https://nermalcat69.github.io/meta-developer-docs/docs/graph-api/guides/secure-requests.html # Secure Graph API Calls Almost every Graph API call requires an [access token](https://developers.facebook.com/docs/facebook-login/access-tokens/). Malicious developers can steal access tokens and use them to send spam from your app. Meta has automated systems to detect this, but you can help us secure your app. This document covers some of the ways you can improve security in your app. ## Meta Crawler A number of platform services such as Social Plugins and Open Graph require our systems to be able to reach your web pages. We recognize that there are situations where you might not want these pages on the public web, during testing or for other security reasons. We've provided information on IP allow lists and User Agent strings for Meta's crawlers in our [Meta Crawler guide](https://developers.facebook.com/docs/sharing/webmasters/crawler). ## Login Security There are a large number of settings you can change to improve the security of your app. Please see our [Login Security](https://developers.facebook.com/docs/facebook-login/security/) documentation for a checklist of things you can do. It's also worth looking at our [access token](https://developers.facebook.com/docs/facebook-login/access-tokens/) documentation which covers various architectures and the security trade-offs that you should consider. ## Server Allow List We also enable you to restrict some of your API calls to come from a list of servers that you have allowed to make calls. Learn more in our [login security](https://developers.facebook.com/docs/facebook-login/security#surfacearea) documentation. ## Social Plugin Confirmation Steps In order to protect users from unintentionally liking content around the web, our systems will occasionally require them to confirm that they intended to interact with one of our Social Plugins via a "confirm" dialog. This is expected behavior and once the system has verified your site as a good actor, the step will be removed automatically. ## Encryption When connecting to our servers your client must use TLS and be able to verify a certificate signed using [`sha256WithRSAEncryption`](http://www.alvestrand.no/objectid/1.2.840.113549.1.1.11.html?fbclid=IwZXh0bgNhZW0CMTEAYnJpZBExdDFTU2F3MEdKRXZxdWxzRXNydGMGYXBwX2lkATAAAR7xe6pEpx2GwPP7Y5zC1ZXuoYaDMF_8qihLVtsAwoH5vbGKn0Ec6Vvr-yD4GQ_aem_GtcVeR9pdhmcc2D7qLsyaQ). Graph API supports TLS 1.2 and 1.3 and non-static RSA cipher suites. We are currently deprecating support for older TLS versions and static RSA cipher suites. Version 16.0 no longer supports TLS versions older than 1.1 or static RSA cipher suites. This change will apply to all API versions on May 3, 2023. ## Verify Graph API Calls with `appsecret_proof` Access tokens are portable. It's possible to take an access token generated on a client by Meta's SDK, send it to a server and then make calls from that server on behalf of the client. An access token can also be stolen by malicious software on a person's computer or a man in the middle attack. Then that access token can be used from an entirely different system that's not the client and not your server, generating spam or stealing data. Calls from a server can be better secured by adding a parameter called `appsecret_proof`. The app secret proof is a sha256 hash of your access token, using your app secret as the key. The app secret can be found in your app dashboard in **Settings > Basic**. If you're using the official PHP SDK, the `appsecret_proof` parameter is automatically added. ### Generate the Proof The following code example is what the call looks like in PHP: ``` $appsecret_proof= hash_hmac('sha256', $access_token, $app_secret); ``` ### Add the Proof You add the result as an `appsecret_proof` parameter to each call you make: ``` curl \ -F 'access_token=' \ -F 'appsecret_proof=' \ -F 'batch=[{"method":"GET", "relative_url":"me"},{"method":"GET", "relative_url":"me/friends?limit=50"}]' \ https://graph.facebook.com ``` ### Require the Proof To enable **Require App Secret** for all your API calls, go to the Meta App Dashboard and click **App Settings > Advanced** in the left side menu. Scroll to the **Security** section, and click the **Require App Secret** toggle. If this setting is enabled, all client-initiated calls must be proxied through your backend where the `appsecret_proof` parameter can be added to the request before sending it to the Graph API, or the call will fail. --- # The Facebook SDKs Source: https://developers.facebook.com/docs/graph-api/guides/our-sdks Mirror: https://nermalcat69.github.io/meta-developer-docs/docs/graph-api/guides/our-sdks.html # The Facebook SDKs Facebook SDKs have built-in methods and objects to get data in and out of the Meta social graph. ## Available SDKs * [Meta Business SDK](https://developers.facebook.com/docs/business-sdk) * [Facebook SDK for Android](https://developers.facebook.com/docs/android) * [Facebook SDK for iOS](https://developers.facebook.com/docs/ios) * [Facebook SDK for JavaScript](https://developers.facebook.com/docs/javascript) * [Facebook SDK for PHP](https://github.com/facebookarchive/php-graph-sdk) * [Facebook SDK for tvOS](https://developers.facebook.com/docs/tvos) * [Facebook SDK for Unity](https://developers.facebook.com/docs/unity) --- # Upgrade to the Latest Graph API Version Source: https://developers.facebook.com/docs/graph-api/advanced/api-upgrade Mirror: https://nermalcat69.github.io/meta-developer-docs/docs/graph-api/advanced/api-upgrade.html # Upgrade to the Latest Graph API Version This guide describes how to prepare your app to test different versions of the Graph API and to upgrade to the latest version. The [API Upgrade Tool](https://developers.facebook.com/tools/api_versioning/) shows the API calls from your app that may be affected by changes in newer versions of the API. You will be able to quickly see which changes you need to make to upgrade from your current version to a newer version. ## Learn How a Change Affects Your App The API Upgrade Tool displays a customized list of changes that impact an app when upgrading to a specified target version. This allows you to view all relevant changes between the source and target versions. Step 1. In the [Upgrade tool](https://developers.facebook.com/tools/api_versioning/), select your app from the dropdown menu or type in the name of the app. The dropdown menu only lists up to ten apps. To view more apps than those listed, use the search bar in the dropdown menu. Step 2. Use the dropdown menus to the right to select the version you would like to **Upgrade from** and the version you would like to **Upgrade to**. ### Read the Results The tool displays the number of changes that need to be made to update your app to the selected version. If your app makes API calls that will not be affected by a newer version no data will be returned. Methods are color coded by the version affecting the call. Hover over the bar chart to see how many changes are in each version. The dates associated with each version are when the changes will be enforced for all apps. The table shows the type of change (deprecation, new feature or change), which methods are affected, the number of calls made in the last 7 days, and the percentage of API calls affected by that specific change. ### Limitations * You must be an admin or developer of the app to view the app in the tool. * No data will be returned if your app has not made any, or too few, API calls from the **Update from** version. * Call volumes may appear incorrect. API call logging is sampled and aggregated over the previous week. It is compared with the call volume to estimate how many of your calls could be affected by a given version change. **Note:** Not all changes may affect each API call. Use your best judgment on whether a particular change needs to be handled by your app. Be sure to test your API calls in the newer version to ensure it works properly. ## Implement a New Version In the App Dashboard **Settings > Advanced**, scroll to the **Upgrade API Version** section. #### Upgrading Developers and Admins This upgrades all developers and admins of an app to the next available version. This allows you to test changes with a small subset of real users before releasing the new version to the public. #### Upgrading All Calls This upgrades all calls made by an app to the next available version. Upgrading early is useful since it preserves the option of going back to the original version in case of unforeseen bugs or issues. ## Learn More * [Graph API Changelog](https://developers.facebook.com/docs/graph-api/changelog) – Learn about the latest version changes. * [Versioning](https://developers.facebook.com/docs/graph-api/guides/versioning) – Learn all about Graph API versioning, requests to different versions, and more. * [Test Apps](https://developers.facebook.com/docs/development/build-and-test/test-apps) – Learn how to create test apps to test changes to your app before public release. * [Test Users](https://developers.facebook.com/docs/development/build-and-test/test-users) – Learn how to create test users to test changes to your app before public release. --- # Webhooks from Meta Source: https://developers.facebook.com/docs/graph-api/webhooks Mirror: https://nermalcat69.github.io/meta-developer-docs/docs/graph-api/webhooks.html # Webhooks from Meta Webhooks allows you to receive real-time HTTP notifications of changes to specific objects in the Meta social graph. For example, we could send you a notification when any of your app Users change their email address or whenever they comment on your Facebook Page. This prevents you from having to query the Graph API for changes to objects that may or may not have happened, and helps you avoid reaching your [rate limit](https://developers.facebook.com/docs/graph-api/advanced/rate-limiting). [Webhooks for Payments](https://developers.facebook.com/docs/games_payments/webhooks) and [Webhooks for Messenger](https://developers.facebook.com/docs/messenger-platform/webhook) have slightly differently configuration steps. If you are setting up a Webhook for either of these products, please refer to their respective documents for setup instructions. ## Objects, Fields, and Values There are many types of objects in the Meta social graph, such as User objects and Page objects, so whenever you configure a Webhook you must first **choose an object** type. Since different objects have different fields, you must then **subscribe to specific fields** for that object type. Whenever there's a **change to the value** of any object field you have subscribed to, we'll send you a notification. Notifications are sent to you as HTTP POST requests and contain a JSON payload that describes the change. For example, let's say you set up a `User` Webhook and subscribed to the `Photos` field. If one of your app's Users uploads a photo, we'd send you a notification that would look like this: #### Sample Notification ``` { "entry": [ { "time": 1520383571, "changes": [ { "field": "photos", "value": { "verb": "update", "object_id": "10211885744794461" } } ], "id": "10210299214172187", "uid": "10210299214172187" } ], "object": "user" } ``` ## HTTPS Server Webhooks are sent using HTTPS, so your server must must be able to receive and process HTTPS requests, and it must have a valid TLS/SSL certificate installed. Self-signed certificates are not supported. ## App Review Webhooks does not require [App Review](https://developers.facebook.com/docs/apps/review/). However, in order to receive Webhooks notifications of changes to objects when your app is in Live mode, your app must have been granted relevant permissions to access those objects. See [Permissions](https://developers.facebook.com/docs/graph-api/webhooks/#permissions) below. ## Permissions Before an app can be made public, it typically must go through App Review. During review, apps can request approval for specific permissions, which control the types of data the app can access when using the Graph API. Although the Webhooks product does not require App Review, it does respect permissions. This means that even if you set up a Webhook and subscribe to specific fields on an object type, you won't receive notifications of any changes to an object of that type unless: * your app has been approved for the permission(s) that corresponds to that type of data, and * the object that owns the data has granted your app permission to access that data (e.g., a User allowing your app to access their Feed) ## Development Mode Apps in [development mode](https://developers.facebook.com/docs/apps#development-mode) can only receive test notifications initiated through the app dashboard or notifications initiated by people who have a role on the app. Note that development mode behavior is different for Messenger Webhooks Events. Refer to the [Webhooks for Messenger](https://developers.facebook.com/docs/messenger-platform/webhook#development-mode) document for details. ## Setup To use Webhooks, you will need to set up an endpoint on a secure (HTTPS) server, then add and configure the Webhooks product in your app's dashboard. The rest of these documents explain how to complete both of these steps. Ready? [Let's get started!](https://developers.facebook.com/docs/graph-api/webhooks/getting-started) ## Learn More * Learn how to get notifications when a conversation is passed from one app to another using the [Messenger Handover Protocol](https://developers.facebook.com/docs/messenger-platform/handover-protocol/#subscribe-to-webhook-events). --- # Meta Developer Documentation Source: https://developers.facebook.com/docs Mirror: https://nermalcat69.github.io/meta-developer-docs/docs.html # Meta Developer Documentation *[Learn the basics of how to send and receive data from the Meta social graph](https://developers.facebook.com/docs/graph-api/overview) and how to implement the APIs, Platforms, Products, and SDKs to fit your application needs.* ## Meta App Development Register as a developer, configure your app's settings in the App Dashboard, and build, test, and release your app. [Docs](https://developers.facebook.com/documentation/development) ## Graph API The primary way for apps to read and write to the Meta social graph. [Docs](https://developers.facebook.com/docs/graph-api) ## Rest API Modern, flexible, and developer-friendly way to build and integrate with Meta's diverse platforms. [Docs](https://developers.facebook.com/documentation/rest-api/overview) ## Responsible Platform Initiatives Verify that your app uses our products and APIs in an approved manner. [Docs](https://developers.facebook.com/documentation/resp-plat-initiatives) ## MCP Connect AI agents to Meta MCP servers [Docs](https://developers.facebook.com/documentation/mcp) ## App Integrations [App Links](https://developers.facebook.com/documentation/applinks)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/applinks) [Graph API](https://developers.facebook.com/docs/graph-api/)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/docs/graph-api/) [Meta App Events](https://developers.facebook.com/documentation/app-events)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/app-events) [Meta Pixel](https://developers.facebook.com/documentation/meta-pixel)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/meta-pixel) [Webhooks](https://developers.facebook.com/docs/graph-api/webhooks/)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/docs/graph-api/webhooks/) ## Authentication [Facebook Login](https://developers.facebook.com/documentation/facebook-login)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/facebook-login) [Limited Facebook Login](https://developers.facebook.com/documentation/facebook-login/ios/limited-login)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/facebook-login/ios/limited-login) [Login Connect with Messenger](https://developers.facebook.com/documentation/facebook-login/login-connect)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/facebook-login/login-connect) ## Developer Guides [Meta App Development](https://developers.facebook.com/documentation/development)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/development) [Developer Policies](https://developers.facebook.com/devpolicy)[![](https://static.xx.fbcdn.net/rsrc.php/ym/r/73VAuIAF34q.webp)](https://developers.facebook.com/devpolicy) [Meta Platform Terms](https://developers.facebook.com/terms)[![](https://static.xx.fbcdn.net/rsrc.php/ym/r/73VAuIAF34q.webp)](https://developers.facebook.com/terms) [Privacy & Consent](https://developers.facebook.com/docs/privacy)[![](https://static.xx.fbcdn.net/rsrc.php/ym/r/73VAuIAF34q.webp)](https://developers.facebook.com/docs/privacy) [Financial Ads Licensing](https://developers.facebook.com/docs/license)[![](https://static.xx.fbcdn.net/rsrc.php/ym/r/73VAuIAF34q.webp)](https://developers.facebook.com/docs/license) ## SDKs [Facebook SDK for Android](https://developers.facebook.com/documentation/android)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/android) [Facebook SDK for iOS](https://developers.facebook.com/documentation/ios)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/ios) [Facebook SDK for JavaScript](https://developers.facebook.com/documentation/javascript)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/javascript) [Facebook SDK for PHP](https://github.com/facebookarchive/php-graph-sdk/tree/master/docs)[![](https://static.xx.fbcdn.net/rsrc.php/ym/r/73VAuIAF34q.webp)](https://github.com/facebookarchive/php-graph-sdk/tree/master/docs) [Unity SDK](https://developers.facebook.com/documentation/unity)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/unity) [Meta Business SDK](https://developers.facebook.com/documentation/business-sdk)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/business-sdk) ## Gaming [Instant Games](https://developers.facebook.com/documentation/games)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/games) ## Social Integrations [Facebook Pages API](https://developers.facebook.com/documentation/pages-api)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/pages-api) [Instagram Platform](https://developers.facebook.com/documentation/instagram-platform)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/instagram-platform) [Threads API](https://developers.facebook.com/documentation/threads)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/threads) [Sharing](https://developers.facebook.com/documentation/sharing)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/sharing) [Social Plugins](https://developers.facebook.com/documentation/plugins)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/plugins) ## Videos [Live Video API](https://developers.facebook.com/documentation/live-video-api)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/live-video-api) [Stories](https://developers.facebook.com/documentation/video-api/page-stories-api)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/video-api/page-stories-api) ## Business Messaging [Instagram Messaging](https://developers.facebook.com/documentation/business-messaging/instagram-messaging)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/business-messaging/instagram-messaging) [Messenger Platform](https://developers.facebook.com/documentation/business-messaging/messenger-platform)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/business-messaging/messenger-platform) [WhatsApp Business Platform](https://developers.facebook.com/documentation/business-messaging/whatsapp/overview)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/business-messaging/whatsapp/overview) [WhatsApp Flows](https://developers.facebook.com/documentation/business-messaging/whatsapp/flows)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/business-messaging/whatsapp/flows) ## Marketing and Commerce [Facebook Creator Discovery API](https://developers.facebook.com/documentation/fb-creator-discovery)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/fb-creator-discovery) [Facebook App Ads](https://developers.facebook.com/documentation/app-ads)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/app-ads) [Automotive Ads](https://developers.facebook.com/documentation/ads-commerce/marketing-api/auto-ads)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/ads-commerce/marketing-api/auto-ads) [Catalog](https://developers.facebook.com/documentation/ads-commerce/catalog)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/ads-commerce/catalog) [Commerce Platform](https://developers.facebook.com/documentation/ads-commerce/commerce-platform)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/ads-commerce/commerce-platform) [Conversions API](https://developers.facebook.com/documentation/ads-commerce/conversions-api)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/ads-commerce/conversions-api) [Conversions API Gateway](https://developers.facebook.com/documentation/ads-commerce/gateway-products/conversions-api-gateway)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/ads-commerce/gateway-products/conversions-api-gateway) [Signals Gateway](https://developers.facebook.com/documentation/ads-commerce/gateway-products/signals-gateway)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/ads-commerce/gateway-products/signals-gateway) [Cross-Channel Conversion Optimization](https://developers.facebook.com/documentation/ads-commerce/ccco) [![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/ads-commerce/ccco) [Meta Audience Network](https://developers.facebook.com/documentation/audience-network)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/audience-network) [Meta Business SDK](https://developers.facebook.com/documentation/business-sdk)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/business-sdk) [Marketing API](https://developers.facebook.com/documentation/ads-commerce/marketing-api)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/ads-commerce/marketing-api) ## Work and Education [Meta Admin Center](https://developers.facebook.com/documentation/admin-center)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/admin-center) ## Artificial Intelligence [Wit.ai](https://www.wit.ai/)[![](https://static.xx.fbcdn.net/rsrc.php/ym/r/73VAuIAF34q.webp)](https://www.wit.ai/) ## Data Portability [Data Portability](https://developers.facebook.com/documentation/data-portability)[![](https://static.xx.fbcdn.net/rsrc.php/yE/r/-E5IQbEIBnh.svg)](https://developers.facebook.com/documentation/data-portability) --- # Meta Admin Center Source: https://developers.facebook.com/documentation/admin-center Mirror: https://nermalcat69.github.io/meta-developer-docs/documentation/admin-center.html # Meta Admin Center Updated: Aug 20, 2025 ## Overview Meta Admin Center enables organizations to create and manage Meta accounts for people in their organization to access Meta products. With managed Meta accounts, organizations have more control over the security of their employees' accounts. Businesses will be able to manage Meta accounts on behalf of their employees and have access to enterprise-grade features like single sign-on integrations. The information provided on this site is technical in nature and is only intended for use by developers for the purpose of understanding or building integrations. Audiences seeking information on the client features or IT guidance should see the Help Center for further information. [Learn more about Admin Center](https://work.meta.com/help?fbclid=IwZXh0bgNhZW0CMTAAYnJpZBExdDFTU2F3MEdKRXZxdWxzRXNydGMGYXBwX2lkEDIyMjAzOTE3ODgyMDA4OTIAAR5bnDS1mTbpWIdnZ30RaGy2QolqLnNTVA8Qb7O7UCnNa267XvskrBudQ0vZ7w_aem_Se4rEmh53TDOFhzcDBZRjA)[Log in to Admin Center](https://work.meta.com/?fbclid=IwZXh0bgNhZW0CMTAAYnJpZBExdDFTU2F3MEdKRXZxdWxzRXNydGMGYXBwX2lkEDIyMjAzOTE3ODgyMDA4OTIAAR5-j7A8Ha0zktfC2Owvt1C2qv0jNAoLi-nj2RzQD35CV7LGAuVM_ggU-mzymA_aem_biPgCpetI_XTHqfdiRAIaw) ## Integrating with Admin Center Learn about building integrations for Admin Center. This site provides documentation to help developers create custom integrations for their organizations. All integrations built for Admin Center must be compliant with [Meta Platform Terms](https://developers.facebook.com/terms/dfc_platform_terms/). ## Platform features ### [Account management API](https://developers.facebook.com/documentation/admin-center/api-reference/account-management-api) Admin Center offers support for managing Meta accounts via REST-based account manamement APIs which are compliant with the open [SCIM 2.0⁠](https://scim.cloud/?fbclid=IwZXh0bgNhZW0CMTAAYnJpZBExdDFTU2F3MEdKRXZxdWxzRXNydGMGYXBwX2lkEDIyMjAzOTE3ODgyMDA4OTIAAR7DtZPSFpLR-t7QXjYVrNI4Su8n7HClpLoY91xin1TKYl62N32vBVg_L1PhsA_aem_IfFuNAdsGVbgxZTBMcfbpQ) protocol. ### [Security audit logs API](https://developers.facebook.com/documentation/admin-center/api-reference/security-log-api) Admin Center offers support for auditing security events relating to managed Meta accounts, via a REST-based API. ## Learn more ### [Permissions & access tokens](https://developers.facebook.com/documentation/admin-center/permissions-access-tokens) This guide will help you make API calls for your own organization via a custom integration on Admin Center. ### [API reference](https://developers.facebook.com/documentation/admin-center/api-reference) Learn about the APIs available to integrations on Admin Center, including SCIM-based account management APIs and security log APIs. ## Sample Apps Get started with a collection of samples containing examples of Graph API usage and integration samples for Meta Admin Center [Meta Admin Center Sample Apps on GitHub](https://github.com/fbsamples/meta-admin-center-integrations?fbclid=IwZXh0bgNhZW0CMTAAYnJpZBExdDFTU2F3MEdKRXZxdWxzRXNydGMGYXBwX2lkEDIyMjAzOTE3ODgyMDA4OTIAAR5j8frSpQRECN8NtqCpR-8UgDfs72252J0rv7987pywdaNWALDy05nDtWGl2g_aem_MX3iBWAzEDFjUnguW9f_8A) --- # 2: Getting Started With the CRM Integration Source: https://developers.facebook.com/documentation/ads-commerce/conversions-api/conversion-leads-integration/crm-integration/3-implementing-the-crm-integration Mirror: https://nermalcat69.github.io/meta-developer-docs/documentation/ads-commerce/conversions-api/conversion-leads-integration/crm-integration/3-implementing-the-crm-integration.html # 2: Getting Started With the CRM Integration Updated: Feb 6, 2026 This guide covers: * [Creating a new Lead Ads campaign](https://developers.facebook.com/documentation/ads-commerce/conversions-api/conversion-leads-integration/crm-integration/3-implementing-the-crm-integration#step-1-create-a-lead-ads-campaign-optional) * [Creating a new Meta CRM Pixel or converting an existing Pixel](https://developers.facebook.com/documentation/ads-commerce/conversions-api/conversion-leads-integration/crm-integration/3-implementing-the-crm-integration#step-2-create-a-meta-crm-pixel) * [Choosing an integration method](https://developers.facebook.com/documentation/ads-commerce/conversions-api/conversion-leads-integration/crm-integration/3-implementing-the-crm-integration#step-3-choose-an-integration-method) ## Step 1: Create a Lead Ads campaign (optional) This section is optional if you already have existing Lead Ads campaigns. Note that the optimization goal cannot be changed on published campaigns, but you can duplicate existing campaigns, then change the optimization goal. * Log into your business [Ads Manager⁠](https://www.facebook.com/adsmanager/manage/campaigns) account. (Conversion Leads performance goal is not available through personal ad accounts nor through Lightweight Interfaces.) * Click the **+ Create** button to create a new campaign. Under the **Choose a Campaign Objective** window, choose **Leads**, and click **Continue**. * In the ad set level settings, within the **Conversion location**, select **Instant forms**. * Under **Optimization and delivery** for the ad set, click on the **Edit** button for **Optimization for ad delivery** and choose the **Conversion Leads** goal in the drop-down. The Conversions API for CRM integration is not a requirement to begin running campaigns with the Conversion Leads performance goal, however you will see better results if it is fully integrated. ## Step 2: Create a Meta CRM dataset This section will walk you through creating a Meta Pixel for your CRM. **Note:** You will need to have admin access to create or convert a Pixel. * In [Events Manager⁠](https://www.facebook.com/events_manager2/list), click **Connect Data Sources** to connect a new data source. * Select **CRM**, then click **Connect**. * You may either create a completely new dataset or convert an existing dataset. Your decision will depend on how you want to organize your events and manage ad account access to the datasets. Create a new dataset so the CRM events do not overlap with existing dataset events in Events Manager, which will make troubleshooting easier. If you convert an existing dataset, give the CRM events a different name rather than reusing existing event names, which could cause confusion between the different types of events. Converting an existing web dataset will not affect other events uploaded to it. A CRM dataset lets Meta know that CRM events will be uploaded to it and adds the Conversion Leads Optimization integration workflow to the dataset. * **To create a new dataset:** Click on the **Create New Dataset** link, and name the dataset accordingly. * **To convert a dataset:** Select the existing dataset you would like to upload CRM events into. Converting an existing web dataset will not affect other events being uploaded to it. * Double check that the icon for your CRM dataset has updated. If it did not, repeat this step. **Note:** The integration is Pixel-based. Do not switch completed integrations to a different Pixel. ![Events Manager left navigation with 'Connect Data Sources' option highlighted](https://scontent.fdel27-2.fna.fbcdn.net/v/t39.2365-6/651743471_1459945359197447_364062364092200302_n.png?_nc_cat=111&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=e280be&_nc_ohc=ToY1QZUEMJoQ7kNvwEI8UpF&_nc_oc=AdpXU1Z7k-Xm_Bk8N_uoF408MnXpi1_OTNRCLCM2sMfMpU7v-lr7MpCEHUScnChdmNmps7uh4VUogyQkWfnq6HZI&_nc_zt=14&_nc_ht=scontent.fdel27-2.fna&_nc_gid=wRKQpRFtsRwQQgoEL2T-iA&_nc_ss=7b289&oh=00_AQARGUYMfr_tjOL6XUbPbKYqG0chkfVsCmqa9oxc5pupgQ&oe=6A607462) ![Connect a new data source dialog with the CRM data source type selected](https://scontent.fdel27-7.fna.fbcdn.net/v/t39.2365-6/653050255_1459945212530795_4102635663282177987_n.png?_nc_cat=111&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=e280be&_nc_ohc=dQY2hLZAaxYQ7kNvwFo94wv&_nc_oc=AdqlGBV1HrlrqB-kSTBGSVRRjYV_-8-FsBwODSRVElagGaBuS1G2hQ0FQLqt19Bds9l9Dq06CXxxqB9JuNH25xxx&_nc_zt=14&_nc_ht=scontent.fdel27-7.fna&_nc_gid=wRKQpRFtsRwQQgoEL2T-iA&_nc_ss=7b289&oh=00_AQAcuMrsTyVdNwA59RyrE2L5lG9U5UjfGWl3QJNvo1oCtA&oe=6A606A1E) ## Step 3: Choose an integration method You will have a choice to complete the set up using the manual integration or a partner integration. A manual integration is a great choice for businesses that have developer resources available, access to their server codebase, and need the ability to customize their configuration. Alternatively, businesses that need a simpler CRM integration may use one of the available partner integrations. * Enter your CRM in the search box. * If your CRM is supported by a partner integration you can choose the **Use a partner** option and follow the directions in that workflow. * Select your preferred partner. * Click **Open instructions** for the respective partner to get directions for that workflow. * Click **Go to partner** to proceed to the partner and begin the integration. ![Select a partner tab showing Zapier as a recommended CRM connection](https://scontent.fdel27-2.fna.fbcdn.net/v/t39.2365-6/652294570_1459945185864131_8265866300993431409_n.png?_nc_cat=101&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=e280be&_nc_ohc=MfpKeJV6mhQQ7kNvwHO98gr&_nc_oc=Adp9G-t5Ot5_yK_W_KHxujhrsQ47nX7egrp2b3ne9uk5r1b517Ux8joR1dG5p9e9YE904tsVEJZiOm2QgyC0YjMe&_nc_zt=14&_nc_ht=scontent.fdel27-2.fna&_nc_gid=wRKQpRFtsRwQQgoEL2T-iA&_nc_ss=7b289&oh=00_AQCNmxKw8omCa7gt8ds0S-BCB6H95v_L_Fh-2Dka0BYCzQ&oe=6A60900F) * Otherwise, proceed by choosing the **Manual code** option or the **Invite a developer** option, and click **Continue**.**Note:** You will need Business Manager admin access to complete the integration. --- # 3: Developer Implementation Source: https://developers.facebook.com/documentation/ads-commerce/conversions-api/conversion-leads-integration/zapier Mirror: https://nermalcat69.github.io/meta-developer-docs/documentation/ads-commerce/conversions-api/conversion-leads-integration/zapier.html # 3: Developer Implementation Updated: Jun 28, 2026 This page deals with the manual integration and covers: * [Building the payload for CRM integration](https://developers.facebook.com/documentation/ads-commerce/conversions-api/conversion-leads-integration/zapier#step-1-build-a-payload) * [Generating an access token and preparing an API call](https://developers.facebook.com/documentation/ads-commerce/conversions-api/conversion-leads-integration/zapier#step-2-create-an-access-token-and-an-api-call) * [Sending a test payload](https://developers.facebook.com/documentation/ads-commerce/conversions-api/conversion-leads-integration/zapier#step-3-test-a-payload-optional) * [Sending production data](https://developers.facebook.com/documentation/ads-commerce/conversions-api/conversion-leads-integration/zapier#step-4-send-production-data) This section is only applicable if you decide to complete this integration using a manual integration and developer resources. If you instead decide to complete this integration using a partner, follow the respective partner instructions for the integration. You can skip to [4: Verify your data](https://developers.facebook.com/documentation/ads-commerce/conversions-api/conversion-leads-integration/crm-integration/4-verify-your-data) section of this guide once the partner integration is complete. You will need Meta Business Suite admin access to complete these integration steps. You may acquire access from the email sent to you if you were invited as a developer. Otherwise, contact a Meta Business Suite admin to request access. ## Step 1: Build a payload This step will lay out the payload specifications for the Conversions API for CRM integration and provide some recommendations on how to send it from your server. * Open the CRM integration guide from the **Settings** tab of your CRM Pixel to get started. * Review the [Conversions API Developers Guide](https://developers.facebook.com/documentation/ads-commerce/conversions-api/using-the-api) to gain an understanding of how the Conversions API functions. * Meta recommends using the [Payload Helper](https://developers.facebook.com/documentation/ads-commerce/conversions-api/payload-helper?data=[%7B%22event_name%22%3A%22Lead%22%2C%22event_time%22%3A1664577963%2C%22action_source%22%3A%22system_generated%22%2C%22user_data%22%3A%7B%22lead_id%22%3A1234567890123456%7D%2C%22custom_data%22%3A%7B%22lead_event_source%22%3A%22Your%20CRM%22%2C%22event_source%22%3A%22crm%22%7D%7D]&selectedProduct=Conversion%20Leads) to build your payload. The Payload Helper will format your payload and check for errors. Once all payload errors are resolved, click the **Get Code** button inside the Payload Helper to generate a code template for your programming language. * Here is the list of required parameters. Review the [Conversion Leads Integration - Payload Specification guide](https://developers.facebook.com/documentation/ads-commerce/conversions-api/conversion-leads-integration/payload-specification) to see the full description for each parameter. **This payload specification should only be used for Conversion Leads Optimization events.** This means the events should only pertain to Meta lead ads. Refrain from using this payload specification for other event types, such as website leads. **Required Parameters** | Name | Description | | --- | --- | | `event_name` string | Free-form field to capture the lead stages you use within your CRM. The `event_name` parameter should indicate a lead moving through the sales funnel in your CRM. **Make sure to send all stages as they are updated, including the raw lead.** | | `event_time` integer | A Unix timestamp in seconds indicating when the lead stage update event is updated by your CRM. The timestamp must occur after the lead generation time or else the event may be discarded. | | `action_source` string | **Value:** `system_generated` (By using the Conversions API, you agree that the [`action_source`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#action-source) parameter is accurate to the best of your knowledge.) | | `user_data` object | A map that contains customer information data. See [Customer Information Parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters) for options. See [Advanced Matching](https://developers.facebook.com/docs/meta-pixel/advanced/advanced-matching) for comparable options available for data sent via Meta Pixel. | | `lead_event_source` string | The name of the CRM where the events are coming from. | | `event_source` string | **Value:** `crm` | **Customer Information Parameters** Customer information helps Meta match events from your server with Meta accounts. Sending as many of the following parameters can lead to more accurate event data and better ad performance. **Note**: You must send at least one customer information parameter. If sending `lead_id`, please use a valid `lead_id` or else the system will reject the event. If you choose to send email, phone number, these have to be hashed. Click ID currently does not have API rejection level error, but a large volume of invalid `click_id` will cause an alert in the system. | Parameter | Priority | Description | | --- | --- | --- | | Lead ID (recommended) [How to find the lead ID?](https://developers.facebook.com/documentation/ads-commerce/conversions-api/conversion-leads-integration/how-to-find-the-lead-id) | Highest | The Facebook generated ID for every lead. It is a 15-17 digit number obtained from the `leadgen_id` [field in the lead generation Webhook](https://developers.facebook.com/documentation/ads-commerce/marketing-api/guides/lead-ads/retrieving#webhook-response) and included under the `user_data` parameter. Refer to [Find the Lead ID](https://developers.facebook.com/documentation/ads-commerce/conversions-api/conversion-leads-integration/how-to-find-the-lead-id) for more information. | | Click ID | Highest | | | Hashed email | Highest | | | Hashed phone number | High | | | Other hashed Contact Information | Medium | | **Note**: In addition to a hashed email and phone number, you can send hashed gender, date of birth, last name, first name, city, state, zip, and more to Meta. **Example** An example payload may look like this. ``` { "data": [ { "event_name": "Lead", "event_time": 1664577963, "action_source": "system_generated", "user_data": { "lead_id": 1234567890123456, "em": [ "973dfe463ec85785f5f95af5ba3906eedb2d931c24e69824a89ea65dba4e813b" ], "ph": [ "74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b" ] }, "custom_data": { "lead_event_source": "Your CRM", "event_source": "crm" } } ] } ``` * If events do not follow the payload specification or do not match a Meta lead ad, then they will not be recognized for the integration and will not be used for training the model. For example the Web payload would be accepted by the Conversions API and appear in Events Manager, but it will **not** be recognized for this integration. You must also use a valid `lead_id` or else the system will reject your event. **Note:** You must send at least one customer information parameter. If sending `lead_id`, please use valid `lead_id` or else the system will reject the event. If you choose to send email, phone number, these have to be hashed. Click ID currently does not have API rejection level error, but a large volume of invalid `click_id` will cause an alert in the system. Only the Conversion Leads payload will be recognized for the integration and used for training. ![Side-by-side JSON payloads: Web payload marked with a red X and Conversion Leads payload marked with a green check](https://scontent.fdel27-6.fna.fbcdn.net/v/t39.2365-6/306070973_798763977822397_5594494441058509130_n.png?_nc_cat=108&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=e280be&_nc_ohc=e89YSCaGO-oQ7kNvwEOVvlp&_nc_oc=Adptua7l2yJlJA8D0WCBYzmUkNkMTSwHq5tIgfvTAPdEu2GIKMeUnTNAQwXt9MKGz_ZayYKcuSD_lfTVVlkkvuYh&_nc_zt=14&_nc_ht=scontent.fdel27-6.fna&_nc_gid=wX0OIUn_dHEIq56bBYocMQ&_nc_ss=7b289&oh=00_AQAI6KkVVX8URxe_1KSs9_SE3boxC55QZLpkYFYV9bj0nw&oe=6A606C2A) ## Step 2: Create an access token and an API call Once you configure what you will send, the next step is to configure where you will send the data. This step will help you generate an access token for your Meta Pixel, which will then be used to establish a connection between your server and the Conversions API. * You can return to the CRM integration guide from the **Settings** tab of your CRM Pixel. * Scroll down to the **Create Endpoint** section and click the **Generate Access Token** button. The access token will be used to build your API call. You can generate a new access token by returning to the integration guide or from the **Settings** tab in [Events Manager⁠](https://www.facebook.com/events_manager2/list) by navigating to the **Conversions API** section and clicking the **Generate access token** link. * The rest of this guide will vary depending on whether you are using Meta's SDK. Using the [Meta Business SDK](https://developers.facebook.com/docs/business-sdk/overview) is recommended because they provide better error and diagnostic messaging. You will need your Pixel ID and access token to make the API call via the Meta Business SDK. You can get the access token by clicking **Copy access token** in the CRM integration guide and saving it. Examples of SDK API calls can be found in the [Conversion API Developers Guide](https://developers.facebook.com/documentation/ads-commerce/conversions-api/using-the-api#send) or the **Get Code** functionality within the Meta Payload Helper. * This is the endpoint format to make a `POST` request to the Conversions API without the SDK. You can get the entire endpoint by clicking **Copy endpoint** in the CRM Integration guide and saving it. ``` https://graph.facebook.com/API_VERSION/PIXEL_ID/events?access_token=ACCESS_TOKEN ``` * `API_VERSION`: The current Marketing API version * `PIXEL_ID`: The Pixel ID can be obtained from Events Manager for each Pixel * `ACCESS_TOKEN`: The access token generated above * You can see the Marketing API release and expiration dates in the [API Version documentation](https://developers.facebook.com/docs/graph-api/changelog/versions). Be sure to update the API version or the Meta Business SDK in your code before the Marketing API expiration date. Using a deprecated version in your code could result in errors and your events may be discarded by the system. ## Step 3: Test a payload (optional) At this point you may want to send a test payload to your Pixel before implementing the code on your server. You can do so by using the **Test Events** tab in [Events Manager⁠](https://www.facebook.com/events_manager2/list). * In the **Test Server Events** section, click on the **Graph API Explorer** link. Using this unique link will prefill some information from your Pixel. (You can also directly access the [Graph API Explorer](https://developers.facebook.com/tools/explorer) if you wish.) Take note of the `test_event_code` value, which can change over time. * Complete the following in the Graph API Explorer tool: * Ensure you are in `POST` mode. * Check that your API version and Pixel ID are correct. * Switch to the JSON view. * Input your payload. This can be manually created or generated using the [Payload Helper](https://developers.facebook.com/documentation/ads-commerce/conversions-api/payload-helper). Make sure to include the `test_event_code` parameter from the previous step and a valid `lead_id`. * Enter your Pixel access token, and click the **Submit** button. * If your payload does not contain any syntax or API errors, you should receive a success message with a `fbtrace_id`. * The test event should appear under the **Test Events** tab in Events Manager after a short time. ## Step 4: Send production data The production data should be in the same format as the payload generated in Step 3, except the data will be coming directly from your server. This step will vary for every integration so this section will provide guidelines rather than a walkthrough. * Send the `lead_id` (recommended) and additional customer information parameters that are listed above for matching. * Make sure to **send all lead stages** as they are updated, including the raw lead event that represents all leads generated on Meta and downloaded into your CRM. Below is an example funnel. The event names and stages are advertiser-defined so they do not have to conform to this example. ![Sales funnel of lead stages: Raw Lead 100, Marketing Qualified Lead 70, Sales Opportunity 30, Converted 15](https://scontent.fdel27-7.fna.fbcdn.net/v/t39.2365-6/652458913_1459945209197462_1743492340946420797_n.png?_nc_cat=101&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=e280be&_nc_ohc=MQop2_oUO7gQ7kNvwEWp4XE&_nc_oc=AdqTaLTWTboHQH-73flDwaoelCcHFkly_uH0OfV1zqopBVHxhemiuUC4kPlob6SESByZkTXulHP0zn5n05ofcEmk&_nc_zt=14&_nc_ht=scontent.fdel27-7.fna&_nc_gid=wX0OIUn_dHEIq56bBYocMQ&_nc_ss=7b289&oh=00_AQCQu-Or-tNZprRQPEJu1-brmaTMkc8oC9ZFYe7FWMSAuw&oe=6A607E85) If your campaigns generate 100 leads, then Meta expects 100 "Raw Lead" events uploaded to represent the first lead stage. Sending the first lead stage lets the system know that the lead was received and processed. As the leads move down the sales funnel, Meta expects 70 "Marketing Qualified Lead", 30 "Sales Opportunity", and 15 "Converted" stages to be uploaded. In this example scenario, 100 leads are generated from the campaigns, but Meta expects 215 events to be uploaded. * Create a function that retrieves updates from your CRM's API or database whenever the lead status updates. Then send your payload to Meta's Conversions API using a custom function or Meta's business SDK. What makes the most sense for your integration will depend on your CRM and database configuration. Variables are recommended for: * `lead_id` * `event_name` * `event_time`For example, a payload that explicitly states the parameter values may look like this: ``` { "event_name": "initial_lead", "event_time": 1628294742, "user_data": { "lead_id": 1234567890123456 }, "action_source": "system_generated", "custom_data:" { "lead_event_source": "Salesforce", "event_source": "crm" } } ``` A payload that passes in values from your database using variables may look like this: ``` { "event_name": lead_stage // "initial_lead" "event_time": unix_time // 1628294742 "user_data": { "lead_id": fb_lead_id // 1234567890123456 }, "action_source": "system_generated", "custom_data:" { "lead_event_source": "Salesforce", "event_source": "crm" } } ``` * Upload data at least once a day. Ideally the calls to your CRM should be made in real-time, but you may employ hourly or daily batching methods if a real-time integration is not feasible. If you choose the batching methods, make sure you capture the lead status change history rather than a snapshot of the lead at the time of batching. For example, if a lead's status updates 3 times between batches, Meta expects 3 events for this lead rather than just the final update. **Note:** Each batch can include up to 1,000 events. If there is an error in the batch, the whole batch will be discarded, so use smaller batches and add logic for retrying attempts. * **Optional**. Meta recommends logging error messages from the Conversions API call and creating alerts if there are issues. Add exception handling for these errors. * You can backfill your data for up to 7 days in the past. The time difference is calculated between `event_time` and `upload_time`. Backfilling some data may speed up the training process. WARNING: Do not attempt to backfill more than 7 days of data by modifying the `event_time` values. The model relies on an accurate time stamp to optimize. Doing so may cause all your backfilled data to be discarded. * Ensure that your `event_time` values are after the lead generation timestamp, otherwise your events may be discarded. * You should start seeing events appear in Events Manager for your Pixel within an hour if your integration is uploading events to Meta. Remember to use a valid `lead_id` in your payloads for events to appear. Open each event sent for the Conversion Leads CRM integration in Events Manager and check that they have the custom parameters `lead_event_source` and `event_source` populated. If the event does not have these parameters, it will not get registered as a Conversion Leads event. ![Events Manager Overview for CRM Integration Test Pixel with activity chart and server events list](https://scontent.fdel27-1.fna.fbcdn.net/v/t39.2365-6/653700531_1459945425864107_752080227303368398_n.png?_nc_cat=111&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=e280be&_nc_ohc=iDPOKXyAzVgQ7kNvwH6qCmT&_nc_oc=AdpRsVtme3JkV6a-2YGaWceshfh_DvDim3FfX9CA4QFEV0E_RKG3OlZVno7Qcfc_v7oSSQgdEwtgNvln4oM9pQLa&_nc_zt=14&_nc_ht=scontent.fdel27-1.fna&_nc_gid=wX0OIUn_dHEIq56bBYocMQ&_nc_ss=7b289&oh=00_AQC5sqXy8AJm8t9NOaqIJwi_A8EHUw-Bok031Pp16iymYA&oe=6A60958F) * The system will verify if any of your events are valid Conversion Leads events. After 1 day, a green check will appear next to the **Send a CRM event** step of the integration if a valid event is detected. --- # 3: Zapier Implementation Source: https://developers.facebook.com/documentation/ads-commerce/conversions-api/conversion-leads-integration/zapier/prerequisites Mirror: https://nermalcat69.github.io/meta-developer-docs/documentation/ads-commerce/conversions-api/conversion-leads-integration/zapier/prerequisites.html # 3: Zapier Implementation Updated: Jun 28, 2026 Use Zapier to integrate your CRM with Meta through the "Facebook Conversions" Zapier app. This removes the need for the developer resources that the manual integration requires. * [Prerequisites](https://developers.facebook.com/documentation/ads-commerce/conversions-api/conversion-leads-integration/zapier/prerequisites) * [Step 1: Implement Conversion Leads Integration](https://developers.facebook.com/documentation/ads-commerce/conversions-api/conversion-leads-integration/zapier/step-1-implement-integration) * [Step 2: Verify Your Integration](https://developers.facebook.com/documentation/ads-commerce/conversions-api/conversion-leads-integration/zapier/step-2-verify-integration) --- # 4: Verify Your Data Source: https://developers.facebook.com/documentation/ads-commerce/conversions-api/conversion-leads-integration/crm-integration/5-configure-your-sales-funnel Mirror: https://nermalcat69.github.io/meta-developer-docs/documentation/ads-commerce/conversions-api/conversion-leads-integration/crm-integration/5-configure-your-sales-funnel.html # 4: Verify Your Data Updated: Dec 8, 2025 There are two phases of data validation: * **Connect your CRM** phase * **Configure your sales funnel** phase ## Connect your CRM phase * After connecting to the Conversions API, refer to the Overview tab of your dataset in Meta Events Manager for integration status. ![CRM setup card showing 20% done with 'Connect your CRM' step active and a 'View reports' button](https://scontent.fdel1-1.fna.fbcdn.net/v/t39.2365-6/651239697_1459945285864121_4256073422128708592_n.png?_nc_cat=102&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=e280be&_nc_ohc=K8rcv9VOxDoQ7kNvwF66sfk&_nc_oc=AdouWYuA2W7Gf3o-kUG5yFYBISC5db_PJs91qFXLCwqKOFafneKRZFRIl91iEsPT7CLTVGgpSa8KEiygGVqYLLjY&_nc_zt=14&_nc_ht=scontent.fdel1-1.fna&_nc_gid=JcDyiPVp2dQm3JAUZswFMA&_nc_ss=7b289&oh=00_AQBtD_f-y602ghvIVGuB3VbNkSm-imsBxgpIqu0faBtrBQ&oe=6A608917) * Send at least one valid event from your integration. An event is valid when it has a proper payload, is sent through your CRM using the Conversions API, and can be attributed to a lead. ## Configure your sales funnel phase By configuring your funnel, you enable Meta to analyze and optimize your funnel's performance, ultimately driving better results for your lead campaigns. To achieve this, the data shared with Meta must meet some requirements. * After sending all events, refer to the Overview tab of your dataset in Events Manager for integration status. You will be able to configure your funnel. Configuring your funnel helps Meta understand the data sent and perform deep analysis based on the fulfilment of the data requirements. Please refer to the [Configure your sales funnel](https://developers.facebook.com/documentation/ads-commerce/conversions-api/conversion-leads-integration/crm-integration/5-configure-your-sales-funnel) document to learn more. ![CRM setup card at 50% done with 'Connect your CRM' marked 'Events firing properly' and 'Configure sales funnel' active](https://scontent.fdel1-9.fna.fbcdn.net/v/t39.2365-6/652869969_1459945299197453_301774844493082206_n.png?_nc_cat=106&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=e280be&_nc_ohc=pj7NleJ62bIQ7kNvwGpwEcS&_nc_oc=AdqGIYG9QOOtNHUL_FpJ8Dd61CJuTvmSNuEopPgVvbRCP7wlfmMjwJTtRUEevcq3hiaObeSVNFyTY3bdAzWXZbmK&_nc_zt=14&_nc_ht=scontent.fdel1-9.fna&_nc_gid=JcDyiPVp2dQm3JAUZswFMA&_nc_ss=7b289&oh=00_AQAgUDfR8_UdbbsCI-qWGrOqsr9Enn1sNApBI050sowQng&oe=6A607705) * The data sent to Meta must satisfy these requirements: * Maintain a running lead campaign generating 200 leads per month. * Your Lead Coverage is at least 60%. Lead Coverage is defined as the percentage of leads that have matching events uploaded to Meta. The best way to increase your Lead Coverage is to include the Meta Lead ID in your payload and upload the raw lead event that represents all leads generated on Meta and downloaded into your CRM. You may view your current Lead Coverage by clicking the **View Reports** button in the **Settings** tab of your CRM pixel. ![CRM setup at 100% done with event activity chart and a tooltip listing lead and lead coverage requirements](https://scontent.fdel1-2.fna.fbcdn.net/v/t39.2365-6/653700424_1459945275864122_7876196427228960078_n.png?_nc_cat=105&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=e280be&_nc_ohc=7AT7BdBKLr0Q7kNvwHRQ_yN&_nc_oc=AdoIgzKYZjUwb5n0RNCxWy6_VJkriKb3TX84tI8Q1NLADfzWfQstVxuXyZ0Ff4NGno5c29aWjvSZ9DGFStdWz68Y&_nc_zt=14&_nc_ht=scontent.fdel1-2.fna&_nc_gid=JcDyiPVp2dQm3JAUZswFMA&_nc_ss=7b289&oh=00_AQAwJIVH8pRf-h7fpUqFxwMVVf5z--BAoMSMQADQOllJug&oe=6A608B7E) * Data has all the required parameters and is in the correct format. Refer to the Payload Specification section for more details. **Note**: If the system detects any errors in your integration, you will see them in the **Settings** tab of your CRM pixel. You can also find errors listed in the **Diagnostics** tab along with instructions on how to fix them. --- # 5: Configure Your Sales Funnel Source: https://developers.facebook.com/documentation/ads-commerce/conversions-api/conversion-leads-integration/crm-integration/6-follow-up-steps Mirror: https://nermalcat69.github.io/meta-developer-docs/documentation/ads-commerce/conversions-api/conversion-leads-integration/crm-integration/6-follow-up-steps.html # 5: Configure Your Sales Funnel Updated: Dec 8, 2025 This guide will walk you through the sales funnel configuration, which will inform the system about your sales funnel and which lead stage to optimize on. You must have admin access to complete this section. **Step 1**. After connecting to the Conversions API, refer to the Overview tab of your dataset in Events Manager for integration status. A CRM integration widget will now display your integration status and provide guidance throughout the process, including notification when complete. ![Events Manager Overview tab showing CRM setup progress and Connect your CRM status](https://scontent.fdel1-8.fna.fbcdn.net/v/t39.2365-6/652145009_1459945335864116_8287952946838859308_n.png?_nc_cat=109&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=e280be&_nc_ohc=qi5DXmwYUocQ7kNvwGacOZb&_nc_oc=AdoGx3nVKtuOpg_bSU2pVU9nnNWOyUiN02rN0GQj5MRyKPisRzG2HmqMwdttw5e91jZpd09YZKNK2FghprsibkQl&_nc_zt=14&_nc_ht=scontent.fdel1-8.fna&_nc_gid=Bmh-9lEZVwf3p2qKwhgurg&_nc_ss=7b289&oh=00_AQBcQjcHOczW2ZG6X3uSAkVEPlV7Lao5cru_ocrZD26xIA&oe=6A6059CB) **Step 2**. When your CRM data passes verification checks, you can configure your sales funnel. **Step 3**. If you share an adequate number of event stages, Meta may use AI to generate a sales funnel for you. You can then review, edit, and confirm the stages to proceed. **Step 4**. Lead events shared from your CRM will show up as funnel stages in Events Manager. Remove events that don't belong and arrange the rest to reflect the order of your sales funnel, using two categories. * *Positive stages*: Events that signify a quality lead, for example, 'marketing qualified lead', 'add to cart'. * *Other stages*: Events that do not signify a quality lead, for example, test events or events accidentally uploaded from another system. * Remove events that indicate a negative lead or do not belong in your sales funnel by clicking the minus (-) button next to each event. These could be leads that received a phone call, but decided to not convert into a sale. ![Configure sales funnel stages screen with AI-generated Positive stages and Other stages lists](https://scontent.fdel1-1.fna.fbcdn.net/v/t39.2365-6/651760200_1459945259197457_5627207297032411192_n.png?_nc_cat=101&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=e280be&_nc_ohc=WfFZ9XZ3RDcQ7kNvwFxdcjr&_nc_oc=Adp-rpdLC0h4sBCSNYiJD-P30oEUxrE0UVW8xzUzf4HDvplM_9OjLkOQu5dth318eNRUMQ9DuNby9KUg1x-Rdl-c&_nc_zt=14&_nc_ht=scontent.fdel1-1.fna&_nc_gid=Bmh-9lEZVwf3p2qKwhgurg&_nc_ss=7b289&oh=00_AQA23MHhTv2UNkStNU3ejiAMySxhrbBZg66dggpNixJuJw&oe=6A606668) **Step 5**. In the same step, order your events to reflect the actual order of your sales funnel. **Step 6**. In the Optimization Target step, select the earliest lead stage you would like to optimize for. This does not need to be the last stage of the funnel. The system will optimize for all down-funnel stages as well. ![Optimization target step recommending which lead stages to optimize for, with conversion rate tips](https://scontent.fdel1-5.fna.fbcdn.net/v/t39.2365-6/651724485_1459945265864123_8522305889699719774_n.png?_nc_cat=111&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=e280be&_nc_ohc=VDYe5rzNqlsQ7kNvwEUDgfq&_nc_oc=AdovBDCW0p7mkd9GPse1q4OiM-eYN-ky3o9twKh3kbJK1SqqrIAbT6tHu4z9TPocLKdtYENjOVtS_b8UaPeiGvlP&_nc_zt=14&_nc_ht=scontent.fdel1-5.fna&_nc_gid=Bmh-9lEZVwf3p2qKwhgurg&_nc_ss=7b289&oh=00_AQCs79vvihOqgdKE1m4k9a63-jB7ZS6F0OYAPmQOmTHolQ&oe=6A606CC0) **Note**: The system may adjust and optimize for a different lead stage than the one selected if better performance can be achieved. --- # 6: Follow-up Steps Source: https://developers.facebook.com/documentation/ads-commerce/conversions-api/conversion-leads-integration/payload-specification Mirror: https://nermalcat69.github.io/meta-developer-docs/documentation/ads-commerce/conversions-api/conversion-leads-integration/payload-specification.html # 6: Follow-up Steps Updated: Dec 8, 2025 This guide covers: * [Allowing the system time to analyze and train on the data](https://developers.facebook.com/documentation/ads-commerce/conversions-api/conversion-leads-integration/payload-specification#funnel-analysis-and-learning-period) * [Sharing the Meta Pixel with your ad accounts](https://developers.facebook.com/documentation/ads-commerce/conversions-api/conversion-leads-integration/payload-specification#share-the-pixel-with-your-ad-accounts) ## Funnel analysis and learning period **Congratulations!** You have completed the main steps of the Conversions API for CRM integration and the next steps will be handled by the system. There is no more work on your end unless the system finds an issue with the data. Do not change pixels after this step. Changing pixels will start a new integration and restart the training process. ### Funnel analysis After the funnel configuration is complete, the system will analyze your data again to determine if it matches with your indicated funnel. The length of this process will depend on the length of your lead conversion window. If it normally takes 14 days for a lead to convert, then you need at least that many days of good data uploaded. Remember, your conversion event must occur within 28 days of lead generation and have a conversion rate between 1-40%. Check the diagnostics tab in Events Manager to find errors and instructions on how to fix them. Confirming that your data is fitting the requirements you just reviewed is a good place to start. ![Events Manager Diagnostics tab showing active CRM integration issue 'Lead coverage below threshold'](https://scontent.fdel1-2.fna.fbcdn.net/v/t39.2365-6/653706207_1459945339197449_671956088852579854_n.png?_nc_cat=106&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=e280be&_nc_ohc=npmktRTyC8QQ7kNvwGZkJ4i&_nc_oc=AdqggCQtjXCOndg_GYY4Ou6u0_m3jUOMd6MDQ6YYmK99XMnAwpCxxPUrQgYL7vk8ePHjYcecImZ73o0-mrWk8OXa&_nc_zt=14&_nc_ht=scontent.fdel1-2.fna&_nc_gid=8CoHmr2sH9T2Mmz8uevRlw&_nc_ss=7b289&oh=00_AQAw-Cu-GoS54yrZhNQwPuRamxd1M9QNF1f-RJdePdwcBg&oe=6A606F8B) ### Learning phase Once your integration is complete and passed the funnel analysis, there is a 2-4 week learning phase before the model finishes training with your data. You may enable the Conversion Leads optimization in the Optimization and Delivery menu of [Ads Manager⁠](https://www.facebook.com/adsmanager/manage/campaigns) during this period, but you may not see the full performance gains until after the training period. If you observe subpar performance with the Conversion Leads, it is recommended that you wait for the Learning phase to finish before enabling the optimization. Upon successful completion of the integration, a confirmation modal will appear to notify you that the process is complete. ![Events Manager confirmation modal with balloons reading 'Congratulations, your CRM integration is complete'](https://scontent.fdel1-5.fna.fbcdn.net/v/t39.2365-6/653706491_1459945362530780_7268147425259848090_n.png?_nc_cat=107&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=e280be&_nc_ohc=rnXarJKKxlMQ7kNvwFWTyKP&_nc_oc=AdqWrRFPyMUnJBz0YIZH9nwn328do22nbsg-c3a0sW4OSmahnw33oN5vQTJA6ULclaZEviPLT-N2sOTTSqT8Lucy&_nc_zt=14&_nc_ht=scontent.fdel1-5.fna&_nc_gid=8CoHmr2sH9T2Mmz8uevRlw&_nc_ss=7b289&oh=00_AQBvDITwv0D0QG2jGaTeEUuMX6Z4El7p3E-dfRfySoMx_g&oe=6A60900D) ## Share the pixel with your ad accounts * Ensure that your ad accounts will have access to the Pixel when running a Conversion Leads campaign. Under the **Settings** tab in [Events Manager⁠](https://www.facebook.com/events_manager2), click on the **Share With an Ad Account** button. This will bring you to your Business Settings. This can also be accessed directly in [Meta Business Suite⁠](https://business.facebook.com/). * Select Add Assets under the Connected Assets tab for your Pixel to add any ad accounts you want to have access to the Pixel. --- # API Calls Source: https://developers.facebook.com/documentation/ads-commerce/marketing-api/audiences Mirror: https://nermalcat69.github.io/meta-developer-docs/documentation/ads-commerce/marketing-api/audiences.html # API Calls Updated: Jun 16, 2026 See examples of API calls to use the Ad Rules Engine. ## Read all rules of an account ``` curl -G \ -d 'fields=name,evaluation_spec,execution_spec,status' \ -d 'access_token=' \ https://graph.facebook.com///adrules_library ``` ## Read a rule ``` curl -G \ -d 'fields=name,evaluation_spec,execution_spec,status' \ -d 'access_token=' \ https://graph.facebook.com// ``` ## Update a rule To update a spec, provide all fields, **including those that are unchanged**. The following is an example updating the rule's trigger to be for every 1,000 impressions. Updating a rule's status requires no spec changes. ``` curl \ -F 'evaluation_spec={ "evaluation_type": ..., "trigger" : { "type": "STATS_MILESTONE", "field": "impressions", "value": 1000, "operator": "EQUAL" }, "filters": ... ] }' \ -F 'access_token=' \ https://graph.facebook.com// ``` Here is an example updating the filters to select all ads that have more than 200 clicks. Other filters such as `entity_type` and `time_preset` must still be in this update. ``` curl \ -F 'evaluation_spec={ "evaluation_type": ..., "filters" : [ { "field": "clicks", "value": 200, "operator": "GREATER_THAN", }, { ... ] }' \ -F 'access_token=' \ https://graph.facebook.com// ``` ## Delete a rule ``` curl -X DELETE \ -d 'access_token=' \ https://graph.facebook.com// ``` ## Access a rule's execution history Access historic data for each rule's executions through a dedicated endpoint. By default, this endpoint provides relevant data, such as results and actions. You can also check the state of the rule at each execution to track edits. ``` curl -G \ -d 'access_token=' \ https://graph.facebook.com///history ``` In addition, this endpoint supports three filtering mechanisms on the data: `object_id`, `action`, and `hide_no_changes`. You can filter the results by an `object_id` or an `action` to see results for only that `object_id` or `action` type. You can also filter the results using the `hide_no_changes` flag to exclude executions that made no changes. You can combine the `object_id`, `action`, and `hide_no_changes` filters to further narrow your results. ``` curl -G \ -d 'object_id=123' \ -d 'action=CHANGED_BID' \ -d 'hide_no_changes=true' \ -d "access_token=" \ https://graph.facebook.com///history ``` ## Access an account's execution history Access aggregated history data for all rules under your account through a dedicated endpoint. By default, this endpoint provides the same relevant data as the [rule's execution history](https://developers.facebook.com/documentation/ads-commerce/marketing-api/audiences#history), but also includes the id of the rules for each entry. Entries in this endpoint are ordered from newest to oldest. This endpoint also supports the same filtering mechanisms as above: `object_id`, `action`, and `hide_no_changes`. ``` curl -G \ -d 'access_token=' \ https://graph.facebook.com///adrules_history ``` ## Preview a rule Preview the evaluation of a [Schedule Based Rule](https://developers.facebook.com/documentation/ads-commerce/marketing-api/ad-rules/guides/scheduled-based-rules) by sending a `POST` request to this endpoint, which returns a list of objects that satisfy all specified filters of the rule at that time. ``` curl \ -F 'access_token=' \ https://graph.facebook.com///preview ``` ## Manually execute a rule Manually execute a [Schedule Based Rule](https://developers.facebook.com/documentation/ads-commerce/marketing-api/ad-rules/guides/scheduled-based-rules) by sending a `POST` request to this endpoint. When a `POST` request is sent to this endpoint, the engine immediately schedules the rule to run. ``` curl \ -F 'access_token=' \ https://graph.facebook.com///execute ``` You can fetch results from the execution history once execution completes. ## Read governing rules for an object Read all the rules that govern each ad, ad set, and ad campaign through these endpoints. By default, a rule governs an object if it statically references it by the `id` filter or dynamically references it by the `entity_type` filter. This endpoint also supports an optional `pass_evaluation`. With `pass_evaluation`, you can further limit the list of rules, by whether or not the object would pass the rule's filters at that time. If `pass_evaluation` is `true`, you receive all rules that, when [previewed](https://developers.facebook.com/documentation/ads-commerce/marketing-api/audiences#preview), would return the object. If it is `false`, you receive all rules that would not. ``` curl \ -F 'access_token=' \ https://graph.facebook.com///adrules_governed ``` --- # API Integration Setup Source: https://developers.facebook.com/documentation/ads-commerce/commerce-platform/app-dashboard Mirror: https://nermalcat69.github.io/meta-developer-docs/documentation/ads-commerce/commerce-platform/app-dashboard.html # API Integration Setup Updated: Jun 28, 2026 Using the Commerce API, you can integrate your Commerce account with your inventory and order management system programmatically to [manage products and inventory](https://developers.facebook.com/documentation/ads-commerce/commerce-platform/catalog) and [orders](https://developers.facebook.com/documentation/ads-commerce/commerce-platform/order-management). ## Requirements * You must be an admin of your [Meta Business Suite⁠](https://www.facebook.com/business/help/113163272211510?id=180505742745347). * Before you complete the [App Review](https://developers.facebook.com/docs/commerce-platform/setup/app-review), your app can only access test commerce accounts. ## Step 1: Create a developer app Go to [Meta for Developers](https://developers.facebook.com/apps) and click **My Apps** > **Create App**. You can also use an existing app. ## Step 2: Create a system user Use access tokens backed by a [system user](https://developers.facebook.com/docs/marketing-api/businessmanager/systemuser) to access the Commerce API. An access token obtained from a typical user can be invalidated after a period of time, or if that user changes their Facebook password. * If you've not done so already, [add your app to your Meta Business Suite⁠](https://www.facebook.com/business/help/2199735813629697?id=420299598837059). * [Add system users to your Meta Business Suite⁠](https://www.facebook.com/business/help/503306463479099?id=2190812977867143). You can also use an existing system user in your business. ## Step 3: Assign assets [Assign your system user admin access⁠](https://www.facebook.com/business/help/325571851329683?id=2190812977867143) to the following assets in your Meta Business Suite: * The app you use for the Commerce API * The test commerce account you created * The Facebook Page backing your test commerce account * The catalog connected to your test commerce account You can only use the system user's access token to access assets assigned to the system user. Once you set up your production commerce account, make sure that you also assign the system user to the relevant assets. ## Step 4: Generate a system user access token * On the **Meta Business Suite** > **System User** page, click **Add Assets** and assign the system user as an admin of your app. * Click **Generate Token** to generate an access token. * Request the following permissions when you generate the access token: * `catalog_management` if you plan to use API to manage catalogs * `business_management` if you plan to use API to manage business assets * `commerce_manage_accounts` or `commerce_account_read_settings` * `commerce_account_manage_orders` or `commerce_account_read_orders` * `commerce_account_read_reports` to access the [Finance Reporting API](https://developers.facebook.com/documentation/ads-commerce/commerce-platform/reporting) * Use the [Access Token Debugger tool](https://developers.facebook.com/tools/debug/accesstoken/) to verify that your access token has the required permissions. ### Page access token Before your app is approved by [App Review](https://developers.facebook.com/docs/commerce-platform/setup/app-review), your app can only access a test commerce account, so make sure you generate a Page access token for the Facebook Page backing your test commerce account. ## Step 5: Connect your app to a commerce account By default, your shop is configured to automatically move new orders to the `IN_PROGRESS` state. To enable order acknowledgment, you must first [associate your shop with your app](https://developers.facebook.com/documentation/ads-commerce/commerce-platform/order-management/acknowledgement-api#order_management_apps). Use this one-time operation if you are planning to fulfill orders using the Order Management API, and it will leave new orders in the `CREATED` state until you acknowledge them. ## Step 6: Start building * Place test orders on your shop using the [App Dashboard](https://developers.facebook.com/apps/). * Begin managing your orders placed in your test commerce account using the [Order Management API](https://developers.facebook.com/documentation/ads-commerce/commerce-platform/order-management). * Once you demonstrate your integration on a test account, submit your app for [App Review](https://developers.facebook.com/docs/commerce-platform/setup/app-review) to manage a real commerce account. * If you are a platform that builds integration for your sellers, you need to build an onboarding flow that automates steps [2](https://developers.facebook.com/documentation/ads-commerce/commerce-platform/app-dashboard#create_system_user) to [5](https://developers.facebook.com/documentation/ads-commerce/commerce-platform/app-dashboard#create_pat) so that you can make API calls on the seller's behalf. Learn more about [Platform Integration](https://developers.facebook.com/documentation/ads-commerce/commerce-platform/platforms) and [Seller Onboarding](https://developers.facebook.com/documentation/ads-commerce/commerce-platform/platforms/onboarding). --- # Accounts and Assets Source: https://developers.facebook.com/documentation/ads-commerce/commerce-platform/get-started Mirror: https://nermalcat69.github.io/meta-developer-docs/documentation/ads-commerce/commerce-platform/get-started.html # Accounts and Assets Updated: Jun 16, 2025 **NOTE**: This document will be deprecated on **September 4, 2025**. On that date, Shops checkout will no longer be available on Facebook and Instagram. Buyers will instead be sent to sellers' own websites for checkout. When you set up a Shop in Commerce Manager, Facebook creates or connects a few accounts and assets together to form your commerce presence. We recommend to learn and understand their roles and relationships to build a successful commerce integration. ## Assets and Functions | Asset | Function | | --- | --- | | **Business** | Main account that represents your business with Facebook. Your business owns all of the assets described below that collectively form your commerce presence. | | **Commerce Account** | Represents your commerce settings and hosts data about your commerce activities. | | **Facebook Page** | A commerce account is backed by one Facebook Page owned under the same business. The Facebook Page can also be activated as a sales channel. | | **Instagram Account** | A commerce account can be connected to a number of Instagram accounts owned under the same business. The Instagram accounts can be activated as sales channels. | | **Catalog** | A commerce account is connected to a catalog owned under the same business. The catalog contains product listings used in your shops. Removing the catalog from your business will delete your commerce account. You can find the IDs of these assets in Business Manager and Commerce Manager. You can also retrieve the IDs and troubleshoot the setup via the API. | ![Diagram of a Business owning two Commerce Accounts, each connected to a Page, Product Catalog, and Instagram Accounts](https://scontent.fdel27-5.fna.fbcdn.net/v/t39.2365-6/651724009_1459945282530788_5607738426331390039_n.png?_nc_cat=102&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=e280be&_nc_ohc=tNPIp3AhTQQQ7kNvwFSEVDl&_nc_oc=Ado38_c0l382EQxa9WVWgC0e_J3JqfoXCJF7QyOTnhPHYlcCJE17bgvKw1LD9qJkJXJTiBaJqbKL0Fuie1HeAnh3&_nc_zt=14&_nc_ht=scontent.fdel27-5.fna&_nc_gid=1JvWqoLZFpOza9VkK2WrMg&_nc_ss=7b289&oh=00_AQAQET5uTwQ6sGEDa3K2BlB4CkdAXHG9UXw2Qt_LJ4rBqw&oe=6A6098AA) In the diagram: * The shaded assets and connections power a functional commerce account. Your business (blue connections) must own the Facebook Page, Catalog, and (optionally) Instagram accounts prior to creating the Commerce Account in Commerce Manager. * Your Commerce Account will be connected to those assets during the setup in Commerce Manager (orange connections). * The Commerce Account is, in turn, also owned by the business. These connections must hold for your Commerce Account to work properly. --- # Acknowledgement API Reference Source: https://developers.facebook.com/documentation/ads-commerce/commerce-platform/order-management/order-snapshot-api Mirror: https://nermalcat69.github.io/meta-developer-docs/documentation/ads-commerce/commerce-platform/order-management/order-snapshot-api.html # Acknowledgement API Reference Updated: Feb 9, 2026 When an order is completed with being processed on the Commerce Platform (fraud checks, remorse period, ...), its state is automatically changed to `CREATED`. Acknowledging an order confirms that you have moved the order into your Order Management System and are ready to fulfill it. Acknowledging an order changes its state to `IN_PROGRESS`. By default, your shop is configured to automatically move orders to the `IN_PROGRESS` state when finalized. To enable order acknowledgement, you must first associate your shop with your app. This one-time operation is recommended if you are planning to fulfill orders using the API, and will leave finalized orders in the `CREATED` state until you acknowledge them. ## Associate Commerce Seller Settings with Your App To manage orders via API, an app must first be associated with the commerce seller settings representing your shop. **This action only needs to be performed once**, and instructs the Commerce Platform to leave finalized orders in the `CREATED` state for you to acknowledge. ``` curl -X POST \ -F 'access_token=' \ https://graph.facebook.com/v25.0//order_management_apps ``` The token here is `PAGE_ACCESS_TOKEN` ### Request | Attribute | Description | | --- | --- | | `cms-id` Type: string | Commerce seller settings ID for the page that you want to extract orders. You can find `{cms-id}` by logging into [Facebook Commerce Manager⁠](https://www.facebook.com/commerce_manager) and then select the page that you want to extract orders. You will be redirected to www.facebook.com/ commerce\_manager/`{cms-id}` | ### Sample Response ``` { "success": true } ``` ## Acknowledge One Order Acknowledge one specific order that was retrieved using the [List Orders API](https://developers.facebook.com/documentation/ads-commerce/commerce-platform/order-management/order-api). This action marks the order as `IN_PROGRESS`, and can be filtered out from future pulls. Be sure to capture errors, take action according to the error messages, and retry accordingly. **Do not start processing orders in your systems that have not been successfully acknowledged.** ``` curl -X POST \ -F 'access_token=' \ https://graph.facebook.com/v25.0//acknowledge_order ``` The token here is `PAGE_ACCESS_TOKEN` ### Request | Attribute | Description | | --- | --- | | `merchant_order_reference` Type: string | **Optional** ID representing the order in your order management system. | | `idempotency_key` Type: string | **Required** Unique key per request | ### Sample Request ``` { "idempotency_key": "cb090e84-e75a-9a34-45d3-5163bec88b65", "merchant_order_reference": "external_order-id-1" } ``` ### Sample Response ``` { "id": "64000841784004", "state": "IN_PROGRESS" } ``` ## Acknowledge Multiple Orders Acknowledge order batches have a maximum of 100 orders per batch. Acknowledge orders that were received by the [List Orders API](https://developers.facebook.com/documentation/ads-commerce/commerce-platform/order-management/order-api), in a batch. This action marks orders as `IN_PROGRESS`, and can be filtered out from future pulls. ``` curl -X POST \ -F 'access_token=' \ https://graph.facebook.com/v25.0//acknowledge_orders ``` The token here is `PAGE_ACCESS_TOKEN` ### Request | Attribute | Description | | --- | --- | | `orders` Type: `array` of [`order_id`](https://developers.facebook.com/documentation/ads-commerce/commerce-platform/order-management/order-snapshot-api#order_id) | **Required** Array of 100 or less order IDs. | | `idempotency_key` Type: string | **Required** Unique key per request | ### `order_id` object | Attribute | Description | | --- | --- | | `id` Type: string | **Required** ID of the order. | | `merchant_order_reference` Type: string | **Optional** ID representing the order in your order management system | You can Acknowledge multiple orders in one request. If few orders were in `FB_PROCESSING` state, then you **cannot ACK** them and receive a **coded exception**. Retrying these requests with same idempotency key returns the same result. **When you get a coded exception, please use new idempotency key and retry.** ### Sample Request ``` { "idempotency_key": "cb090e84-e75a-9a34-45d3-5163bec88b65", "orders": [ { "id": "64000841790004" }, { "id": "10100677592885259" } ] } ``` ### Response | Attribute | Description | | --- | --- | | `orders` Type: `array` of [`order_id_and_state`](https://developers.facebook.com/documentation/ads-commerce/commerce-platform/order-management/order-snapshot-api#order_id_and_state) | Array of order ID and order state. | #### `order_id_and_state` object | Attribute | Description | | --- | --- | | `id` Type: string | ID of the order. | | `state` Type: [`order_state`](https://developers.facebook.com/docs/commerce-platform/order-management/overview#orders_states) | Order state. | ### Sample Response ``` { "orders": [ { "id": "64000841790004", "state": "IN_PROGRESS" }, { "id": "10100677592885259", "error": { "error_code": 2361003, "error_message": "Invalid Order ID" } } ] } ``` --- # Activities Source: https://developers.facebook.com/documentation/ads-commerce/catalog/reference/activities/catalog-edge Mirror: https://nermalcat69.github.io/meta-developer-docs/documentation/ads-commerce/catalog/reference/activities/catalog-edge.html # Activities Updated: May 29, 2026 The Activities API allows you to manage catalog items such as concerts, sporting events, guided tours, and other bookable activities. You can read, update, and delete individual items using the `/{activity-id}` node. ## Permissions To use this API, your app needs the following permission: * `catalog_management` ## Reading To retrieve an activity item, send a `GET` request: ``` GET /v25.0/{activity-id} HTTP/1.1 Host: graph.facebook.com ``` ### Fields | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | Yes | A unique content ID for the activity. Each content ID must appear only once in your catalog. To run Advantage+ catalog ads, this ID must exactly match the content ID for the same activity in your Meta Pixel code. Character limit: 100. | | `retailer_id` | string | Yes | Retailer-provided unique identifier for the activity item. | | `name` | string | Yes | A specific and relevant title for the activity. Shown in ads. Character limit: 200. See [title specifications⁠](https://www.facebook.com/business/help/2104231189874655). | | `description` | string | Yes | A short and relevant description of the activity. Shown in ads. Use plain text and don't enter text in all capital letters. Character limit: 9999. See [description specifications⁠](https://www.facebook.com/business/help/2302017289821154). | | `image_url` | string | Yes | The URL for the main image of your activity. Shown in ads. Must be in a supported format (JPG/PNG) and at least 500 x 500 pixels. See [image specifications⁠](https://www.facebook.com/business/help/686259348512056). | | `url` | string | Yes | The link to the specific page on your business's website where people can learn more about or book this activity. Links must begin with http:// or https://. | | `price` | string | No | The price of the activity. Shown in ads. Format the price as a number followed by the 3-letter currency code (ISO 4217 standards). Use a period (.) as the decimal point. Do not use commas. | | `sale_price` | string | No | The discounted price of the activity if it's on sale. Format the price as a number followed by the 3-letter currency code (ISO 4217 standards). Use a period (.) as the decimal point. Do not use commas. A sale price is required if you want to use an overlay for discounted prices. | | `currency` | string | No | ISO 4217 currency code for the price. | | `brand` | string | No | The name of the activity provider, organizer, or seller. Character limit: 100. | | `activity_category` | string | No | The type of activity. Used to recommend your content to the right people. Supported values: Comedy, Concert, Conference, Sports, Theater, Tour, Transfer, Other. | | `activity_sub_categories` | array | No | A more specific subcategory of the activity, such as Rock or Pop for concerts, or Football or Cricket for sports. Use commas to separate multiple entries. Character limit: 100. | | `activity_date` | string | No | The scheduled date when the activity will take place. For one-off activities only. Use the format YYYY-MM-DD. | | `performers` | array | No | The main performers, speakers or guides for the activity, such as a musician or actor. Use commas to separate multiple names. Character limit: 200. | | `user_rating` | float | No | The average user rating of the activity. Enter a rating between 0.0 and 5.0, using a single decimal place. Can be shown in ads. | | `rating_count` | integer | No | The number of users who have left ratings on the activity. Can be shown in ads. | | `location_names` | array | No | The name of the venue or location where the activity takes place. Use commas to separate multiple locations. Character limit: 200. | | `in_languages` | array | No | The language of the content or performance. Use language codes from the ISO 639 standard. Use commas to separate multiple entries. | | `address` | object | No | Address of the activity location. Contains the following sub-fields: city, country. | | `availability_circle_origin` | object | No | The center point of a circular availability area. Contains latitude and longitude sub-fields. Use with availability\_circle\_radius and availability\_circle\_radius\_unit. | | `availability_circle_radius` | float | No | Radius of the circular availability area. Minimum: 1 km or 0.6 mi, maximum: 255 km or 158.4 mi. Use with availability\_circle\_origin and availability\_circle\_radius\_unit. Only one area type (circle, polygon, or postal codes) should be defined per product. | | `availability_circle_radius_unit` | enum | No | The unit of distance for the availability radius, in kilometres (km) or miles (mi). Supported values: km, mi. Use with availability\_circle\_origin and availability\_circle\_radius. | | `availability_polygon_coordinates` | array | No | Ordered lat/lng pairs tracing the perimeter of a polygonal availability area. Each object contains latitude and longitude sub-fields. | | `availability_postal_codes` | array | No | Postal codes where the activity is available. | | `status` | string | No | Controls whether the activity is active or archived in your catalog. Only active items can be shown to people in your ads, shops, or other channels. Supported values: active, archived. Items are active by default. This field was previously called `visibility`. | | `tags` | array | No | Tags for product organization. | | `additional_image_urls` | array | No | Additional image URLs for the activity beyond the primary image. You can add up to 20 images. | | `video_urls` | array | No | URLs for videos of your activity. Videos can be shown in ads and make your ads more engaging. Must be a direct link to download the video file. You can add up to 20 videos. | | `custom_label_0 through custom_label_4` | string | No | Any relevant information you want to add to your ad creative such as in the headline. | | `custom_number_0 through custom_number_4` | integer | No | Any number you want to filter products by when you create product sets. Use this to filter by number ranges (is greater than and is less than). Use whole numbers between 0 and 4294967295. Decimals and commas are not supported. | | `applink_ios_url` | string | No | A deep link to your app on iOS. Used to send people from your ads to your app, if installed. If it isn't installed, redirects to your website or the App Store. | | `applink_ios_app_store_id` | integer | No | The unique numeric identifier for the app on the Apple App Store. | | `applink_ios_app_name` | string | No | The official name of the app as it appears on the Apple App Store. | | `applink_android_url` | string | No | A deep link to your app on Android. Used to send people from your ads to your app, if installed. If it isn't installed, redirects to your website or Google Play. | | `applink_android_package` | string | No | The unique package identifier for the Android app. | | `applink_android_class` | string | No | Android activity class name. | | `applink_android_app_name` | string | No | The official name of the app as it appears on the Google Play Store. | ## Creating To create activity items in a catalog, you can use: * [Product Feed](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/product-feed#Creating) — upload items via a scheduled data feed. * [Items Batch API](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/product-catalog/items_batch) — create or update items in bulk via the API. * [Product Catalog Activities edge](https://developers.facebook.com/documentation/ads-commerce/catalog/reference/activities/catalog-edge) — create items individually via the API. ## Updating To update an activity item, send a `PUT` request with the fields you want to change: ``` PUT /v25.0/{activity-id} HTTP/1.1 Host: graph.facebook.com Content-Type: application/json { "name": "Jasper's City Highlights Tour", "description": "Discover the city's most iconic landmarks on a guided walking tour with an expert local guide. Suitable for all ages.", "activity_category": "Tour", "performers": "Alex Smith,Jordan Lee", "activity_date": "2026-09-15" } ``` All fields are optional for partial updates. Only the fields included in the request body will be updated. For the full list of updatable fields, see the [Fields](https://developers.facebook.com/documentation/ads-commerce/catalog/reference/activities/catalog-edge#reading-fields) section above. ### Response ``` { "id": "ACT-001" } ``` ## Deleting To delete an activity item, send a `DELETE` request: ``` DELETE /v25.0/{activity-id} HTTP/1.1 Host: graph.facebook.com ``` ### Response ``` { "id": "ACT-001" } ``` --- # Ad Source: https://developers.facebook.com/documentation/ads-commerce/graph-api/reference/adgroup/ad_studies Mirror: https://nermalcat69.github.io/meta-developer-docs/documentation/ads-commerce/graph-api/reference/adgroup/ad_studies.html # Ad Updated: May 6, 2026 Contains information to display an ad and associate it with an ad set. Each ad is associated with an ad set and all ads in a set have the same daily or lifetime budget, schedule, and targeting. Creating multiple ads in an ad set helps optimize their delivery based on variations in images, links, video, text or placements. Note that results returned by `synchronous_ad_review` does not represent the final decision made during full review of your ad. ### Ads with Political Content To increase transparency of ads on Facebook, we require advertisers running ads with political content to complete authorization. We will begin enforcing this in the next few weeks. You must also indicate that your ad has political content and provide the name of the funding source for the ad: * Your ad account must be authorized by a Page admin to run political ads for this Page. This is done by a Page admin on the `Issue, Electoral or Political Ads` tab under `Page Settings`. * Ad account users must go through a verification process. ### Ads with Page Mentions With Facebook's ads tools such as [Ads Manager⁠](https://www.facebook.com/ads/manager/accounts) or light-weight interfaces, you can create an ad with a *Page Mention*. This displays a link in your ad which opens an advertiser's Facebook page. **We do not provide this functionality in Marketing API**. If you try to create an ad with the API with a Page Mention it will succeed, however we will deliver the ad without the mention. Instead, use one of Facebook's ads tools. ### Targeting DSA Regulated Locations (European Union) To create or copy an ad which is in an ad set targeted in the European Union's Digital Services Act (DSA) regulated locations, please set the payor/beneficiary information first. For your convenience, if the `default_dsa_payor` and `default_dsa_beneficiary` are set in an ad account, during the copying process, even if the original ad set does not set payor or beneficiary, it will be filled with saved default values. For more information on copying ads that target DSA regulated locations in the EU, see the [Ad Copies reference documentation](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/adgroup/copies#targeting-dsa-regulated-locations--european-union-). ### Targeting Youth in European Union (EU), European Economic Area (EEA), and Switzerland Meta will stop showing ads to youth in the EU, EEA, and Switzerland as early as the week of November 6, 2023. When creating new ad sets or updating existing ones that target youth in the EU, EEA, and Switzerland, they will be prevented. Existing ad sets targeting youth in the EU, EEA and Switzerland, will pause delivery as early as the week of November 6, 2023. Existing ad sets targeting youth in the EU, EEA, and Switzerland and in other regions will see a warning that the ads in the ad sets will no longer be delivered to youth in the EU, EEA, and Switzerland. ### Examples Creating an ad: ``` curl -X POST \ -F 'name="My Ad"' \ -F 'adset_id=""' \ -F 'creative={ "creative_id": "" }' \ -F 'status="PAUSED"' \ -F 'access_token=' \ https://graph.facebook.com/v25.0/act_/ads ``` To create a political ad, provide `authorization_category` with the value `POLITICAL` . For example: ``` curl -X POST \ -F 'name="My AdGroup"' \ -F 'adset_id=""' \ -F 'creative={ "creative_id": "" }' \ -F 'status="PAUSED"' \ -F 'authorization_category="POLITICAL"' \ -F 'access_token=' \ https://graph.facebook.com/v25.0/act_/ads ``` See: * [Ad Campaign](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-campaign-group), [Ad Set](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-campaign), and [Ad Creative](https://developers.facebook.com/docs/reference/ads-api/adcreative) * [Storing Ad Objects](https://developers.facebook.com/documentation/ads-commerce/marketing-api/best-practices/manage-your-ad-object-status) ## Reading An ad object contains the data necessary to visually display an ad and associate it with a corresponding ad set. ### By ad ID ``` curl -X GET \ -d 'fields="id,name"' \ -d 'access_token=' \ https://graph.facebook.com/v25.0// ``` ### By ad account To read all ads from one ad account: Select language PHP Business SDKPython Business SDKcURL --- ``` use FacebookAds\Object\AdAccount; use FacebookAds\Object\Fields\AdFields; $account = new AdAccount($account_id); $ads = $account->getAds(array( AdFields::NAME, )); // Outputs names of Ads. foreach ($ads as $ad) { echo $ad->name; } ``` ### By ad campaign Read all ads from a campaign: ``` curl -X GET \ -d 'fields="name"' \ -d 'access_token=' \ https://graph.facebook.com/v25.0//ads ``` ### By ad set To read all ads from one ad set: Select language PHP Business SDKPython Business SDKcURL --- ``` use FacebookAds\Object\AdSet; use FacebookAds\Object\Fields\AdSetFields; $adset = new AdSet($adset_id); $ads = $adset->getAds(array( AdFields::NAME, )); // Outputs names of Ads . foreach ($ads as $ad) { echo $ad->name; } ``` #### Example Select language HTTPPHP SDKJavaScript SDKAndroid SDKiOS SDKcURL --- ``` GET /v25.0//?fields=id%2Cname HTTP/1.1 Host: graph.facebook.com ``` Try it in [Graph API Explorer](https://developers.facebook.com/tools/explorer/?method=GET&path=%3CADGROUP_ID%3E%2F%3Ffields%3Did%252Cname&version=v25.0) If you want to learn how to use the Graph API, read our [Using Graph API guide](https://developers.facebook.com/docs/graph-api/using-graph-api) #### Parameters | Parameter | Description | | --- | --- | | `date_preset` *enum{today, yesterday, this\_month, last\_month, this\_quarter, maximum, data\_maximum, last\_3d, last\_7d, last\_14d, last\_28d, last\_30d, last\_90d, last\_week\_mon\_sun, last\_week\_sun\_sat, last\_quarter, last\_year, this\_week\_mon\_today, this\_week\_sun\_today, this\_year}* | Date Preset | | `review_feedback_breakdown` *boolean* | **Default value:** `false` review\_feedback\_breakdown | | `time_range` *{'since':YYYY-MM-DD,'until':YYYY-MM-DD}* | Time Range. Note if time range is invalid, it will be ignored. --- `since` *datetime* A date in the format of "YYYY-MM-DD", which means from the beginning midnight of that day. `until` *datetime* A date in the format of "YYYY-MM-DD", which means to the beginning midnight of the following day. Show child parameters | #### Fields | Field | Description | | --- | --- | | `id` *numeric string* | id default | | `account_id` *numeric string* | account\_id | | `ad_active_time` *numeric string* | ad\_active\_time | | `ad_review_feedback` *[AdgroupReviewFeedback](https://developers.facebook.com/docs/marketing-api/reference/adgroup-review-feedback)* | ad\_review\_feedback | | `ad_schedule_end_time` *datetime* | ad\_schedule\_end\_time | | `ad_schedule_start_time` *datetime* | ad\_schedule\_start\_time | | `adlabels` *[list](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-label)* | adlabels | | `adset` *[AdSet](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-campaign)* | adset | | `adset_id` *numeric string* | adset\_id | | `bid_amount` *int32* | bid\_amount | | `bid_info` *map* | bid\_info | | `bid_type` *enum {CPC, CPM, MULTI\_PREMIUM, ABSOLUTE\_OCPM, CPA}* | bid\_type | | `campaign` *[Campaign](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-campaign-group)* | campaign | | `campaign_id` *numeric string* | campaign\_id | | `configured_status` *enum {ACTIVE, PAUSED, DELETED, ARCHIVED}* | configured\_status | | `conversion_domain` *string* | conversion\_domain | | `conversion_specs` *[list](https://developers.facebook.com/docs/marketing-api/reference/conversion-action-query)* | conversion\_specs | | `created_time` *datetime* | created\_time | | `creative` *[AdCreative](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-creative)* | creative | | `creative_asset_groups_spec` *[AdCreativeAssetGroupsSpec](https://developers.facebook.com/docs/marketing-api/reference/ad-creative-asset-groups-spec)* | creative\_asset\_groups\_spec | | `demolink_hash` *string* | demolink\_hash | | `display_sequence` *int32* | display\_sequence | | `effective_status` *enum {ACTIVE, PAUSED, DELETED, PENDING\_REVIEW, DISAPPROVED, PREAPPROVED, PENDING\_BILLING\_INFO, CAMPAIGN\_PAUSED, ARCHIVED, ADSET\_PAUSED, IN\_PROCESS, WITH\_ISSUES}* | effective\_status | | `engagement_audience` *bool* | engagement\_audience | | `failed_delivery_checks` *[list](https://developers.facebook.com/docs/marketing-api/adgroup/deliverychecks)* | failed\_delivery\_checks | | `is_autobid` *bool* | is\_autobid | | `issues_info` *[list](https://developers.facebook.com/docs/marketing-api/reference/adgroup-issues-info)* | issues\_info | | `last_updated_by_app_id` *id* | last\_updated\_by\_app\_id | | `name` *string* | name | | `preview_shareable_link` *string* | preview\_shareable\_link | | `priority` *unsigned int32* | priority | | `recommendations` *list* | recommendations | | `source_ad` *[Ad](https://developers.facebook.com/docs/graph-api/reference/adgroup)* | source\_ad | | `source_ad_id` *numeric string* | source\_ad\_id | | `special_ad_categories` *list* | special\_ad\_categories | | `status` *enum {ACTIVE, PAUSED, DELETED, ARCHIVED}* | status | | `targeting` *Targeting* | targeting | | `tracking_and_conversion_with_defaults` *TrackingAndConversionWithDefaults* | tracking\_and\_conversion\_with\_defaults | | `tracking_specs` *[list](https://developers.facebook.com/docs/marketing-api/reference/conversion-action-query)* | tracking\_specs | | `updated_time` *datetime* | updated\_time | #### Edges | Edge | Description | | --- | --- | | [`adcreatives`](https://developers.facebook.com/documentation/ads-commerce/graph-api/reference/adgroup/adcreatives) *Edge* | adcreatives | | [`adrules_governed`](https://developers.facebook.com/documentation/ads-commerce/graph-api/reference/adgroup/adrules_governed) *Edge* | adrules\_governed | | [`copies`](https://developers.facebook.com/documentation/ads-commerce/graph-api/reference/adgroup/copies) *Edge* | copies | | [`insights`](https://developers.facebook.com/documentation/ads-commerce/graph-api/reference/adgroup/insights) *Edge* | insights | | [`leads`](https://developers.facebook.com/documentation/ads-commerce/graph-api/reference/adgroup/leads) *Edge* | leads | | [`previews`](https://developers.facebook.com/documentation/ads-commerce/graph-api/reference/adgroup/previews) *Edge* | previews | | [`targetingsentencelines`](https://developers.facebook.com/documentation/ads-commerce/graph-api/reference/adgroup/targetingsentencelines) *Edge* | targetingsentencelines | #### Error Codes | Error Code | Description | | --- | --- | | 100 | Invalid parameter | | 80004 | There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to /docs/graph-api/overview/rate-limiting#ads-management. | | 613 | Calls to this api have exceeded the rate limit. | | 190 | Invalid OAuth 2.0 Access Token | | 104 | Incorrect signature | | 2635 | You are calling a deprecated version of the Ads API. Please update to the latest version. | | 2500 | Error parsing graph query | | 3018 | The start date of the time range cannot be beyond 37 months from the current date | | 200 | Permissions error | | 270 | This Ads API request is not allowed for apps with development access level (Development access is by default for all apps, please request for upgrade). Make sure that the access token belongs to a user that is both admin of the app and admin of the ad account | ## Creating Before you create an ad, you need an existing [ad set](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-campaign) and [ad creative](https://developers.facebook.com/docs/reference/ads-api/adcreative). You can create ads synchronously and asynchronously. **New ads are in pending state and do not run until Facebook approves or rejects them**. After we approve an ad it runs. If you do not want an ad to automatically run after approval, create it and set its ad set to `paused` (see [ad set](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-campaign)). Run the [ad set](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-campaign) when you are ready. Due to iOS 14.5 changes, [Deferred Deep Linking](https://developers.facebook.com/docs/app-ads/deep-linking#deferred-deep-linking) is no longer available for [SKAdsNetwork Campaigns](https://developers.facebook.com/docs/audience-network/guides/SKAdNetwork). ### Synchronous Creation Creates one ad at a time: ``` curl -X POST \ -F 'name="My Ad"' \ -F 'adset_id=""' \ -F 'creative={ "creative_id": "" }' \ -F 'status="PAUSED"' \ -F 'access_token=' \ https://graph.facebook.com/v25.0/act_/ads ``` ### Asynchronous Creation Create multiple ads at a time asynchronously. Receive a notification when all the ads in the request exist. Make an `HTTP POST` to: `https://graph.facebook.com/{API_VERSION}/act_{AD_ACCOUNT_ID}/asyncadrequestsets` Use these fields: | Field | Description | | --- | --- | | **name** type: string | Required. Name of ad set for newly created ads. | | **ad\_specs** type: array of ad specs | Required. Ads can be created for different ad sets inside the current ad account. To use images in ad creative, provide `image_hash` in ad spec after you upload the image at `https://graph.facebook.com/{API_VERSION}/act_{AD_ACCOUNT_ID}/adimages`. `image_file` inside ad\_specs. | | **notification\_uri** type: string | Optional. Async job completed. This URI notifies the caller with a `POST` and ad set id. | | **notification\_mode** type: string | Optional. Notification mode: `OFF` – No notification `ON_COMPLETE` – Send notification when all ads for set created. | For information on asynchronous request sets, see [Asynchronous Requests](https://developers.facebook.com/documentation/ads-commerce/marketing-api/asyncrequests). ### Limits These are the maximum number of ads per object: | Limit | Value | | --- | --- | | Ads in regular ad account | 5000 non-deleted ads | | Ads in bulk ad account | 50000 non-deleted ads | | Ads in an ad set | 50 non-deleted ads | | Archived ads in an ad account | 100,000 archived ads | ### Examples Download details for an ad: ``` curl -X POST \ -F 'name="My AdGroup with Redownload"' \ -F 'adset_id=""' \ -F 'creative={ "creative_id": "" }' \ -F 'redownload=1' \ -F 'status="PAUSED"' \ -F 'access_token=' \ https://graph.facebook.com/v25.0/act_/ads ``` ### /{ad\_id}/copies You can make a POST request to *copies* edge from the following paths: * [/{ad\_id}/copies](https://developers.facebook.com/documentation/ads-commerce/graph-api/reference/adgroup/copies) When posting to this edge, an [Ad](https://developers.facebook.com/docs/graph-api/reference/adgroup) will be created. #### Parameters | Parameter | Description | | --- | --- | | `adset_id` *numeric string or integer* | Single ID of an adset object to make the parent of the copy. Ignore if you want to keep the copy under the original adset parent. | | `creative_parameters` *AdCreative* | Creative inputs which will be used to construct the creative in the new ad. Overwrites happen at the top level. If no input is provided, the new ad will be created with an identical ad creative. If some input is provided, those parameters will be assigned to the ad creative created by this API call. Accepts all ad creative parameters as specified in /documentation/ads-commerce/marketing-api/reference/ad-account/adcreatives supports emoji | | `rename_options` *JSON or object-like arrays* | Rename options --- `rename_strategy` *enum {DEEP\_RENAME, ONLY\_TOP\_LEVEL\_RENAME, NO\_RENAME}* **Default value:** `ONLY_TOP_LEVEL_RENAME` `DEEP_RENAME`: will change this object's name and children's names in the copied object. `ONLY_TOP_LEVEL_RENAME`: will change the this object's name but won't change the children's name in the copied object. `NO_RENAME`: will change no name in the copied object `rename_prefix` *string* A prefix to copy names. Defaults to null if not provided. `rename_suffix` *string* A suffix to copy names. Defaults to null if not provided and appends a localized string of `- Copy` based on the ad account locale. Show child parameters | | `status_option` *enum {ACTIVE, PAUSED, INHERITED\_FROM\_SOURCE}* | **Default value:** `PAUSED` `ACTIVE`: the copied ad will have active status. `PAUSED`: the copied ad will have paused status. `INHERITED_FROM_SOURCE`: the copied ad will have the parent status. | #### Return Type This endpoint supports [read-after-write](https://developers.facebook.com/docs/graph-api/overview#read-after-write) and will read the node represented by *copied\_ad\_id* in the return type. ``` Struct { copied_ad_id: numeric string, } ``` #### Error Codes | Error Code | Description | | --- | --- | | 100 | Invalid parameter | | 200 | Permissions error | --- ### /act\_{ad\_account\_id}/ads You can make a POST request to *ads* edge from the following paths: * [/act\_{ad\_account\_id}/ads](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-account/ads) When posting to this edge, an [Ad](https://developers.facebook.com/docs/graph-api/reference/adgroup) will be created. #### Example Select language HTTPPHP SDKJavaScript SDKAndroid SDKiOS SDKcURL --- ``` POST /v25.0/act_/ads HTTP/1.1 Host: graph.facebook.com name=My+Ad&adset_id=%3CAD_SET_ID%3E&creative=%7B%22creative_id%22%3A%22%3CCREATIVE_ID%3E%22%7D&status=PAUSED ``` Try it in [Graph API Explorer](https://developers.facebook.com/tools/explorer/?method=POST&path=act_%3CAD_ACCOUNT_ID%3E%2Fads%3Fname%3DMy%2BAd%26adset_id%3D%253CAD_SET_ID%253E%26creative%3D%257B%2522creative_id%2522%253A%2522%253CCREATIVE_ID%253E%2522%257D%26status%3DPAUSED&version=v25.0) If you want to learn how to use the Graph API, read our [Using Graph API guide](https://developers.facebook.com/docs/graph-api/using-graph-api) #### Parameters | Parameter | Description | | --- | --- | | `ad_schedule_end_time` *datetime* | An optional parameter that defines the end time of an individual ad. If no end time is defined, the ad will run on the campaign's schedule. This parameter is only available for sales and app promotion campaigns. | | `ad_schedule_start_time` *datetime* | An optional parameter that defines the start time of an individual ad. If no start time is defined, the ad will run on the campaign's schedule. This parameter is only available for sales and app promotion campaigns. | | `adlabels` *list* | Ad labels associated with this ad | | `adset_id` *int64* | The ID of the ad set, required on creation. | | `adset_spec` *Ad set spec* | The ad set spec for this ad. When the spec is provided, adset\_id field is not required. | | `audience_id` *string* | The ID of the audience. | | `bid_amount` *integer* | **Deprecated.** We no longer allow setting the `bid_amount` value on an ad. Please set `bid_amount` for the ad set. | | `conversion_domain` *string* | The domain where conversions happen. Required to create or update an ad in a campaign that shares data with a pixel. This field will be auto-populated for existing ads by inferring from destination URLs . Note that this field should contain only the first and second level domains, and not the full URL. For example `facebook.com`. | | `creative` *AdCreative* | This field is required for create. The ID or creative spec of the ad creative to be used by this ad. You can read more about creatives [here](https://developers.facebook.com/docs/marketing-api/adcreative). You may supply the ID within an object as follows: `{"creative_id": }` or creative spec as follow: `{"creative": {\"name\": \"\", \"object_story_spec\": }​}` required supports emoji | | `creative_asset_groups_spec` *string (CreativeAssetGroupsSpec)* | creative\_asset\_groups\_spec supports emoji | | `date_format` *string* | The format of the date. | | `display_sequence` *int64* | The sequence of the ad within the same campaign | | `engagement_audience` *boolean* | Flag to create a new audience based on users who engage with this ad | | `execution_options` *list* | **Default value:** `Set` An execution setting `validate_only`: when this option is specified, the API call will not perform the mutation but will run through the validation rules against values of each field. `include_recommendations`: this option cannot be used by itself. When this option is used, recommendations for ad object's configuration will be included. A separate section [recommendations](https://developers.facebook.com/docs/marketing-api/reference/ad-recommendation) will be included in the response, but only if recommendations for this specification exist. `synchronous_ad_review`: this option should not be used by itself. It should always be specified with `validate_only`. When these options are specified, the API call will perform Ads Integrity validations, which include message language checking, image 20% text rule, and so on, as well as the validation logics. If the call passes validation or review, response will be `{"success": true}`. If the call does not pass, an error will be returned with more details. These options can be used to improve any UI to display errors to the user much sooner, e.g. as soon as a new value is typed into any field corresponding to this ad object, rather than at the upload/save stage, or after review. | | `include_demolink_hashes` *boolean* | Include the demolink hashes. | | `name` *string* | Name of the ad. required supports emoji | | `priority` *int64* | Priority | | `source_ad_id` *numeric string or integer* | ID of the source Ad, if applicable. | | `status` *enum{ACTIVE, PAUSED, DELETED, ARCHIVED}* | Only `ACTIVE` and `PAUSED` are valid during creation. Other statuses can be used for update. When an ad is created, it will first go through ad review, and will have the ad status `PENDING_REVIEW` before it finishes review and reverts back to your selected status of `ACTIVE` or `PAUSED`. During testing, it is recommended to set ads to a `PAUSED` status so as to not incur accidental spend. | | `tracking_specs` *Object* | With Tracking Specs, you log actions taken by people on your ad. See [Tracking and Conversion Specs](https://developers.facebook.com/documentation/ads-commerce/marketing-api/tracking-specs). | #### Return Type This endpoint supports [read-after-write](https://developers.facebook.com/docs/graph-api/overview#read-after-write) and will read the node represented by *id* in the return type. ``` Struct { id: numeric string, success: bool, } ``` #### Error Codes | Error Code | Description | | --- | --- | | 100 | Invalid parameter | | 200 | Permissions error | | 613 | Calls to this api have exceeded the rate limit. | | 368 | The action attempted has been deemed abusive or is otherwise disallowed | | 80004 | There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to /docs/graph-api/overview/rate-limiting#ads-management. | | 194 | Missing at least one required parameter | | 500 | Message contains banned content | | 2635 | You are calling a deprecated version of the Ads API. Please update to the latest version. | | 190 | Invalid OAuth 2.0 Access Token | | 105 | The number of parameters exceeded the maximum for this operation | --- ## Updating Update certain fields: ``` curl -X POST \ -F 'name="My New Ad"' \ -F 'access_token=' \ https://graph.facebook.com/v25.0// ``` ### Limitations * Only update fields that were used during ad creation can be updated. * `adset_id` and `social_prefs` can not be updated. * Ads with `status = ARCHIVED` have only two mutable fields: `name` and `status`. You can only change the latter to `DELETED`. * Ads with `status = DELETED` only can have `name` changed. * Ads in an ad set with `creative_sequence` set cannot be changed to `PAUSED`, `ARCHIVED`, or `DELETED`. * Trying to duplicate existing objective campaigns to use the new objective values (`OUTCOME_APP_PROMOTION`, `OUTCOME_AWARENESS`, `OUTCOME_ENGAGEMENT`, `OUTCOME_LEADS`, `OUTCOME_SALES`, `OUTCOME_TRAFFIC`) may throw an error. ### Examples Update the name: ``` curl -X POST \ -F 'name="My New Ad"' \ -F 'access_token=' \ https://graph.facebook.com/v25.0// ``` Update the name and download ad information: ``` curl -X POST \ -F 'adgroup_status="PAUSED"' \ -F 'access_token=' \ https://graph.facebook.com/v25.0// ``` Update the status: ``` curl -X POST \ -F 'adgroup_status="PAUSED"' \ -F 'access_token=' \ https://graph.facebook.com/v25.0// ``` You can't perform this operation on this endpoint. ## Deleting #### Deleting an ad You can remove values for any optional fields by [updating](https://developers.facebook.com/documentation/ads-commerce/graph-api/reference/adgroup/ad_studies#Updating) the value to empty. You cannot delete ads in ad set with `creative_sequence` settings. ``` curl -X DELETE \ -F 'access_token=' \ https://graph.facebook.com/v25.0// ``` ### /{ad\_id} You can delete an [Ad](https://developers.facebook.com/docs/graph-api/reference/adgroup) by making a DELETE request to [/{ad\_id}](https://developers.facebook.com/docs/graph-api/reference/adgroup). #### Example Select language HTTPPHP SDKJavaScript SDKAndroid SDKiOS SDKcURL --- ``` DELETE /v25.0// HTTP/1.1 Host: graph.facebook.com ``` Try it in [Graph API Explorer](https://developers.facebook.com/tools/explorer/?method=DELETE&path=%3CADGROUP_ID%3E%2F&version=v25.0) If you want to learn how to use the Graph API, read our [Using Graph API guide](https://developers.facebook.com/docs/graph-api/using-graph-api) #### Parameters This endpoint doesn't have any parameters. #### Return Type ``` Struct { success: bool, } ``` #### Error Codes | Error Code | Description | | --- | --- | | 100 | Invalid parameter | | 200 | Permissions error | | 80004 | There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to /docs/graph-api/overview/rate-limiting#ads-management. | | 368 | The action attempted has been deemed abusive or is otherwise disallowed | --- --- # Ad Account Source: https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-account/aaa_compatible_ad_objects Mirror: https://nermalcat69.github.io/meta-developer-docs/documentation/ads-commerce/marketing-api/reference/ad-account/aaa_compatible_ad_objects.html # Ad Account Updated: May 6, 2026 Represents a business, person or other entity who creates and manages ads on Facebook. Multiple people can manage an account, and each person can have one or more levels of access to an account, see [Business Manager API](https://developers.facebook.com/docs/marketing-api/business-manager-api). In response to Apple's new policy, we are announcing breaking changes that will affect SDKAdNetwork, Marketing API and Ads Insights API endpoints. To learn more about how Apple's iOS 14.5 requirements will impact Facebook advertising, visit our Business Help Center aricles and changelog: * [Facebook SDK for iOS, App Events API and Mobile Measurement Partners Updates for Apple's iOS 14 Requirements⁠](https://www.facebook.com/business/help/2750680505215705?id=428636648170202) * [Facebook Pixel Updates for Apple's iOS 14 Requirements⁠](https://www.facebook.com/business/help/721422165168355) * [January 19, 2021 - Breaking Changes](https://developers.facebook.com/docs/graph-api/changelog/non-versioned-changes/jan-19-2021) The `agency_client_declaration` field requires [Admin privileges⁠](https://www.facebook.com/business/help/442345745885606?id=180505742745347) for all operations starting with v10.0 and will be required for all versions on May 25, 2021. ## Ad Volume You can view the volume of ads *running or in review* for your ad accounts. These ads will count against the ads limit per page that we will enact in early 2021. Query the number of ads running or in review for a given ad account. Ad Limit Per Page enforcement begins for when a Page reaches its ad limit enforcement date. Enforcement date can be queried [here](https://developers.facebook.com/documentation/ads-commerce/marketing-api/insights-api/ads-volume). When a Page is at its ad limit: * New ads (or ads scheduled to begin at that time) do not publish successfully. * Actions on existing ads are limited to pausing and archiving until the number of ads running or in review is below the ad limit. To see the ads volume for your ad account: ``` curl -G -d "access_token=" "https://graph.facebook.com//act_/ads_volume" ``` The response looks like this: ``` {"data":[{"ads_running_or_in_review_count":2}]} ``` For information on managing ads volume, see [About Managing Ad Volume⁠](https://www.facebook.com/business/help/2720085414702598). ### Running Or In Review To see if an ad is running or in review, we check `effective_status`, `configured_status`, and the ad account's status: * If an ad has `effective_status` of `1` - `active`, we consider it a *running* or *in review*. * If an ad has `configured_status` of `active` and `effective_status` of `9` - `pending review`, or `17` - `pending processing` we consider it a *running* or *in review*. * The ad can be *running* or *in review* only if the ad account status is in `1` - `active`, `8` - `pending settlement`, `9` - `in grace period`. We also determine if an ad is running or in review based on the ad set's schedule. * If start time is before current time, and current time is before end time, then we consider the ad running or in review. * If start time is before current time and the ad set has no end time, we also consider it running or in review. For example, if the ad set is scheduled to run in the future, the ads are not running or in review. However if the ad set is scheduled to run from now until three months from now, we consider the ads running or in review. If you are using special ads scheduling features, such as *day-parting*, we consider the ad running or in review the *whole day*, not just for the part of the day when the ad starts running. ### Breakdown By Actors We've added the `show_breakdown_by_actor` parameter to the `act_123/ads_volume` endpoint so you can query ad volume and ad limits-related information for each page. For more details, see [Breakdown by Actors](https://developers.facebook.com/documentation/ads-commerce/marketing-api/insights-api/ads-volume#breakdown-by-actors). --- ### Limits | Limit | Value | | --- | --- | | Maximum number of ad accounts per person | 25 | | Maximum number of people with access, per ad account | 25 | | Maximum number of ads per regular ad account | 6,000 non-archived non-deleted ads | | Maximum number of ads per bulk ad account | 50,000 non-archived non-deleted ads | | Maximum number of archived ads per ad account | 100,000 archived ads | | Maximum number of ad sets per regular ad account | 6,000 non-archived non-deleted ad sets | | Maximum number of ad sets per bulk ad account | 10,000 non-archived non-deleted ad sets | | Maximum number of archived ad sets per ad account | 100,000 archived ad sets | | Maximum number of ad campaigns per regular ad account | 6,000 non-archived non-deleted ad campaigns | | Maximum number of ad campaigns per bulk ad account | 10,000 non-archived non-deleted ad campaigns | | Maximum number of archived ad campaigns per ad account | 100,000 archived ad campaigns | | Maximum number of images per ad account | Unlimited | ## Reading An ad account is an account used for managing ads on Facebook ### Digital Services Act Saved Beneficiary/Payor Information Use the following code examples to download the beneficiary and payor information. #### Android SDK ``` GraphRequest request = GraphRequest.newGraphPathRequest( accessToken, "/act_", new GraphRequest.Callback() { @Override public void onCompleted(GraphResponse response) { // Insert your code here } }); Bundle parameters = new Bundle(); parameters.putString("fields", "default_dsa_payor,default_dsa_beneficiary"); request.setParameters(parameters); request.executeAsync(); iOS SDK FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc] initWithGraphPath:@"/act_" parameters:@{ @"fields": @"default_dsa_payor,default_dsa_beneficiary",} HTTPMethod:@"GET"]; [request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) { // Insert your code here }]; Javascript SDK: FB.api( '/act_', 'GET', {"fields":"default_dsa_payor,default_dsa_beneficiary"}, function(response) { // Insert your code here } ); ``` #### cURL ``` curl -X GET \ "https://graph.facebook.com/v25.0/act_?fields=default_dsa_payor%2Cdefault_dsa_beneficiary&access_token=" ``` The return value is in JSON format. For example: ``` {"default_dsa_payor":"payor2","default_dsa_beneficiary":"bene2","id":"act_426197654150180"} ``` #### Parameters This endpoint doesn't have any parameters. #### Fields | Field | Description | | --- | --- | | `id` *string* | The string `act_{ad_account_id}`. default | | `account_id` *numeric string* | The ID of the Ad Account. default | | `account_status` *unsigned int32* | Status of the account: `1 = ACTIVE` `2 = DISABLED` `3 = UNSETTLED` `7 = PENDING_RISK_REVIEW` `8 = PENDING_SETTLEMENT` `9 = IN_GRACE_PERIOD` `100 = PENDING_CLOSURE` `101 = CLOSED` `201 = ANY_ACTIVE` `202 = ANY_CLOSED` | | `ad_account_promotable_objects` *[AdAccountPromotableObjects](https://developers.facebook.com/docs/graph-api/reference/ad-account-promotable-objects)* | Ad Account creation request purchase order fields associated with this Ad Account. | | `age` *float* | Amount of time the ad account has been open, in days. | | `agency_client_declaration` *[AgencyClientDeclaration](https://developers.facebook.com/docs/marketing-api/reference/agency-client-declaration)* | Details of the agency advertising on behalf of this client account, if applicable. Requires Business Manager [Admin⁠](https://www.facebook.com/business/help/442345745885606?id=180505742745347) privileges. | | `amount_spent` *numeric string* | Current amount spent by the account with respect to `spend_cap`. Or total amount in the absence of `spend_cap`. See [why amount spent is different in ad account spending limit⁠](https://business.facebook.com/business/help/196476577203529?id=1792465934137726) for more info. | | `attribution_spec` *list* | **Deprecated due to iOS 14 changes.** Please visit the [changelog](https://developers.facebook.com/docs/graph-api/changelog/non-versioned-changes/jan-19-2021) for more information. | | `balance` *numeric string* | Bill amount due for this Ad Account. | | `brand_safety_content_filter_levels` *list* | Brand safety content filter levels set for in-content ads (Facebook in-stream videos and Ads on Facebook Reels) and Audience Network along with feed ads (Facebook Feed, Instagram feed, Facebook Reels feed and Instagram Reels feed) if applicable. Refer to [Placement Targeting](https://developers.facebook.com/documentation/ads-commerce/marketing-api/audiences/reference/placement-targeting#placement-targeting) for a list of supported values. | | `business` *[Business](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/business)* | The [Business Manager](https://developers.facebook.com/docs/marketing-api/businessmanager), if this ad account is owned by one | | `business_city` *string* | City for business address | | `business_country_code` *string* | Country code for the business address | | `business_name` *string* | The business name for the account | | `business_state` *string* | State abbreviation for business address | | `business_street` *string* | First line of the business street address for the account | | `business_street2` *string* | Second line of the business street address for the account | | `business_zip` *string* | Zip code for business address | | `can_create_brand_lift_study` *bool* | If we can create a new automated brand lift study under the Ad Account. | | `capabilities` *list* | List of capabilities an Ad Account can have. See [capabilities](https://developers.facebook.com/docs/marketing-api/reference/ad-account/capabilities) | | `created_time` *datetime* | The time the account was created in ISO 8601 format. | | `currency` *string* | The currency used for the account, based on the corresponding value in the account settings. See [supported currencies](https://developers.facebook.com/documentation/ads-commerce/marketing-api/currencies) | | `default_dsa_beneficiary` *string* | This is the default value for creating L2 object of dsa\_beneficiary | | `default_dsa_payor` *string* | This is the default value for creating L2 object of dsa\_payor | | `direct_deals_tos_accepted` *bool* | Whether DirectDeals ToS are accepted. | | `disable_reason` *unsigned int32* | The reason why the account was disabled. Possible reasons are: `0 = NONE` `1 = ADS_INTEGRITY_POLICY` `2 = ADS_IP_REVIEW` `3 = RISK_PAYMENT` `4 = GRAY_ACCOUNT_SHUT_DOWN` `5 = ADS_AFC_REVIEW` `6 = BUSINESS_INTEGRITY_RAR` `7 = PERMANENT_CLOSE` `8 = UNUSED_RESELLER_ACCOUNT` `9 = UNUSED_ACCOUNT` `10 = UMBRELLA_AD_ACCOUNT` `11 = BUSINESS_MANAGER_INTEGRITY_POLICY` `12 = MISREPRESENTED_AD_ACCOUNT` `13 = AOAB_DESHARE_LEGAL_ENTITY` `14 = CTX_THREAD_REVIEW` `15 = COMPROMISED_AD_ACCOUNT` | | `end_advertiser` *numeric string* | The entity the ads will target. Must be a Facebook Page Alias, Facebook Page ID or an Facebook App ID. | | `end_advertiser_name` *string* | The name of the entity the ads will target. | | `existing_customers` *list* | The custom audience ids that are used by advertisers to define their existing customers. This definition is primarily used by Automated Shopping Ads. | | `expired_funding_source_details` *[FundingSourceDetails](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-account)* | `ID` = ID of the payment method `COUPON` = Details of the Facebook Ads Coupon from the payment method `COUPONS` = List of active Facebook Ads Coupon from the ad account `COUPON_ID` = ID of the Facebook Ads Coupon `AMOUNT` = Amount of Facebook Ads Coupon `CURRENCY` = Currency of the Facebook Ads Coupon `DISPLAY_AMOUNT` = How the amount of Facebook Ads Coupon is displayed `EXPIRATION` = When the coupon expired `START_DATE` = When the coupon started `DISPLAY_STRING` = How the payment method is shown `CAMPAIGN_IDS` = List of campaigns the coupon can be applied to, empty if the coupon is applied on the ad account level. `ORIGINAL_AMOUNT` = Amount of Facebook Ads Coupon When Issued `ORIGINAL_DISPLAY_AMOUNT` = How the Facebook Ads Coupon displayed When Issued `TYPE` = Type of the funding source `0 = UNSET` `1 = CREDIT_CARD` `2 = FACEBOOK_WALLET` `3 = FACEBOOK_PAID_CREDIT` `4 = FACEBOOK_EXTENDED_CREDIT` `5 = ORDER` `6 = INVOICE` `7 = FACEBOOK_TOKEN` `8 = EXTERNAL_FUNDING` `9 = FEE` `10 = FX` `11 = DISCOUNT` `12 = PAYPAL_TOKEN` `13 = PAYPAL_BILLING_AGREEMENT` `14 = FS_NULL` `15 = EXTERNAL_DEPOSIT` `16 = TAX` `17 = DIRECT_DEBIT` `18 = DUMMY` `19 = ALTPAY` `20 = STORED_BALANCE` To access this field, the user making the API call must have a `MANAGE` task permission for that specific ad account. See [Ad Account, Assigned Users](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-account/assigned_users) for more information. | | `extended_credit_invoice_group` *[ExtendedCreditInvoiceGroup](https://developers.facebook.com/docs/marketing-api/reference/extended-credit-invoice-group)* | The extended credit invoice group that the ad account belongs to | | `failed_delivery_checks` *[list](https://developers.facebook.com/docs/marketing-api/adgroup/deliverychecks)* | Failed delivery checks | | `fb_entity` *unsigned int32* | fb\_entity | | `funding_source` *numeric string* | ID of the payment method. If the account does not have a payment method it will still be possible to create ads but these ads will get no delivery. Not available if the account is disabled | | `funding_source_details` *[FundingSourceDetails](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-account)* | `ID` = ID of the payment method `COUPON` = Details of the Facebook Ads Coupon from the payment method `COUPONS` = List of active Facebook Ads Coupon from the ad account `COUPON_ID` = ID of the Facebook Ads Coupon `AMOUNT` = Amount of Facebook Ads Coupon `CURRENCY` = Currency of the Facebook Ads Coupon `DISPLAY_AMOUNT` = How the amount of Facebook Ads Coupon is displayed `EXPIRATION` = When the coupon will expire `START_DATE` = When the coupon starts `DISPLAY_STRING` = How the payment method is shown `CAMPAIGN_IDS` = List of campaigns the coupon can be applied to, empty if the coupon is applied on the ad account level. `ORIGINAL_AMOUNT` = Amount of Facebook Ads Coupon When Issued `ORIGINAL_DISPLAY_AMOUNT` = How the Facebook Ads Coupon displayed When Issued `TYPE` = Type of the funding source `0 = UNSET` `1 = CREDIT_CARD` `2 = FACEBOOK_WALLET` `3 = FACEBOOK_PAID_CREDIT` `4 = FACEBOOK_EXTENDED_CREDIT` `5 = ORDER` `6 = INVOICE` `7 = FACEBOOK_TOKEN` `8 = EXTERNAL_FUNDING` `9 = FEE` `10 = FX` `11 = DISCOUNT` `12 = PAYPAL_TOKEN` `13 = PAYPAL_BILLING_AGREEMENT` `14 = FS_NULL` `15 = EXTERNAL_DEPOSIT` `16 = TAX` `17 = DIRECT_DEBIT` `18 = DUMMY` `19 = ALTPAY` `20 = STORED_BALANCE` To access this field, the user making the API call must have a `MANAGE` task permission for that specific ad account. See [Ad Account, Assigned Users](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-account/assigned_users) for more information. | | `has_migrated_permissions` *bool* | Whether this account has migrated permissions | | `has_page_authorized_adaccount` *bool* | Indicates whether a Facebook page has authorized this ad account to place ads with political content. If you try to place an ad with political content using this ad account for this page, and this page has not authorized this ad account for ads with political content, your ad will be disapproved. See [Breaking Changes, Marketing API, Ads with Political Content](https://developers.facebook.com/docs/graph-api/changelog/breaking-changes#4-23-2018) and [Facebook Advertising Policies⁠](https://www.facebook.com/policies/ads) | | `io_number` *numeric string* | The Insertion Order (IO) number. | | `is_attribution_spec_system_default` *bool* | If the attribution specification of ad account is generated from system default values | | `is_direct_deals_enabled` *bool* | Whether the account is enabled to run Direct Deals | | `is_in_3ds_authorization_enabled_market` *bool* | If the account is in a market requiring to go through payment process going through 3DS authorization | | `is_notifications_enabled` *bool* | Get the notifications status of the user for this ad account. This will return true or false depending if notifications are enabled or not | | `is_personal` *unsigned int32* | Indicates if this ad account is being used for private, non-business purposes. This affects how value-added tax (VAT) is assessed. **Note:** This is not related to whether an ad account is attached to a business. | | `is_prepay_account` *bool* | If this ad account is a prepay. Other option would be a postpay account. To access this field, the user making the API call must have a `ADVERTISE` or `MANAGE` task permission for that specific ad account. See [Ad Account, Assigned Users](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-account/assigned_users) for more information. | | `is_tax_id_required` *bool* | If tax id for this ad account is required or not. To access this field, the user making the API call must have a `ADVERTISE` or `MANAGE` task permission for that specific ad account. See [Ad Account, Assigned Users](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-account/assigned_users) for more information. | | `line_numbers` *list* | The line numbers | | `media_agency` *numeric string* | The agency, this could be your own business. Must be a Facebook Page Alias, Facebook Page ID or an Facebook App ID. In absence of one, you can use `NONE` or `UNFOUND`. | | `min_campaign_group_spend_cap` *numeric string* | The minimum required spend cap of Ad Campaign. | | `min_daily_budget` *unsigned int32* | The minimum daily budget for this Ad Account | | `name` *string* | Name of the account. If not set, the name of the first admin visible to the user will be returned. | | `offsite_clo_signal_status` *int32* | offsite\_clo\_signal\_status | | `offsite_pixels_tos_accepted` *bool* | Indicates whether the offsite pixel Terms Of Service contract was signed. This feature can be accessible before v2.9 | | `opportunity_score` *float* | On a 0-100 point scale, this score represents how optimized the ad account's campaigns, ad sets and ads are overall. See [Opportunity Score⁠](https://web.facebook.com/business/tools/opportunity-score) to learn more. | | `opportunity_score_weight` *integer* | This opportunity score weight represent the remaining budget for the ad account in cents, computed daily. This can be used with other ad accounts within the same business to compute the weighted opportunity score for a business. See [Opportunity Score⁠](https://web.facebook.com/business/tools/opportunity-score) to learn more about opportunity score. | | `owner` *numeric string* | The ID of the account owner | | `partner` *numeric string* | This could be Facebook Marketing Partner, if there is one. Must be a Facebook Page Alias, Facebook Page ID or an Facebook App ID. In absence of one, you can use `NONE` or `UNFOUND`. | | `rf_spec` *ReachFrequencySpec* | Reach and Frequency limits configuration. [See Reach and Frequency](https://developers.facebook.com/docs/marketing-api/reachandfrequency) | | `show_checkout_experience` *bool* | Whether or not to show the pre-paid checkout experience to an advertiser. If `true`, the advertiser is eligible for checkout, or they are already locked in to checkout and haven't graduated to postpay. | | `spend_cap` *numeric string* | The maximum amount that can be spent by this Ad Account. When the amount is reached, all delivery stops. A value of `0` means no spending-cap. Setting a new spend cap only applies to spend **AFTER** the time at which you set it. Value specified in basic unit of the currency, for example 'cents' for `USD`. | | `tax_id` *string* | Tax ID | | `tax_id_status` *unsigned int32* | VAT status code for the account. `0`: Unknown `1`: VAT not required- US/CA `2`: VAT information required `3`: VAT information submitted `4`: Offline VAT validation failed `5`: Account is a personal account | | `tax_id_type` *string* | Type of Tax ID | | `timezone_id` *unsigned int32* | The [timezone ID](https://developers.facebook.com/docs/marketing-api/reference/ad-account/timezone-ids) of this ad account | | `timezone_name` *string* | Name for the time zone | | `timezone_offset_hours_utc` *float* | Time zone difference from UTC (Coordinated Universal Time). | | `tos_accepted` *map* | Checks if this specific ad account has signed the Terms of Service contracts. Returns `1`, if terms were accepted. | | `user_tasks` *list* | user\_tasks | | `user_tos_accepted` *map* | Checks if a user has signed the Terms of Service contracts related to the Business that contains a specific ad account. Must include user's access token to get information. This verification is not valid for [system users](https://developers.facebook.com/docs/marketing-api/businessmanager/systemuser). | #### Edges | Edge | Description | | --- | --- | | [`account_controls`](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-account/account_controls) *Edge* | Account Controls is for Advantage+ shopping campaigns where advertisers can set audience controls for minimum age and excluded geo location. | | [`activities`](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-account/activities) *Edge* | The activities of this ad account | | [`adcreatives`](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-account/adcreatives) *Edge* | The ad creatives of this ad account | | [`ads_reporting_mmm_reports`](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-account/ads_reporting_mmm_reports) *Edge* | Marketing mix modeling (MMM) reports generated for this ad account. | | [`ads_reporting_mmm_schedulers`](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-account/ads_reporting_mmm_schedulers) *Edge* | Get all MMM report schedulers by this ad account | | [`advertisable_applications`](https://developers.facebook.com/docs/marketing-api/reference/ad-account/advertisable_applications)  *Edge* | All advertisable apps associated with this account | | [`advideos`](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ad-account/advideos) *Edge