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

GEThttps://papi.buysellads.com/lineitems?key=api_test&startDate=2020-09-01&endDate=2020-09-30

[
  {
    "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"
  }
]

GEThttps://papi.buysellads.com/lineitems?key=api_test&startDate=2020-09-01&endDate=2020-09-30&type=csv

"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

GEThttps://papi.buysellads.com/daily-stats?key=api_test&startDate=2020-09-01&endDate=2020-09-30

[
  {
    "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

Format-specific fields vary by inventory. Different placements may include additional fields not listed here, or omit fields that don't apply to their creative format.

Example

GEThttps://papi.buysellads.com/creatives?key=api_test&startDate=2020-09-01&endDate=2020-09-30

[
  {
    "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

Format-specific fields vary by inventory. Different placements may include additional fields not listed here, or omit fields that don't apply to their creative format.

Example

GEThttps://papi.buysellads.com/creatives-daily-stats?key=api_test&startDate=2020-09-01&endDate=2020-09-30

[
  {
    "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"
  }
]