The Meta Business SDK is a toolkit that simplifies how you interact with a suite of Facebook's business-focused APIs. It is an upgraded version of the Marketing API SDK that includes Marketing API as well as many Meta APIs from different platforms such as Pages, Business Manager, Instagram, etc.

The Marketing API SDK is specifically for ads, which helps you to integrate with Marketing API and manage your Meta ads much easier.

Before implementing the SDK you will need:

  • A Meta Developer Account
  • An Meta App ID
  • An Meta App Secret
  • A Facebook Page Access Token
  • An Meta Ad Account

Learn more about these prerequisites in the Getting Started Guide for the Meta Business SDK.

You can download the SDK from Github, or one of the package management systems your language uses. We provide a composer for PHP, Mavin for Java, pypi for Python, gem for Ruby, and npm for Nodejs, as following:

If the endpoint is supported in latest API version but not supported in SDK, you could report it on Github. We will have bump up versions, such as v3.0.1, to enable some high demand requests.

Yes, you need to connect your Page to your app so your app has the ability to access certain Pages API endpoints.

You can add CurlLogger at the beginning of your class to allow the terminal to print the curl request when you run an SDK function call. If the curl request is incorrect, for example, you see a totally different curl request for the exact same parameters on the same endpoint from Graph API Explorer tool, then please help file a bug in Github. Different languages might have different syntax to add the logger so please refer to the Github Readme file or sample code to see how to implement the logger.

You cannot. The Meta Business SDK started with v3.0.

The Meta Business SDK includes some endpoints that are still in beta, such as the Instagram Content Publishing APIs and Solution to Onboarding Clients at Scale APIs. You need to get your app approved for those beta version endpoints before you can use the related SDK functions successfully. Learn more about available endpoints in the Graph API Reference docs.


To begin troubleshooting, please enable debugging in the APIContext file.

There are many possible causes for a failed request:

  • Incorrect parameters in the API Request

    If it's caused by incorrect parameters, you'll see error descriptions in the exception message. Check Graph API Docs to get more information about error codes and error handling.

  • Permission Issue

    If it's caused by permission issue, you'll see error messages like "permission denied" or "unknown path". Check your access token or app secret to make sure the needed permissions are included.

  • SDK Bug

    If in stacktrace you see that the failed request is caused by exceptions such as NullPointerException or MalformedResponseException, it is likely an SDK bug (or your own bug, depending on the stacktrace). If you see in the debug message that the params sent to the server don't match what you specified, it is possible that you didn't specify the param correctly, or the SDK didn't assemble the request properly. If it is an SDK bug, please help report it on Facebook Platform Bugs. Thanks!

  • Temporary Network Issue

    Check your network and retry.

  • Temporary Server Issue

    For a temporary server issue, typically retry should work after a few seconds. You could retry, or report the issue at Facebook Platform Bugs if it happens too often.

  • Server bug

    If the server persistently responds with "Unknown error," then it is potentially a server bug. Please help report it on Meta Platform Bugs. Thanks!