Campaign Management

Accounts

GET accounts

Retrieve details for some or all advertising-enabled accounts the authenticating user has access to.

Resource URL

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

Parameters

Name Description
account_ids
optional
 Scope the response to just the desired account IDs by specifying a comma-separated list of identifiers.

Type: string

Example: 18ce54d4x5t
count
optional
 Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
optional
 Specifies a cursor to get the next page of results. See Pagination for more information.

Type: string

Example: 8x7v00oow
sort_by
optional
 Sorts by supported attribute in ascending or descending order. See Sorting for more information.

Type: string

Example: created_at-asc
with_deleted
optional
 Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false
with_total_count
optional
 Include the total_count response attribute.

Note: This parameter and cursor are exclusive.

Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.twitter.com/5/accounts?account_ids=18ce54d4x5t

Example Response

   {
     "request": {
       "params": {
         "account_ids": [
           "18ce54d4x5t"
         ]
       }
     },
     "next_cursor": null,
     "data": [
       {
         "name": "API McTestface",
         "business_name": null,
         "timezone": "America/Los_Angeles",
         "timezone_switch_at": "2016-07-21T07:00:00Z",
         "id": "18ce54d4x5t",
         "created_at": "2016-07-21T22:42:09Z",
         "salt": "54cb7b5a34183f77d82dd6d0f4329691",
         "updated_at": "2017-07-06T16:51:04Z",
         "business_id": null,
         "approval_status": "ACCEPTED",
         "deleted": false
       }
     ]
   }

GET accounts/:account_id

Retrieve a specific account that the authenticating user has access to.

Resource URL

https://ads-api.twitter.com/5/accounts/:account_id

Parameters

Name Description
account_id
required
 The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts.

The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
with_deleted
optional
 Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.twitter.com/5/accounts/18ce54d4x5t

Example Response

   {
     "request": {
       "params": {
         "account_id": "18ce54d4x5t"
       }
     },
     "data": {
       "name": "API McTestface",
       "business_name": null,
       "timezone": "America/Los_Angeles",
       "timezone_switch_at": "2016-07-21T07:00:00Z",
       "id": "18ce54d4x5t",
       "created_at": "2016-07-21T22:42:09Z",
       "salt": "54cb7b5a34183f77d82dd6d0f4329691",
       "updated_at": "2017-07-06T16:51:04Z",
       "industry_type": "TRAVEL",
       "business_id": null,
       "approval_status": "ACCEPTED",
       "deleted": false
     }
   }

POST accounts

SANDBOX ONLY

Create an ads account in the sandbox environment.

Resource URL

https://ads-api-sandbox.twitter.com/5/accounts

Parameters

None

Example Request

POST https://ads-api-sandbox.twitter.com/5/accounts

Example Response

   {
     "request": {
       "params": {}
     },
     "next_cursor": null,
     "data": [
       {
         "name": "Sandbox account",
         "business_name": null,
         "timezone": "America/Los_Angeles",
         "timezone_switch_at": null,
         "id": "gq12fh",
         "created_at": "2016-07-18T23:02:20Z",
         "salt": "d65f6e581bdd6a370f9db2efe18a0cbd",
         "updated_at": "2016-07-18T23:02:20Z",
         "business_id": null,
         "approval_status": "ACCEPTED",
         "deleted": false
       }
     ]
   }

PUT accounts/:account_id

Updates the account name and/or industry type.

Resource URL

https://ads-api.twitter.com/5/accounts/:account_id

Parameters

Name Description
account_id
required
 The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts.
The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
account_name
optional
 The name of account.

Type: string

Example: API McTestface
industry_type
optional
 Industry that the account is associated with.

Type: string

Possible values: AGENCY, BUSINESS_TO_BUSINESS, ONLINE_SERVICES, EDUCATION, FINANCIAL, HEALTH, GOVERNMENT, MEDIA, MOBILE, RESTAURANT, RETAIL, TECHNOLOGY, TRAVEL, OTHER

Example Request

PUT https://ads-api.twitter.com/5/accounts/18ce54d4x5t?account_name='API McTestface 2'&industry_type=TECHNOLOGY

Example Response

   {
     "request": {
       "params": {
         "account_id": "18ce54d4x5t"
         "account_name"": "API McTestface 2",
         "industry_type": "TECHNOLOGY"
       }
     },
     "data": {
       "name": "API McTestface 2",
       "business_name": null,
       "timezone": "America/Los_Angeles",
       "timezone_switch_at": "2016-07-21T07:00:00Z",
       "id": "18ce54d4x5t",
       "created_at": "2016-07-21T22:42:09Z",
       "salt": "54cb7b5a34183f77d82dd6d0f4329691",
       "updated_at": "2017-07-06T16:51:04Z",
       "industry_type": "TECHNOLOGY",
       "business_id": null,
       "approval_status": "ACCEPTED",
       "deleted": false
     }
   }

DELETE accounts/:account_id

SANDBOX ONLY

Delete an ads account in the sandbox environment.

Resource URL

https://ads-api-sandbox.twitter.com/5/accounts/:account_id

Parameters

Name Description
account_id
required
 The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts.

The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t

Example Request

DELETE https://ads-api-sandbox.twitter.com/5/accounts/gq12fh

Example Response

   {
     "data": {
       "name": "Sandbox account",
       "timezone": "America/Los_Angeles",
       "timezone_switch_at": null,
       "id": "gq12fh",
       "created_at": "2016-07-18T23:02:20Z",
       "salt": "d65f6e581bdd6a370f9db2efe18a0cbd",
       "updated_at": "2017-08-23T18:21:10Z",
       "approval_status": "ACCEPTED",
       "deleted": true
     },
     "request": {
       "params": {
         "account_id": "gq12fh"
       }
     }
   }