Getting Started

How to get access to the Ads API

  1. Sign up for a developer account and subscribe to one of our access plans.
  2. Create a developer App and secure your token.
  3. Visit ads.x.com/help to submit a request for Ads API access for each of your developer app(s).

Note:  If you are already building on the X Developer Platform and have a developer account, skip to step three.

Step one: Signup for a developer account

To make a request to any of X's API products, you must first sign up for a developer account. Within the developer portal, create a Project and developer App. This will provide you a set of credentials that you will use to authenticate all requests to the API. 

Sign up for a developer account


Step two: Save your App's key and tokens and keep them secure

Within your developer App, you will be provided a set of API Keys (also known as Consumer Keys). You will also have the chance to generate a set of Access Tokens that can be used to make requests on behalf of your personal X account, and a Bearer Token that can be used to authenticate endpoints that require OAuth 2.0 Bearer Token. As these keys and tokens do not expire unless regenerated, we suggest creating environment variables, or using a secure password manager.

Please also take note of your App ID, which can be found in the URL of your App details. This will make it easier to request access to the Ads API in the next step.

Please note: Your keys and tokens will only display once in the developer portal, so it is important that you store these credentials in your password management system as soon as you generate them.

If you misplace or forget the keys and tokens, you will need to regenerate them, which creates new keys and tokens, and invalidates the old ones. This means that you will have to update any integrations that you may have set up with your prior credentials.

Learn more about our authentication best practices. 

Step three: Apply for access to the Ads API

At this point you will have basic access to the X API, but not specific Twitter Ads API functionality. Next, you will need to request access and be approved for Ads API access. Visit ads.x.com/help to submit a request for Ads API access for each of your developer app(s).

Access tiers

As part of the application process, you'll need to specify what level of access you require. Learn more about App-level and Ad Account-level permissions.

Conversion Only

Access to Mobile and Web Conversion endpoints with read & write access.

Standard Access

Access to Analytics, Campaign Management, Creatives, Custom Audiences, and Conversion endpoints with read & write access.

Note: After your app is approved for Ads API access, you will need to regenerate any user access tokens to make properly authenticated Ads API requests.

 

Note: Ads API developers who requested access prior to July 2023 may have different levels of access and permissions, and may be limited to five OAuth tokens. See our guide on increasing access to access to additional endpoints or lift token limits for existing applications.

Make your first request

To test your access to the Ads API make a request to the GET accounts endpoint. This endpoint will return the ad accounts the currently authorized user has access to. Use the ad account IDs from this request in subsequent API requests to read and write data for a specific ad account. Using Twurl on the command line the request would look like the following.

Example Request

      twurl -H ads-api.x.com "/11/accounts"

Example Response

      {
  "request": {
    "params": {}
  },
  "data": [
   {
    "name": "Furni",
    "business_name": null,
    "timezone": "America/Los_Angeles",
    "timezone_switch_at": "2016-04-06T07:00:00Z",
    "id": "18ce54ayf0z",
    "created_at": "2016-04-07T14:40:15Z",
    "salt": "b88939e5cabbca720159cb3659d73c06",
    "updated_at": "2017-02-08T08:49:53Z",
    "business_id": null,
    "approval_status": "ACCEPTED",
    "deleted": false
     }
   ]
}

 

Up next . . .