There are a number of resources that developers should use to supplement the Ads API docs. We recommend that developers review the documentation for Twitter advertisers using ads.twitter.com. These docs cover core concepts of advertising on Twitter and provide insight into the expectations your advertisers will have based on previous experience advertising on Twitter. We also recommend that Ads API developers familiarize themselves with the public Twitter API documentation.

The Twitter developer forums are another valuable resource containing conversations about developing on Twitter. Search over the repository or communicate with other developers building on the Advertising API.
 

Using the API

The Advertising API is accessed on https://ads-api.twitter.com. The standard REST API, and the Advertising API can be used together with the same client app. The Advertising API enforces HTTPS, therefore attempts to access an endpoint with HTTP will result in an error message.

The Ads API outputs JSON. All identifiers are strings and all strings are UTF-8. The Advertising API is versioned (currently version “six”) and the version is specified as the first path element of any resource URL. For example, version six is represented in this URL as the first “six” path element you see:

https://ads-api.twitter.com/6/accounts
 

HTTP & OAuth

Like Twitter REST API v1.1, the Advertising API requires the use of both OAuth 1.0A and HTTPS. API keys can be obtained through the app management console. Access tokens must also be used to represent the “current user.” The current user is a Twitter account with advertising capabilities.

It is strongly recommended that partners use an OAuth library, rather than writing your own. We can support debugging when using a known library, but cannot if you roll your own OAuth implementation. See the libraries that you can use.

The API is strict with HTTP 1.1 and OAuth. Ensure that you’re encoding reserved characters appropriately within URLs and POST bodies before preparing OAuth signature base strings. The Advertising API in particular uses ”:” characters when specifying time and ”,” characters when providing a collection of options. Both characters are among this reserved set:

Accounts

There are two different types of accounts involved in using the Ads API: advertising accounts and Twitter user accounts. Within this documentation, the term “account” refers to the advertising account.

• Advertising accounts are registered on ads.twitter.com and identified in the API by account_id. Advertising accounts link directly to funding sources and leverage content from one or more Twitter user accounts as ‘promotable users’. Each advertising account can grant permission to one or more Twitter user accounts. The advertising account, or “current account,” is represented in nearly every URL executed as an in-line :account_id parameter.
• Twitter user accounts (such as @AdsAPI) are identified by user_id in the Ads API. One or more of these accounts can be associated with an advertising account. The authenticated Twitter user account making requests on the API is referred to as the ‘current user.’ A listing of advertising accounts that the current user has access to can be found with GET accounts. ‘Promotable users’ are Twitter handles that can be promoted by a specific advertising account. For more details about this, see Obtaining Ads Account Access.
   

HTTP verbs & typical response codes

There are four HTTP verbs used in the Ads API:

• GET retrieves data 
• POST creates new data, such as campaigns
• PUT updates existing data, like line items
• DELETE removes data.

While deletions are permanent, deleted data can still be viewed from most GET-based methods by including an explicit with_deleted=true parameter when asking for the resource. Otherwise, deleted records will return a HTTP 404.

A successful request will return a HTTP 200-series response along with the JSON response representing the object when creating, deleting, or updating a resource.

When updating data with HTTP PUT, only the specified fields will be updated. You can un-set an optional value by specifying the parameter with an empty string. As an example, this group of parameters would unset any already specified end_time: &end_time=&paused=false.

See Error Codes & Responses for more details on error responses.
 

Rate limits

Information on our rate limiting has been moved from this doc to our Ads API Rate Limiting overview.
 

In-line parameters

Most resource URLs feature one or more in-line parameter. Many URLs also take explicitly declared parameters on the query string or, for POST or PUT requests, in the body.

In-line parameters are denoted with a pre-pended colon (”:”) in the Resource Path section of each resource. For example, if the account you were working on were identified as "abc1" and you were retrieving the campaigns associated with an account, you would access that list by using the URL https://ads-api.twitter.com/6/accounts/abc1/campaigns. By specifying the in-line account_id parameter described in the resource URL (https://ads-api.twitter.com/6/accounts/:account_id/campaigns), you’ve scoped the request to objects associated only with that account.
 

Time

Datetime values are always returned in UTC time (as indicated by the Z at the end of the datetime value.) Datetimes may be specified in any timezone in a POST or PUT command using the ISO 8601 standard format for timezone. Time is represented using a subset of ISO-8601. More specifically, the strptime string for our date format is "%Y-%m-%dT%l:%M:%S%z".

For more information on how time is treated in the API, see Timezones.
 

Currency

The type of a currency is identified using ISO-4217. This is a three-letter string like “USD” or “EUR”. The value of a currency is represented in micros. For USD, $5.50 is encoded as 5.50*1e6, or 5,500,000. To represent a “whole value”, you need to multiply the local micro by 1e6 (1_000_000) for all currencies.

The Ads API recognizes official currencies of all countries where the Twitter SMB Ads product is available. For a complete list of these countries, please click here.

Most currencies have a “precision” of two (like USD: $1.23).

• AED, VEF, PKR, IDR, HKD, QAR, PHP, NZD, INR, EUR, ARS, THB, MXN, EGP, DZD, SAR, LBP, COP, TRY, SGD, MAD, AUD, USD, MYR, CAD, BRL, GBP.

The following currencies don’t use a decimal:

• VND, KRW, CLP, JPY

And these use three decimal places:

• KWD, IQD, BHD, TND

The usage of currency is accomplished through funding instruments.
 

Localization

Some endpoints support localization of names within the Ads API. Endpoints with the lang parameters support passing a ISO 639-1 language code in order to get localized data returned, in addition to the standard data object.
 

Sandbox

The sandbox Advertising API is available at https://ads-api-sandbox.twitter.com. You can perform actions here on most Advertising API resources by replacing the host component of the URI to be executed. When making an initial request to POST accounts in the sandbox, an account record will be generated for you from which you can perform the remainder of your operations. Data within the sandbox is subject to occasional reset. The accounts, campaigns, and line items within the sandbox are unique to the “current user.”