× Exclamation Point Icon Important: As we continue to evolve and improve our offerings, we have decided to retire the SharpSpring Ads (formerly Perfect Audience) platform on August 15, 2024. Click here to learn more.
Home > API Documentation > Reporting API

Reporting API

The SharpSpring Ads performance reporting API allows you to retrieve your campaign, ad, and conversion performance data. Visualize your data in a custom dashboard, log new metrics out as they come in, or impress us with another way to use your data. Here's information about how our reporting API works:
 

Quick Navigation

Getting Started

All you need to get up and running on the API is an account with SharpSpring Ads. Head over here if you don't have one yet.

Authentication

https://api.perfectaudience.com/auth

You will authenticate using the same credentials you signed up with. Upon successful authentication, you will receive a token good for two hours. All subsequent requests will be made using your token. The token will be passed in an Authorization header. You will need to reauthenticate, and retrieve a new token, every two hours.

Post Parameters

name required type default description
email yes string   The email address you used to sign up at app.perfectaudience.com.
password yes string   The password you used to sign up at app.perfectaudience.com.

Response attributes

name example description
token 7180b331d590d95cfb1592489fb818b3d412d578 This token is unique to your user login and will remain valid for two hours. It will need to be passed in the Authorization header of all subsequent requests. After two hours, you will need to obtain a new token.

Example request

curl -d "email=steve@perfectaudience.com&password=mypassword" "https://api.perfectaudience.com/auth"

Example response

{
	"status": 200,
	"token": "7180b331d590d95cfb1592489fb818b3d412d578"
}

Data Status

https://api.perfectaudience.com/data_status

Use the data status service to check when new performance data is available.

Query Parameters

name required type default description
data_type yes enum: campaign_report, ad_report, conversion_report   The type of data to check status of.

Response attributes

name example description
last_updated 2013-02-08T17:00:00Z The UTC timestamp at which the data source was last updated.

Example request

Check when the campaign_report data was last updated.

curl -H "Authorization: 7180b331d590d95cfb1592489fb818b3d412d578" "https://api.perfectaudience.com/data_status?data_type=campaign_report"

Example response

{
	"status": 200,
	"api_version": 1,
	"time": "2013-03-20T07:21:39Z",
	"data_status": {
		"last_updated": "2013-02-08T17:00:00Z"
	}
}

Campaign Report

https://api.perfectaudience.com/reports/campaign_report

The campaign_report returns useful performance statistics over a given time interval, separated by campaign.

Query Parameters

name required type default description
interval no enum: today, yesterday, last_7_days, last_30_days, lifetime last_7_days The time interval over which to return reporting data. All dates are in Eastern Time and respect Daylight Savings.
start_date no string in the format "YYYY-MM-DD"   The start_date used to define a precise time interval. If start_date is supplied, end_date must be supplied as well. The presence of start_date and end_date overrides a supplied interval enum.
end_date no string in the format "YYYY-MM-DD"   The end_date used to define a precise time interval. If end_date is supplied, start_date must be supplied as well. The presence of start_date and end_date overrides a supplied interval enum.
site_id no string   Restricts the results to campaigns underneath the site with the given ID. Site IDs may be retrieved from the /sites endpoint.
campaign_id no string   Restricts the results to the campaign with the given ID. Campaign IDs may be retrieved from the /campaigns endpoint.
dimension no enum: ad   Slices the campaign results by the given dimension and returns a flat array of each unique pair, e.g. if dimension is 'ad', the report will consist of an array of each campaign/ad pair identifiable by campaign_id, ad_id and the campaign_ad_id. Currently the only acceptable value for this parameter is 'ad'.

Response attributes

Each object in the array of objects returned for the 'report' key will contain the following attributes.

name example description
campaign_id 5074bc89d7a67f0002000026 The ID of the campaign
campaign_nid 200062988 The numeric ID of the campaign
campaign_name My Campaign The name of the campaign
campaign_type facebook The type may be 'facebook', 'web', 'newsfeed', 'dynamic_facebook_sidebar', or 'dynamic_newsfeed'
impressions 25000 The number of impressions the campaign served
clicks 750 The number of clicks the campaign received
costs 25.2 The cost of the campaign
click_conversions 10 The number of attributable click-through conversions
view_conversions 20 The number of attributable view-through conversions
conversions 30 The total number of attributable conversions
post_click_revenue 5.25 Revenue from click-through conversions
post_view_revenue 10 Revenue from view-through conversions
revenue 15.25 Total revenue from conversions
adjusted_post_click_revenue 5.25 Adjusted Revenue from click-through conversions, adjusted by post-click attribution rate
adjusted_post_view_revenue 10 Adjusted Revenue from click-through conversions, adjusted by post-view attribution rate
adjusted_conversion_revenue 15.25 Total Adjusted Revenue from conversions
cpm 1.008 Cost per 1000 impressions
ctr 0.03 Click-through Rate: the number of clicks divided by the number of impressions
cpc 0.0336 Cost per Click
conversion_rate 0.04 The number of conversions divided by the number of clicks
ad_id 53716d5316bf2f9945000002 The ID of the ad. Note this attribute is only returned for reports with a specified 'dimension' of 'ad'
campaign_ad_id 200062988234092967 The ID of the campaign/ad pair. Note this attribute is only returned for reports with a specified 'dimension' of 'ad'

Example request

curl -H "Authorization: 7180b331d590d95cfb1592489fb818b3d412d578" "https://api.perfectaudience.com/reports/campaign_report?interval=last_30_days"

Example response

{
	"status": 200,
	"api_version": 1,
	"time": "2013-03-19T21:50:50Z",
	"report": [
		{
			"campaign_id": "941e29f625f97b74620000e7",
			"campaign_nid": "200092967",
			"impressions": 78817,
			"clicks": 164,
			"costs": 149.437427,
			"click_conversions": 2,
			"post_click_revenue": 20,
			"view_conversions": 5,
			"post_view_revenue": 52.75,
			"campaign_name": "Site Retargeting",
			"campaign_type": "web",
			"conversions": 7,
			"revenue": 72.75,
			"ctr": 0.0020807693771648247,
			"cpc": 0.9112038231707318,
			"conversion_rate": 0.042682926829268296,
			"cpm": 1.896005011609171,
			"adjusted_post_click_revenue": 10,
			"adjusted_post_view_revenue": 52.75,
			"adjusted_conversion_revenue": 62.75
		},
		{
			"campaign_id": "82e0ecd0512c76000824019b",
			"campaign_nid": "201362923",
			"impressions": 51955,
			"clicks": 54,
			"costs": 12.574825,
			"click_conversions": 3,
			"post_click_revenue": 30,
			"view_conversions": 5,
			"post_view_revenue": 50,
			"campaign_name": "Facebook Retargeting",
			"campaign_type": "facebook",
			"conversions": 8,
			"revenue": 80,
			"ctr": 0.0010393609854681936,
			"cpc": 0.23286712962962963,
			"conversion_rate": 0.14814814814814814,
			"cpm": 0.24203300933500146,
			"adjusted_post_click_revenue": 15,
			"adjusted_post_view_revenue": 25,
			"adjusted_conversion_revenue": 40
		},
	]
}

Example request

curl -H "Authorization: 7180b331d590d95cfb1592489fb818b3d412d578" "https://api.perfectaudience.com/reports/campaign_report?dimension=ad"

Example response

{
	"status": 200,
	"api_version": 1,
	"time": "2013-03-19T21:50:50Z",
	"report": [
		{
			"campaign_id": "941e29f625f97b74620000e7",
			"campaign_nid": "200092967",
			"ad_id": "504f0dfc4c63500002000002",
			"campaign_ad_id": "200092967390073410",
			"impressions": 78817,
			"clicks": 164,
			"costs": 149.437427,
			"click_conversions": 2,
			"post_click_revenue": 20,
			"view_conversions": 5,
			"post_view_revenue": 50,
			"campaign_name": "Site Retargeting",
			"campaign_type": "web",
			"conversions": 7,
			"revenue": 70,
			"ctr": 0.0020807693771648247,
			"cpc": 0.9112038231707318,
			"conversion_rate": 0.042682926829268296,
			"cpm": 1.896005011609171,
			"adjusted_post_click_revenue": 20,
			"adjusted_post_view_revenue": 25,
			"adjusted_conversion_revenue": 45
		},
		{
			"campaign_id": "82e0ecd0512c76000824019b",
			"campaign_nid": "201362923",
			"ad_id": "5019123459538b0002000002",
			"campaign_ad_id": "201362923107890001",
			"impressions": 51955,
			"clicks": 54,
			"costs": 12.574825,
			"click_conversions": 3,
			"post_click_revenue": 36.3,
			"view_conversions": 5,
			"post_view_revenue": 50,
			"campaign_name": "Facebook Retargeting",
			"campaign_type": "facebook",
			"conversions": 8,
			"revenue": 86.3,
			"ctr": 0.0010393609854681936,
			"cpc": 0.23286712962962963,
			"conversion_rate": 0.14814814814814814,
			"cpm": 0.24203300933500146,
			"adjusted_post_click_revenue": 36.3,
			"adjusted_post_view_revenue": 25,
			"adjusted_conversion_revenue": 61.3
		},
	]
}

Ad Report

https://api.perfectaudience.com/reports/ad_report

The ad_report returns useful performance statistics over a given time interval, separated by ad.

Query Parameters

name required type default description
interval no enum: today, yesterday, last_7_days, last_30_days, lifetime last_7_days The time interval over which to return reporting data. All dates are in Eastern Time and respect Daylight Savings.
start_date no string in the format "YYYY-MM-DD"   The start_date used to define a precise time interval. If start_date is supplied, end_date must be supplied as well. The presence of start_date and end_date overrides a supplied interval enum.
end_date no string in the format "YYYY-MM-DD"   The end_date used to define a precise time interval. If end_date is supplied, start_date must be supplied as well. The presence of start_date and end_date overrides a supplied interval enum.
site_id no string   Restricts the results to ads underneath the site with the given ID. Site IDs may be retrieved from the /sites endpoint.
campaign_id no string   Restricts the results to the ad with the given ID. Ad IDs may be retrieved from the /ads endpoint.

Response attributes

Each object in the array of objects returned for the 'report' key will contain the following attributes.

name example description
ad_id 5074bc89d7a67f0002000026 The ID of the ad
ad_nid 200062988 The numeric ID of the ad
ad_name My Ad The name of the ad
ad_type facebook The type may be 'facebook', 'pagepost', 'ImageAd', 'dynamic_facebook_sidebar', or 'dynamic_pagepost'
impressions 25000 The number of impressions the ad served
clicks 750 The number of clicks the ad received
costs 25.2 The cost of serving this ad's impressions
click_conversions 10 The number of attributable click-through conversions
view_conversions 20 The number of attributable view-through conversions
conversions 30 The total number of attributable conversions
post_click_revenue 5.25 Revenue from click-through conversions
post_view_revenue 10.5 Revenue from view-through conversions
revenue 15.75 Total revenue from conversions
adjusted_post_click_revenue 5.25 Adjusted Revenue from click-through conversions, adjusted by post-click attribution rate
adjusted_post_view_revenue 10 Adjusted Revenue from click-through conversions, adjusted by post-view attribution rate
adjusted_conversion_revenue 15.25 Total Adjusted Revenue from conversions
cpm 1.008 Cost per 1000 impressions
ctr 0.03 Click-through Rate: the number of clicks divided by the number of impressions
cpc 0.0336 Cost per Click
conversion_rate 0.04 The number of conversions divided by the number of clicks

Example request

curl -H "Authorization: 7180b331d590d95cfb1592489fb818b3d412d578" "https://api.perfectaudience.com/reports/ad_report?interval=last_30_days"

Example response

{
	"status": 200,
	"api_version": 1,
	"time": "2013-03-19T21:50:50Z",
	"report": [
		{
			"ad_id": "504f0dfc4c63500002000002",
			"ad_nid": "390073410",
			"impressions": 3729,
			"clicks": 14,
			"costs": 4.900379,
			"click_conversions": 3,
			"post_click_revenue": 30,
			"view_conversions": 2,
			"post_view_revenue": 20,
			"ad_name": "Foamy468",
			"ad_type": "ImageAd",
			"conversions": 5,
			"revenue": 50,
			"ctr": 0.0037543999366586215,
			"cpc": 0.3500270714285714,
			"conversion_rate": 0,
			"cpm": 1.314126843657817,
			"adjusted_post_click_revenue": 15,
			"adjusted_post_view_revenue": 20,
			"adjusted_conversion_revenue": 35
		},
		{
			"impressions": 0,
			"clicks": 0,
			"costs": 0,
			"click_conversions": 4,
			"post_click_revenue": 40,
			"view_conversions": 5,
			"post_view_revenue": 50,
			"ad_name": "testing",
			"ad_type": "facebook",
			"ad_id": "5019123459538b0002000002",
			"ad_nid": "107890001",
			"conversions": 9,
			"revenue": 90.0,
			"ctr": null,
			"cpc": null,
			"conversion_rate": null,
			"cpm": null,
			"adjusted_post_click_revenue": 20,
			"adjusted_post_view_revenue": 50,
			"adjusted_conversion_revenue": 70
		} 
	]
}

Conversion Report

https://api.perfectaudience.com/reports/conversion_report

The conversion_report returns useful performance statistics over a given time interval, separated by conversion.

Query Parameters

name required type default description
interval no enum: today, yesterday, last_7_days, last_30_days, lifetime last_7_days The time interval over which to return reporting data. All dates are in Eastern Time and respect Daylight Savings.
start_date no string in the format "YYYY-MM-DD"   The start_date used to define a precise time interval. If start_date is supplied, end_date must be supplied as well. The presence of start_date and end_date overrides a supplied interval enum.
end_date no string in the format "YYYY-MM-DD"   The end_date used to define a precise time interval. If end_date is supplied, start_date must be supplied as well. The presence of start_date and end_date overrides a supplied interval enum.
site_id no string   Restricts the results to ads underneath the site with the given ID. Site IDs may be retrieved from the /sites endpoint.
campaign_id no string   Restricts the results to the conversion with the given ID. Conversion IDs may be retrieved from the /conversions endpoint.

Response attributes

Each object in the array of objects returned for the 'report' key will contain the following attributes.

name example description
conversion_id 5074bc89d7a67f0002000026 The ID of the conversion
conversion_nid 200062988 The numeric ID of the conversion
conversion_name Sale The name of the conversion
click_conversions 10 The number of click-through conversions
view_conversions 20 The number of view-through conversions
conversions 30 The total number of conversions
post_click_revenue 5.4 Revenue from click-through conversions
post_view_revenue 10.35 Revenue from view-through conversions
revenue 15.75 Total revenue from conversions

Example request

curl -H "Authorization: 7180b331d590d95cfb1592489fb818b3d412d578" "https://api.perfectaudience.com/reports/conversion_report?interval=last_30_days"

Example response

{
	"status": 200,
	"api_version": 1,
	"time": "2013-03-19T23:25:31Z",
	"report": [
		{
			"conversions": 112,
			"click_conversions": 51,
			"view_conversions": 61,
			"post_click_revenue": 5.1,
			"post_view_revenue": 6.1,
			"revenue": 11.2,
			"adjusted_post_click_revenue": 5.1,
			"adjusted_post_view_revenue": 3.05,
			"adjusted_conversion_revenue": 8.15,
			"conversion_name": "Sale",
			"conversion_nid": "214862377",
			"conversion_id": "4ff6ade836111110020000a9"
		},
		{
			"conversions": 30,
			"click_conversions": 10,
			"view_conversions": 20,
			"post_click_revenue": 5,
			"post_view_revenue": 10,
			"revenue": 15,
			"adjusted_post_click_revenue": 20,
			"adjusted_post_view_revenue": 5,
			"adjusted_conversion_revenue": 25,
			"conversion_name": "Sign Up",
			"conversion_nid": "102332929",
			"conversion_id": "505b63967654c7000200004c"
		}
	]
}

Segment Size Report

https://api.perfectaudience.com/reports/segment_size_report

The segment_size_report returns segment size data for each of your available segments.

Query Parameters

name required type default description
site_id no string   Restricts the results to segments underneath the site with the given ID. Site IDs may be retrieved from the /sites endpoint.
segment_id no string   Returns results for a single segment. Segment IDs may be retrieved from the /segments endpoint.

Response attributes

Each object in the array of objects returned for the 'report' key will contain the following attributes.

name example description
segment_id 5074bc89d7a67f0002000026 The ID of the segment
segment_nid 200062988 The numeric ID of the segment
segment_name All Visitors The name of the segment
segment_size 83634 The size of the segment

Example request

curl -H "Authorization: 7180b331d590d95cfb1592489fb818b3d412d578" "https://api.perfectaudience.com/reports/segment_size_report"

Example response

{
	"status": 200,
	"api_version": 1,
	"time": "2013-03-19T23:25:31Z",
	"report": [
		{
			"segment_id": "50637d4c57c05a000200013d",
			"segment_nid": "199203044",
			"segment_name": "All Visitors",
			"segment_size": 83634
		},
		{
			"segment_id": "508331969bb79c000200038a",
			"segment_nid": "180063970",
			"segment_name": "Purchasers",
			"segment_size": 1655
		}
	]
}

Sites

https://api.perfectaudience.com/sites

https://api.perfectaudience.com/sites/:id

https://api.perfectaudience.com/sites/:nid

Returns metadata for sites within an account

Query Parameters

None.

Response attributes

Each site object returned will contain the following attributes.

name example description
_id 5074bc89d7a67f0002000026 The ID of the site
nid 200062988 The numeric ID of the site
name My Site The name of the site
url https://www.perfectaudience.com The site's URL
created_at 2013-01-11T16:38:32+00:00 Site creation UTC timestamp
view_conversion_window 30 The site-wide view conversion window in days
click_conversion_window 30 The site-wide click conversion window in days
domain_blacklist http://blacklist.com,http://donotserve.com A comma-separated list of domains to blacklist from this site's campaigns

Example request

Return results for all sites

curl -H "Authorization: 7180b331d590d95cfb1592489fb818b3d412d578" "https://api.perfectaudience.com/sites"

Example response

{
	"status": 200,
	"api_version": 1,
	"time": "2013-03-19T21:50:50Z",
	"sites": [
		{
			"_id": "4ff6ade4361ed500020111a5",
			"nid": "134071988",
			"click_conversion_window": 30,
			"created_at": null,
			"domain_blacklist": "",
			"name": "Perfect Audience",
			"url": "http://perfectaudience.com/",
			"view_conversion_window": 30
		}
	]
}

Example request

Return results for a single site

curl -H "Authorization: 7180b331d590d95cfb1592489fb818b3d412d578" "https://api.perfectaudience.com/sites/4ff6ade4361ed500020111a5"
curl -H "Authorization: 7180b331d590d95cfb1592489fb818b3d412d578" "https://api.perfectaudience.com/sites/134071988"

Example response

{
	"status": 200,
	"api_version": 1,
	"time": "2013-03-19T23:40:10Z",
	"site": {
		"_id": "4ff6ade4361ed500020111a5",
		"nid": "134071988",
		"click_conversion_window": 30,
		"created_at": null,
		"domain_blacklist": "bluvideos.com",
		"name": "Perfect Audience",
		"url": "http://perfectaudience.com/",
		"view_conversion_window": 30
	}
}

Campaigns

https://api.perfectaudience.com/campaigns

https://api.perfectaudience.com/campaigns/:id

https://api.perfectaudience.com/campaigns/:nid

Returns metadata for campaigns within an account

Query Parameters

name required type default description
site_id no string   Restricts the results to campaigns underneath the site with the given ID. Site IDs may be retrieved from the /sites endpoint.

Response attributes

Each campaign object returned will contain the following attributes.

name example description
_id 5074bc89d7a67f0002000026 The ID of the campaign
nid 200062988 The numeric ID of the campaign
site_id 4ff6ade4361ed500020111a5 The site that the campaign belongs to
name My Campaign The name of the campaign
type facebook The type may be 'facebook', 'web', 'newsfeed', 'dynamic_facebook_sidebar', or 'dynamic_newsfeed'
created_at 2013-01-11T16:38:32+00:00 Campaign creation UTC timestamp
state active The state may be 'active' or 'inactive'
start_date 2012-12-18T00:00:00+00:00 The configured start date of the campaign
end_date 2013-03-18T00:00:00+00:00 The configured end date of the campaign
pricing_model CPM The bidding model for the campaign - currently this attribute will only have values of "CPM" (Manual) or "Optimized"
cpm_max_bid 0.5 The configured max CPM bid. Note that campaigns with an "Optimized" pricing model will return null for this attribute
weekly_budget 500 The weekly budget

Example request

Return results for all campaigns

curl -H "Authorization: 7180b331d590d95cfb1592489fb818b3d412d578" "https://api.perfectaudience.com/campaigns"

Example response

{
	"status": 200,
	"api_version": 1,
	"time": "2013-03-19T21:50:50Z",
	"campaigns": [
		{
			"_id": "50e7279e6cfee2111200027b",
			"nid": "273100104",
			"pricing_model": "CPM",
			"cpm_max_bid": 3,
			"created_at": "2013-01-04T19:03:59+00:00",
			"end_date": null,
			"name": "Audience Retargeting",
			"type": "facebook",
			"start_date": "2013-01-03T00:00:00+00:00",
			"state": "active",
			"weekly_budget": 280
		},
		{
			"_id": "5106e6d26a11140002000003",
			"nid": "149102897",
			"pricing_model": "Optimized",
			"cpm_max_bid": null,
			"created_at": "2013-01-28T21:00:03+00:00",
			"end_date": null,
			"name": "Free Trial campaign",
			"type": "web",
			"start_date": "2013-01-27T00:00:00+00:00",
			"state": "inactive",
			"weekly_budget": 140
		}
	]
}

Example request

Return results for a single campaign

curl -H "Authorization: 7180b331d590d95cfb1592489fb818b3d412d578" "https://api.perfectaudience.com/campaigns/5106e6d26a11140002000003"
curl -H "Authorization: 7180b331d590d95cfb1592489fb818b3d412d578" "https://api.perfectaudience.com/campaigns/149102897"

Example response

{
	"status": 200,
	"api_version": 1,
	"time": "2013-03-19T23:40:10Z",
	"campaign": {
		"_id": "5106e6d26a11140002000003",
		"nid": "149102897",
		"pricing_model": "Optimized",
		"cpm_max_bid": null,
		"created_at": "2013-01-28T21:00:03+00:00",
		"end_date": null,
		"name": "Free Trial campaign",
		"type": "web",
		"start_date": "2013-01-27T00:00:00+00:00",
		"state": "inactive",
		"weekly_budget": 140
	}
}

Ads

https://api.perfectaudience.com/ads

https://api.perfectaudience.com/ads/:id

https://api.perfectaudience.com/ads/:nid

Returns metadata for ads within an account

Query Parameters

name required type default description
site_id no string   Restricts the results to ads underneath the site with the given ID. Site IDs may be retrieved from the /sites endpoint.

Response attributes

Each ad object returned will contain the following attributes.

name example description
_id 5074bc89d7a67f0002000026 The ID of the ad
nid 200062988 The numeric ID of the ad
site_id 4ff6ade4361ed500020111a5 The site that the ad belongs to
name My Ad The name of the ad
state active The state may be 'active' or 'inactive'
click_url https://www.perfectaudience.com The ad's click URL
created_at 2013-01-11T16:38:32+00:00 Site creation UTC timestamp
dimensions 99x72 The dimensions of the ad
type facebook The type may be 'facebook', 'pagepost', 'ImageAd', 'dynamic_facebook_sidebar', or 'dynamic_pagepost'
facebook_title Try Facebook Retargeting If this is a facebook ad, the field will contain the title text.
facebook_body Start retargeting on Facebook Exchange today. 14-day free trial. Low prices. Epic ROI. If this is a facebook ad, the field will contain the body text.

Example request

Return results for all ads

curl -H "Authorization: 7180b331d590d95cfb1592489fb818b3d412d578" "https://api.perfectaudience.com/ads"

Example response

{
	"status": 200,
	"api_version": 1,
	"time": "2013-03-19T21:50:50Z",
	"ads": [
		{
			"_id": "50e156111c2644000200037a",
			"nid": "250042830",
			"click_url": "http://perfectaudience.com/?utm_source=perfect&utm_medium=fbx&utm_content=fbxsitefreddie2&utm_campaign=fbxsite",
			"created_at": "2012-12-31T09:09:55+00:00",
			"dimensions": "99x72",
			"facebook_body": "Start retargeting on Facebook Exchange today. 14-day free trial. Low prices. Epic ROI.",
			"facebook_title": "Try Facebook Retargeting",
			"name": "Try Facebook Retargeting",
			"state": "active",
			"type": "facebook"
		},
		{
			"_id": "50e1567c111144000200037c",
			"nid": "210362867",
			"click_url": "http://perfectaudience.com/?utm_source=perfect&utm_medium=fbx&utm_content=fbxsitefreddie3&utm_campaign=fbxsite",
			"created_at": "2012-12-31T09:10:25+00:00",
			"dimensions": "99x72",
			"facebook_body": "Start retargeting on Facebook Exchange today. 14-day free trial. Low prices. Epic ROI.",
			"facebook_title": "Try Facebook Retargeting",
			"name": "Try Facebook Retargeting",
			"state": "active",
			"type": "facebook"
		}
	]
}

Example request

Return results for a single site

curl -H "Authorization: 7180b331d590d95cfb1592489fb818b3d412d578" "https://api.perfectaudience.com/ads/50e1567c111144000200037c"
curl -H "Authorization: 7180b331d590d95cfb1592489fb818b3d412d578" "https://api.perfectaudience.com/ads/210362867"

Example response

{
	"status": 200,
	"api_version": 1,
	"time": "2013-03-19T23:40:10Z",
	"ad": {
		"_id": "50e1567c111144000200037c",
		"nid": "210362867",
		"click_url": "http://perfectaudience.com/?utm_source=perfect&utm_medium=fbx&utm_content=fbxsitefreddie3&utm_campaign=fbxsite",
		"created_at": "2012-12-31T09:10:25+00:00",
		"dimensions": "99x72",
		"facebook_body": "Start retargeting on Facebook Exchange today. 14-day free trial. Low prices. Epic ROI.",
		"facebook_title": "Try Facebook Retargeting",
		"name": "Try Facebook Retargeting",
		"state": "active",
		"type": "facebook"
	}
}

Segments

https://api.perfectaudience.com/segments

https://api.perfectaudience.com/segments/:id

https://api.perfectaudience.com/segments/:nid

Returns metadata for segments (retargeting lists) within an account

Query Parameters

name required type default description
site_id no string   Restricts the results to segments underneath the site with the given ID. Site IDs may be retrieved from the /sites endpoint.

Response attributes

Each segment object returned will contain the following attributes.

name example description
_id 5074bc89d7a67f0002000026 The ID of the segment
nid 200062988 The numeric ID of the segment
site_id 4ff6ade4361ed500020111a5 The site that the segment belongs to
name My Segment The name of the segment
created_at 2013-01-11T16:38:32+00:00 Ad creation UTC timestamp
duration 45 The length of time, in days, to keep users in the segment
goal path The method used to match against the client URL
target_text /trial* The text used to match against the client URL

Example request

Return results for all segments

curl -H "Authorization: 7180b331d590d95cfb1592489fb818b3d412d578" "https://api.perfectaudience.com/segments"

Example response

{
	"status": 200,
	"api_version": 1,
	"time": "2013-03-19T21:50:50Z",
	"segments": [
		{
			"_id": "509879b351802700020007f3",
			"nid": "360412191",
			"created_at": "2012-12-18T10:47:15+00:00",
			"duration": null,
			"goal": "path",
			"name": "All visitors",
			"target_text": "/*"
		},
		{
			"_id": "12343fe42f2ea900020004b3",
			"nid": "307945138",
			"created_at": "2013-01-11T16:37:56+00:00",
			"duration": null,
			"goal": "path",
			"name": "Interested in a trial",
			"target_text": "/trial*"
		}
	]
}

Example request

Return results for a single segment

curl -H "Authorization: 7180b331d590d95cfb1592489fb818b3d412d578" "https://api.perfectaudience.com/segments/12343fe42f2ea900020004b3"
curl -H "Authorization: 7180b331d590d95cfb1592489fb818b3d412d578" "https://api.perfectaudience.com/segments/307945138"

Example response

{
	"status": 200,
	"api_version": 1,
	"time": "2013-03-19T23:40:10Z",
	"segment": {
		"_id": "12343fe42f2ea900020004b3",
		"nid": "307945138",
		"created_at": "2013-01-11T16:37:56+00:00",
		"duration": null,
		"goal": "path",
		"name": "Interested in a trial",
		"target_text": "/trial*"
	}
}

Conversions

https://api.perfectaudience.com/conversions

https://api.perfectaudience.com/conversions/:id

https://api.perfectaudience.com/conversions/:nid

Returns metadata for configured conversions within an account

Query Parameters

name required type default description
site_id no string   Restricts the results to conversions underneath the site with the given ID. Site IDs may be retrieved from the /sites endpoint.

Response attributes

Each conversion object returned will contain the following attributes.

name example description
_id 5074bc89d7a67f0002000026 The ID of the conversion
nid 200062988 The numeric ID of the conversion
site_id 4ff6ade4361ed500020111a5 The site that the conversion belongs to
name Sign up The name of the conversion
created_at 2013-01-11T16:38:32+00:00 Conversion creation UTC timestamp
conversion_frequency every Conversion frequency may be 'every' or 'once'
last_fired 2013-03-19T21:29:02+00:00 The UTC timestamp at which the conversion pixel last fired
goal path The method used to match against the client URL
target_text /orderSuccess The text used to match against the client URL

Example request

Return results for all conversions

curl -H "Authorization: 7180b331d590d95cfb1592489fb818b3d412d578" "https://api.perfectaudience.com/conversions"

Example response

{
	"status": 200,
	"api_version": 1,
	"time": "2013-03-19T21:50:50Z",
	"conversions": [
		{
			"_id": "1234ade8361ed500020000a7",
			"nid": "241045673",
			"conversion_frequency": "once",
			"created_at": "2012-10-18T19:46:52+00:00",
			"goal": "path",
			"last_fired": "2013-03-19T21:29:02+00:00",
			"name": "SignUp",
			"target_text": "/sites/new"
		},
		{
			"_id": "576dacacfa0b100002000293",
			"nid": "256458880",
			"conversion_frequency": "once",
			"created_at": "2012-10-18T19:46:52+00:00",
			"goal": "path",
			"last_fired": "2013-03-15T08:19:18+00:00",
			"name": "Sale",
			"target_text": "/orderSuccess"
		}
	]
}

Example request

Return results for a single conversion

curl -H "Authorization: 7180b331d590d95cfb1592489fb818b3d412d578" "https://api.perfectaudience.com/conversions/576dacacfa0b100002000293"
curl -H "Authorization: 7180b331d590d95cfb1592489fb818b3d412d578" "https://api.perfectaudience.com/conversions/256458880"

Example response

{
	"status": 200,
	"api_version": 1,
	"time": "2013-03-19T23:40:10Z",
	"conversion": {
		"_id": "576dacacfa0b100002000293",
		"nid": "256458880",
		"conversion_frequency": "once",
		"created_at": "2012-10-18T19:46:52+00:00",
		"goal": "path",
		"last_fired": "2013-03-15T08:19:18+00:00",
		"name": "Sale",
		"target_text": "/orderSuccess"
	}
}

General Tips

All requests must be made over SSL. A request made to http://api.perfectaudience.com will be 301 redirected to https://api.perfectaudience.com.

All time intervals are reported using Eastern Time, respecting Daylight Savings.

Errors

The Perfect Audience API attempts to provide the appropriate HTTP status code with each response. In addition to the status code, an error_code and error_message is provided. Here is an example error response:

{
	"status": 400,
	"error_code": "UNKNOWN_DATA_TYPE",
	"error_message": "The data type 'not_a_real_data_type' is not recognized.",
	"api_version": 1,
	"time": "2013-03-20T07:31:58Z"
}

Versions

The Perfect Audience API uses the Accept header to specify version info. The following call, for example, requests a report using version 1 of the API.

curl -H "Authorization: 7180b331d590d95cfb1592489fb818b3d412d578" -H "Accept: application/vnd.perfect-audience-v1+json" https://api.perfectaudience.com/reports/campaign_report"

Any call that excludes the Accept header will default to the latest version of the API. The latest version of the API is currently version 1.

Rate Limiting

The API is currently not rate-limited. However, usage is monitored, and access may be revoked for abusive clients. Rate limiting will be added in the future. If you have any questions concerning appropriate API usage, please contact tech@perfectaudience.com.

Best Practices

The data returned by the campaign_report, ad_report, and conversion_report is updated approximately once per hour. It is recommended that client applications query the data_status endpoint once per hour and store the timestamp returned. This timestamp may be used to determine if new data is available since the last request for performance data. This allows a client to only request performance data after it has been updated.

API Clients

API clients, or adapters, abstract the details of the API away so you can interact with your objects and data more easily. If you write an API client for the Perfect Audience API, let us know at tech@perfectaudience.com, and we'll feature your work in our documentation!

Language Author Documentation
Ruby Gary Rafferty Perfecta docs