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/4/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 will be ignored if cursor is specified.

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/4/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/4/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/4/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/4/accounts

Parameters

None

Example Request

POST https://ads-api-sandbox.twitter.com/4/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/4/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/4/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/4/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/4/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"
    }
  }
}