Reporting API

Quick Navigation

• Getting Started
• Services
  • Authentication
  • Data Status
  • Reporting Services
    • Campaign Report
    • Ad Report
    • Conversion Report
    • Segment Size Report
    Entity Services
    • 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 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

Response attributes

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

Response attributes

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

Response attributes

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

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

Response attributes

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

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

Response attributes

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

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

Response attributes

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

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.

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

Response attributes

Each campaign object returned will contain the following attributes.

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

Response attributes

Each ad object returned will contain the following attributes.

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

Response attributes

Each segment object returned will contain the following attributes.

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

Response attributes

Each conversion object returned will contain the following attributes.

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!