Promoted Accounts
promoted-accounts

Promoted Accounts

Run in Postman ❯ 

GET accounts/:account_id/promoted_accounts

Retrieve details for some or all promoted accounts associated with one or more line items under the current account.

Use GET users/lookup to obtain user data for the user accounts identified by user_id in the response.

An HTTP 400 will be returned if none of the specified line items are configured to contain promoted accounts.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_accounts

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
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
line_item_ids
optional

Scope the response to just the promoted accounts associated with the specified line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: 9bpb2
promoted_account_ids
optional

Scope the response to just the desired promoted accounts by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: 19pl2
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.x.com/12/accounts/18ce54d4x5t/promoted_accounts?promoted_account_ids=19pl2

Example Response

{
  "request": {
    "params": {
      "promoted_account_ids": [
        "19pl2"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "line_item_id": "9bpb2",
      "user_id": "756201191646691328",
      "id": "19pl2",
      "entity_status": "ACTIVE",
      "created_at": "2017-07-05T05:54:13Z",
      "updated_at": "2017-07-05T05:54:13Z",
      "approval_status": "ACCEPTED",
      "deleted": false
    }
  ]
}

GET accounts/:account_id/promoted_accounts/:promoted_account_id

Retrieve a specific reference to an account associated with a line item under the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_accounts/:promoted_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
promoted_account_id
required

A reference to the promoted account you are operating with in the request.

Type: string

Example: 19pl2
with_deleted
optional

Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts/19pl2

Example Response

{
  "request": {
    "params": {
      "promoted_account_id": "19pl2",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "line_item_id": "9bpb2",
    "user_id": "756201191646691328",
    "id": "19pl2",
    "entity_status": "ACTIVE",
    "created_at": "2017-07-05T05:54:13Z",
    "updated_at": "2017-07-05T05:54:13Z",
    "approval_status": "ACCEPTED",
    "deleted": false
  }
}

POST accounts/:account_id/promoted_accounts

Associate an account (user_id) with the specified line item.

If the specified line item is not configured to be associated with Promoted Accounts, a HTTP 400 INCOMPATIBLE_LINE_ITEM error will be returned. If the specified user is ineligible for promotion, a HTTP 400 will be returned and no users will be promoted. If the provided user is already promoted, the request will be ignored.

For more information on Promoted Accounts, see our campaign management page.

Note: It is not possible to update (PUT) promoted accounts entities.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_accounts

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
line_item_id
required

A reference to the line item you are operating with in the request.

Type: string

Example: 9bpb2
user_id
required

A reference to the user you are operating with in the request. Use GET users/lookup to retrieve a user ID for a screen name.

Type: long

Example: 756201191646691328

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts?line_item_id=9bpb2&user_id=756201191646691328

Example Response

{
  "data": {
    "line_item_id": "9bpb2",
    "user_id": "756201191646691328",
    "id": "19pl2",
    "entity_status": "ACTIVE",
    "created_at": "2017-07-05T05:54:13Z",
    "updated_at": "2017-07-05T05:54:13Z",
    "approval_status": "ACCEPTED",
    "deleted": false
  },
  "request": {
    "params": {
      "user_id": "756201191646691328",
      "line_item_id": "9bpb2",
      "account_id": "18ce54d4x5t"
    }
  }
}

DELETE accounts/:account_id/promoted_accounts/:promoted_account_id

Disassociate an account from the specified line item.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_accounts/:promoted_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
promoted_account_id
required

The identifier refers to the instance of a Promoted Account associated with a line item.

Type: string

Example: 19pl2

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts/19pl2

Example Response

{
  "data": {
    "line_item_id": "9bpb2",
    "user_id": "756201191646691328",
    "id": "19pl2",
    "entity_status": "ACTIVE",
    "created_at": "2017-07-05T05:54:13Z",
    "updated_at": "2017-08-23T18:53:15Z",
    "approval_status": "ACCEPTED",
    "deleted": true
  },
  "request": {
    "params": {
      "promoted_account_id": "19pl2",
      "account_id": "18ce54d4x5t"
    }
  }
}