DocsAdvertiser API

Advertiser API

Endpoints

All BuySellAds endpoints can be found at https://papi.buysellads.com. Below is a list of our current endpoints available for your use.

`lineitems`#

This endpoint returns details for all active line items in the current month.

Parameters#

These parameters should be in the query string.

Name	Type	Description
key	string	Required. Your API key for authentication.
startDate	string	Optional. `yyyy-mm-dd` format. Example value is `2024-01-16`
endDate	string	Optional. `yyyy-mm-dd` format. Example value is `2024-01-30`
type	string	Optional. Creates a CSV output. The value is `csv`

Response Fields#

Field	Type	Description
lineitem_id	string	Unique identifier for the line item
lineitem_name	string	Display name of the line item
order_id	string	Unique identifier for the parent order
order_name	string	Display name of the parent order
placements	string	Placement zones where the line item runs
paused	boolean	Whether the line item is currently paused
goal_unit	string	Unit type for the goal: `impressions`, `clicks`, `actions`, `landings`, or `fixed`
goal_quantity	number	Target quantity for the goal unit
unit_cost	string	Cost per unit, formatted as currency
ratified	boolean	Whether the line item has been ratified/approved
budget	string	Total budget for the line item, formatted as currency
notes	string	Additional notes or comments for the line item
scheduled_start	string	Start date of the line item (e.g., `Oct 1st, 2020`)
scheduled_end	string	End date of the line item (e.g., `Oct 31st, 2020`)
scheduled_start_iso	string	Start date in ISO format (e.g., `2020-10-01`)
scheduled_end_iso	string	End date in ISO format (e.g., `2020-10-31`)

Example#

[
  {
    "lineitem_id": "9801",
    "lineitem_name": "2020 Sep 1 - 30 Dribbble Shot",
    "order_id": "7283",
    "order_name": "Acme / September 2020",
    "placements": "Dribbble Shot Detail - Image + Text (260x200)",
    "paused": false,
    "goal_unit": "impressions",
    "goal_quantity": 1876000,
    "unit_cost": "$2.50",
    "ratified": true,
    "budget": "$4,690.00",
    "notes": "",
    "scheduled_start": "Sep 1st, 2020",
    "scheduled_end": "Sep 30th, 2020",
    "scheduled_start_iso": "2020-09-01",
    "scheduled_end_iso": "2020-09-30"
  },
  {
    "lineitem_id": "9802",
    "lineitem_name": "2020 Sep 1 - 30 Dribbble Shot_EU",
    "order_id": "7283",
    "order_name": "Acme / September 2020",
    "placements": "Dribbble Shot Detail - Image + Text (260x200)",
    "paused": false,
    "goal_unit": "impressions",
    "goal_quantity": 924000,
    "unit_cost": "$2.50",
    "ratified": true,
    "budget": "$2,310.00",
    "notes": "",
    "scheduled_start": "Sep 1st, 2020",
    "scheduled_end": "Sep 30th, 2020",
    "scheduled_start_iso": "2020-09-01",
    "scheduled_end_iso": "2020-09-30"
  }
]

"Lineitem ID","Lineitem Name","Order ID","Order Name","Placements","Paused","Goal Unit","Goal Quantity","Unit Cost","Ratified","Budget","Notes","Scheduled Start","Scheduled End","Scheduled Start ISO","Scheduled End ISO"
"9801","2020 Sep 1 - 30 Dribbble Shot","7283","Acme / September 2020","Dribbble Shot Detail - Image + Text (260x200)","false","impressions","1876000","$2.50","true","$4,690.00","","Sep 1st, 2020","Sep 30th, 2020","2020-09-01","2020-09-30"
"9802","2020 Sep 1 - 30 Dribbble Shot_EU","7283","Acme / September 2020","Dribbble Shot Detail - Image + Text (260x200)","false","impressions","924000","$2.50","true","$2,310.00","","Sep 1st, 2020","Sep 30th, 2020","2020-09-01","2020-09-30"

`daily-stats`#

This endpoint returns stats by day for all active line items in the current month.

Parameters#

These parameters should be in the query string.

Name	Type	Description
key	string	Required. Your API key for authentication.
lineitemId	int	Optional. Filters for a specific line item. Line item IDs can be found in the line item endpoint or within the buy.buysellads.com app. Example value `11192`.
startDate	string	Optional. `yyyy-mm-dd` format. Example value is `2024-01-16`
endDate	string	Optional. `yyyy-mm-dd` format. Example value is `2024-01-30`
type	string	Optional. Creates a CSV output. The value is `csv`

Response Fields#

Field	Type	Description
lineitem_id	string	Unique identifier for the line item
lineitem_name	string	Display name of the line item
order_id	string	Unique identifier for the parent order
order_name	string	Display name of the parent order
placements	string	Placement zones where the line item runs
date	string	Date for the stats in `yyyy-mm-dd` format
impressions	number	Number of impressions delivered on this date
clicks	number	Number of clicks received on this date
ctr	string	Click-through rate as a percentage (e.g., `0.11%`)
spend	string	Amount spent on this date, formatted as currency
notes	string	Additional notes or comments for the line item

Example#

[
  {
    "lineitem_id": "10507",
    "lineitem_name": "2020 Sep 1 - 30 Carbon: Stack Overflow",
    "order_id": "7573",
    "order_name": "Acme / September 2020",
    "placements": "Carbon - StackOverflow Dev",
    "date": "2020-09-15",
    "impressions": 59925,
    "clicks": 67,
    "ctr": "0.11%",
    "spend": "$149.81",
    "notes": ""
  },
  {
    "lineitem_id": "10507",
    "lineitem_name": "2020 Sep 1 - 30 Carbon: Stack Overflow",
    "order_id": "7573",
    "order_name": "Acme / September 2020",
    "placements": "Carbon - StackOverflow Dev",
    "date": "2020-09-16",
    "impressions": 57783,
    "clicks": 74,
    "ctr": "0.13%",
    "spend": "$144.45",
    "notes": ""
  }
]

`creatives`#

This endpoint returns creative stats for all line items in the current month.

Parameters#

These parameters should be in the query string.

Name	Type	Description
key	string	Required. Your API key for authentication.
lineitemId	int	Optional. Filters for a specific line item. Line item IDs can be found in the line item endpoint or within the buy.buysellads.com app. Example value `11192`.
startDate	string	Optional. `yyyy-mm-dd` format. Example value is `2024-01-16`
endDate	string	Optional. `yyyy-mm-dd` format. Example value is `2024-01-30`
type	string	Optional. Creates a CSV output. The value is `csv`

Response Fields#

Core fields (always present):

Field	Type	Description
order_name	string	Display name of the parent order
order_id	string	Unique identifier for the parent order
lineitem_id	string	Unique identifier for the line item
lineitem_name	string	Display name of the line item
creative_id	string	Unique identifier for the creative
link	string	Click-through URL for the creative
weight	number	Relative weight for rotation (higher = more frequent)
impressions	number	Total impressions delivered for this creative
clicks	number	Total clicks received for this creative
ctr	string	Click-through rate as a percentage (e.g., `0.08%`)
spend	string	Total spend for this creative, formatted as currency

Format-specific fields (vary by inventory):

Field	Type	Description
image	string	URL of the full-size creative image
small_image	string	URL of the small/thumbnail image
description	string	Description text displayed with the ad
company_tagline	string	Tagline or short description
tracking_pixel	string	URL for impression tracking pixel

Example#

[
  {
    "order_name": "Acme / September 2020",
    "order_id": "8001",
    "lineitem_id": "12001",
    "lineitem_name": "2020 Sep 01-30 Dev Circle",
    "creative_id": "36111",
    "image": "https://cdn4.buysellads.net/slack-carbon-red.png",
    "small_image": "https://cdn4.buysellads.net/slack-carbon-red_2x.png",
    "company_tagline": "Build internal tools fast",
    "description": "Description shows up here",
    "link": "https://www.acme.com",
    "tracking_pixel": "https://www.acme.com",
    "weight": 1,
    "impressions": 174186,
    "clicks": 132,
    "ctr": "0.08%",
    "spend": "$541.18"
  },
  {
    "order_name": "Acme / September 2020",
    "order_id": "8001",
    "lineitem_id": "12002",
    "lineitem_name": "2020 Sep 01-30 Stack Overflow: Dev Circle",
    "creative_id": "36112",
    "image": "https://cdn4.buysellads.net/slack-carbon-white.png",
    "small_image": "https://cdn4.buysellads.net/slack-carbon-white_2x.png",
    "company_tagline": "Build internal tools fast",
    "description": "Description shows up here",
    "link": "https://www.acme.com",
    "tracking_pixel": "https://www.acme.com",
    "weight": 1,
    "impressions": 173602,
    "clicks": 151,
    "ctr": "0.09%",
    "spend": "$538.48"
  }
]

`creatives-daily-stats`#

This endpoint returns creative stats by day for all line items in the current month.

Parameters#

These parameters should be in the query string.

Name	Type	Description
key	string	Required. Your API key for authentication.
lineitemId	int	Optional. Filters for a specific line item. Line item IDs can be found in the line item endpoint or within the buy.buysellads.com app. Example value `11192`.
startDate	string	Optional. `yyyy-mm-dd` format. Example value is `2024-01-16`
endDate	string	Optional. `yyyy-mm-dd` format. Example value is `2024-01-30`
type	string	Optional. Creates a CSV output. The value is `csv`

Response Fields#

Core fields (always present):

Field	Type	Description
order_name	string	Display name of the parent order
order_id	string	Unique identifier for the parent order
lineitem_id	string	Unique identifier for the line item
lineitem_name	string	Display name of the line item
creative_id	string	Unique identifier for the creative
date	string	Date for the stats in `yyyy-mm-dd` format
link	string	Click-through URL for the creative
weight	number	Relative weight for rotation (higher = more frequent)
impressions	number	Impressions delivered for this creative on this date
clicks	number	Clicks received for this creative on this date
ctr	string	Click-through rate as a percentage (e.g., `0.33%`)
spend	string	Spend for this creative on this date, as currency

Format-specific fields (vary by inventory):

Field	Type	Description
image	string	URL of the full-size creative image
small_image	string	URL of the small/thumbnail image
description	string	Description text displayed with the ad
company_tagline	string	Tagline or short description
tracking_pixel	string	URL for impression tracking pixel

Example#

[
  {
    "order_name": "Acme / September 2020",
    "order_id": "8001",
    "lineitem_id": "12001",
    "lineitem_name": "2020 Sep 01-30 Carbon Ads: Design Circle",
    "creative_id": "34949",
    "date": "2020-09-15",
    "image": "https://cdn4.buysellads.net/carbon-white.png",
    "small_image": "https://cdn4.buysellads.net/carbon-white_2x.png",
    "company_tagline": "Build internal tools fast",
    "description": "Description shows up here",
    "link": "https://www.acme.com",
    "tracking_pixel": "https://www.acme.com",
    "weight": 1,
    "impressions": 20164,
    "clicks": 67,
    "ctr": "0.33%",
    "spend": "$68.55"
  },
  {
    "order_name": "Acme / September 2020",
    "order_id": "8001",
    "lineitem_id": "12001",
    "lineitem_name": "2020 Sep 01-30 Carbon Ads: Design Circle",
    "creative_id": "34949",
    "date": "2020-09-16",
    "image": "https://cdn4.buysellads.net/carbon-white.png",
    "small_image": "https://cdn4.buysellads.net/carbon-white_2x.png",
    "company_tagline": "Build internal tools fast",
    "description": "Description shows up here",
    "link": "https://www.acme.com",
    "tracking_pixel": "https://www.acme.com",
    "weight": 1,
    "impressions": 19393,
    "clicks": 70,
    "ctr": "0.36%",
    "spend": "$65.93"
  }
]

Need help with your integration? Contact supportView source

lineitems#

Parameters#

Response Fields#

Example#

daily-stats#

Parameters#

Response Fields#

Example#

creatives#

Parameters#

Response Fields#

Example#

creatives-daily-stats#

Parameters#

Response Fields#

Example#

`lineitems`#

`daily-stats`#

`creatives`#

`creatives-daily-stats`#