Preroll Call To Actions
preroll-call-to-actions

Preroll Call To Actions

GET accounts/:account_id/preroll_call_to_actions

Retrieve details for some or all preroll Call-To-Actions (CTAs) associated with line items under the current account.

Resource URL

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

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

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

Type: string

Example: 8v53k

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

preroll_call_to_action_ids
optional

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

Type: string

Example: 8f0

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/preroll_call_to_actions?line_item_ids=8v53k

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "line_item_ids": [
        "8v53k"
      ]
    }
  },
  "next_cursor": null,
  "data": [
    {
      "line_item_id": "8v53k",
      "call_to_action_url": "https://www.twitter.com",
      "call_to_action": "VISIT_SITE",
      "id": "8f0",
      "created_at": "2017-07-07T19:28:40Z",
      "updated_at": "2017-07-07T19:28:40Z",
      "deleted": false
    }
  ]
}

GET accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id

Retrieve a specific Call-to-Action (CTAs) associated with this account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_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

preroll_call_to_action_id
required

A reference to the preroll call to action you are operating with in the request.

Type: string

Example: 8f0

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/preroll_call_to_actions/8f0

Example Response

{
  "request": {
    "params": {
      "preroll_call_to_action_id": "8f0",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "line_item_id": "8v53k",
    "call_to_action_url": "https://www.twitter.com",
    "call_to_action": "VISIT_SITE",
    "id": "8f0",
    "created_at": "2017-07-07T19:28:40Z",
    "updated_at": "2017-07-07T19:28:40Z",
    "deleted": false
  }
}

POST accounts/:account_id/preroll_call_to_actions

Set the optional Call-to-Action (CTA) for a PREROLL_VIEWS line item.

Resource URL

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

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

call_to_action
required

The CTA text for the displayed button within the ad.

Type: enum

Possible values: GO_TO, SEE_MORE, SHOP, VISIT_SITE, WATCH_NOW

call_to_action_url
required

The URL to redirect the user to when the CTA button is clicked.

Type: string

Example: https://www.twitter.com

line_item_id
required

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

Type: string

Example: 8v53k

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions?line_item_id=8v53k&call_to_action=VISIT_SITE&call_to_action_url=https://www.twitter.com

Example Response

{
  "data": {
    "line_item_id": "8v53k",
    "call_to_action_url": "https://www.twitter.com",
    "call_to_action": "VISIT_SITE",
    "id": "8f0",
    "created_at": "2017-07-07T19:28:40Z",
    "updated_at": "2017-07-07T19:28:40Z",
    "deleted": false
  },
  "request": {
    "params": {
      "line_item_id": "8v53k",
      "call_to_action": "VISIT_SITE",
      "call_to_action_url": "https://www.twitter.com",
      "account_id": "18ce54d4x5t"
    }
  }
}

PUT accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id

Update the optional Call-to-Action (CTA) for a PREROLL_VIEWS line item.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_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

preroll_call_to_action_id
required

A reference to the preroll CTA you are operating with in the request.

Type: string

Example: 8f0

call_to_action
optional

The CTA text for the displayed button within the ad.

Type: enum

Possible values: GO_TO, SEE_MORE, SHOP, VISIT_SITE, WATCH_NOW

call_to_action_url
optional

The URL to redirect the user to when the CTA button is clicked.

Type: string

Example: https://www.twitter.com

Example Request

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0?call_to_action=WATCH_NOW

Example Response

{
  "data": {
    "line_item_id": "8v53k",
    "call_to_action_url": "https://www.twitter.com",
    "call_to_action": "WATCH_NOW",
    "id": "8f0",
    "created_at": "2017-07-07T19:28:40Z",
    "updated_at": "2017-09-09T05:51:26Z",
    "deleted": false
  },
  "request": {
    "params": {
      "preroll_call_to_action_id": "8f0",
      "call_to_action": "WATCH_NOW",
      "account_id": "18ce54d4x5t"
    }
  }
}

DELETE accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id

Delete the specified preroll Call-to-Action (CTA) belonging to the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_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

preroll_call_to_action_id
required

A reference to the preroll CTA you are operating with in the request.

Type: string

Example: 8f0

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0

Example Response

{
  "data": {
    "line_item_id": "8v53k",
    "call_to_action_url": "https://www.twitter.com",
    "call_to_action": "VISIT_SITE",
    "id": "8f0",
    "created_at": "2017-07-07T19:28:40Z",
    "updated_at": "2017-08-30T06:08:21Z",
    "deleted": true
  },
  "request": {
    "params": {
      "preroll_call_to_action_id": "8f0",
      "account_id": "18ce54d4x5t"
    }
  }
}