Ads Reporting API – Lead Gen & CRM from Constant Contact

The Lead Gen & CRM 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:

Getting Started
Authentication
Data Status
Campaign Report
Ad Report
Conversion Report
Segment Size Report
Sites
Campaigns
Ads
Segments
Conversions
General Tips
Errors
Versions
Rate Limiting
Best Practices
API Clients

Getting Started

All you need to get up and running on the API is an account with Lead Gen & CRM Ads.

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 (default), last_30_days, lifetime	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	Description
interval	no	enum: today, yesterday, last_7_days (default), last_30_days, lifetime	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	Description
interval	no	enum: today, yesterday, last_7_days (default), last_30_days, lifetime	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	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	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
	}
}

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	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	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	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 Lead Gen & CRM Ads 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 Lead Gen & CRM Ads 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 ads@constantcontact.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 Lead Gen & CRM Ads API, let us know at ads@constantcontact.com, and we'll feature your work in our documentation!

Articles in this section

Getting Started

Authentication

Post Parameters

Response attributes

Example request

Example response

Data Status

Query Parameters

Response attributes

Example request

Example response

Campaign Report

Query Parameters

Response attributes

Example request

Example response

Example request

Example response

Ad Report

Query Parameters

Response attributes

Example request

Example response

Conversion Report

Query Parameters

Response attributes

Example request

Example response

Segment Size Report

Query Parameters

Response attributes

Example request

Example response

Sites

Query Parameters

Response attributes

Example request

Example response

Example request

Example response

Campaigns

Query Parameters

Response attributes

Example request

Example response

Example request

Example response

Ads

Query Parameters

Response attributes

Example request

Example response

Example request

Example response

Segments

Query Parameters

Response attributes

Example request

Example response

Example request

Example response

Conversions

Query Parameters

Response attributes

Example request

Example response

Example request

Example response

General Tips

Errors

Versions

Rate Limiting

Best Practices

API Clients

Related articles

Why was this help article not helpful?

Still didn't find what you are looking for?