Tech Docs
API
Parse.ly Conversions API (Beta)

Parse.ly Conversions API (Beta)

The beta release of Parse.ly’s Conversions API is designed to address two use-cases: First, to download detailed URL-level conversion metrics for ad-hoc analysis (/conversions/url). Second, to provide a top-converting content module on your site containing a list of URLs, filtered by metadata, and ranked by conversion metrics (/conversions/url/top). These endpoints follow all the same authentication, error, and formatting standards specified in our documentation and closely follow the functionality or our /analytics endpoint.

#/conversions/url

Returns detailed conversion metrics for all of your URLs, broken down by all of your conversion labels. This API provides the most granular metrics on converting content and is typically used to populate a data warehouse for ad-hoc analysis.

#Optional Parameters

attribution_typeDetermines which of our attribution models to use for computing conversion metrics. Either linear, last_touch, last_post_touched, or first_touch. Defaults to last_touch if not specified.
conversion_typeOne or more conversion types to use for computing conversion metrics. Using this filter will result in conversion metrics being calculated for all conversion labels of these types. Either newsletter_signup, custom, lead_capture, link_click, subscription, or purchase. Defaults to returning conversion label-level metrics for all conversion types if not specified.
conversion_labelOne or more of your custom conversion labels. Defaults to returning conversion label-level metrics for all of your conversion labels if not specified.
page_typeOne or more page types to consider conversion from. Either post, sectionpage,frontpage, or index. Defaults to returning conversions across all page types if not specified.
period_startStart of date range to consider conversions from; see Date/Time Handling for formatting details. Defaults to 14 days ago.
period_endEnd of date range to consider conversions from; see Date/Time Handling for formatting details. Defaults to current date and time if not specified. The maximum difference between period_start and period_end is 90 days.
pub_date_startPublication filter start date; see Date/Time Handling for formatting details. This option is only available for posts.
pub_date_endPublication filter end date; see Date/Time Handling for formatting details. Defaults to current date and time if not specified. This option is only available for posts.
urlA specific URL to return conversions metrics for. This should match the canonical URL for the page in question. Defaults to returning metrics for all URLs if none is specified.
limitNumber of records to retrieve; defaults to 10. Maximum is 2000.
pagePage number to retrieve if multiple pages are available; defaults to 1. Retrieving a page that is unavailable returns an empty record list.
callbackJSON-P callback, a JavaScript function name that will be used to wrap the JSON response. The API also supports Cross-Origin Response Sharing.
author(page_type=post only) Filter the current top posts by one or more authors.
tag(page_type=post only) Filter the current top posts by one or more tags.
section(page_type=post only) Filter the current top posts by a specific section.
segment(page_type=post only) Filter the current top posts by a specific segment.
channel(page_type=post only) Filter the current top posts by a specific channel (website, amp, or fbia).
campaign_id(page_type=post only) Filter the current top posts by a specific campaign ID.
campaign_medium(page_type=post only) Filter the current top posts by a specific campaign medium.
campaign_source(page_type=post only) Filter the current top posts by a specific campaign source.
campaign_content(page_type=post only) Filter the current top posts by a specific campaign content.
campaign_term(page_type=post only) Filter the current top posts by a specific campaign term.

The maximum pagination limit is 2000 records. You will receive an error from the API if you attempt to retrieve past record 2000 through any combination of page and limit.

Multiple conversion_type, conversion_label, author, and/or tag filters may be specified by repeating the parameter (e.g. ?tag=report&tag=tesla&tag`=evs). Each parameter supports up to a maximum of five values.

#/conversions/url/top

Returns a list of URLs sorted by conversion metrics. This is typically used to generate front page or article page widgets featuring your top-converting content. NOTE: In order to safely protect your API secret, you’ll want to pull this data in on your backend rather than making the API request on your frontend.

#Optional Parameters

attribution_typeDetermines which of our attribution models to use for computing conversion metrics. Either linear, last_touch, last_post_touched, or first_touch. Defaults to last_touch if not specified.
conversion_typeOne or more conversion types to use for computing conversion metrics. Using this filter will result in conversion metrics being aggregated across all of your conversion labels of these types. Either newsletter_signup, custom, lead_capture, link_click, subscription, purchase. Defaults to aggregating metrics across all conversion types if not specified.
conversion_labelOne or more of your custom conversion labels. Defaults to aggregating metrics across all of your conversion labels if not specified.
page_typeOne or more page types to consider conversions from. Either post, sectionpage, frontpage, or index. Defaults to returning conversions across all page types if not specified.
period_startStart of date range to consider conversions from; see Date/Time Handling for formatting details. Defaults to 14 days ago.
period_endEnd of date range to consider conversions from; see Date/Time Handling for formatting details. Defaults to current date and time if not specified. The maximum difference between period_start and period_end is 90 days.
pub_date_startPublication filter start date; see Date/Time Handling for formatting details. This option is only available for posts.
pub_date_endPublication filter end date; see Date/Time Handling for formatting details. Defaults to current date and time if not specified. This option is only available for posts.
sortEither conversions or converting_visitors, if that feature is enabled; defaults to conversions.
limitNumber of records to retrieve; defaults to 10. Maximum is 2000.
pagePage number to retrieve if multiple pages are available; defaults to 1. Retrieving a page that is unavailable returns an empty record list.
callbackJSON-P callback, a JavaScript function name that will be used to wrap the JSON response. The API also supports Cross-Origin Response Sharing.
author(page_type=post only) Filter the current top posts by one or more authors.
tag(page_type=post only) Filter the current top posts by one or more tags.
section(page_type=post only) Filter the current top posts by a specific section.
segment(page_type=post only) Filter the current top posts by a specific segment.
channel(page_type=post only) Filter the current top posts by a specific channel (website, amp, or fbia).
campaign_id(page_type=post only) Filter the current top posts by a specific campaign ID.
campaign_medium(page_type=post only) Filter the current top posts by a specific campaign medium.
campaign_source(page_type=post only) Filter the current top posts by a specific campaign source.
campaign_content(page_type=post only) Filter the current top posts by a specific campaign content.
campaign_term(page_type=post only) Filter the current top posts by a specific campaign term.

The maximum pagination limit is 2000 records. You will receive an error from the API if you attempt to retrieve past record 2000 through any combination of page and limit.

Multiple conversion_type, conversion_label, author, and/or tag filters may be specified by repeating the parameter (e.g. ?tag=report&tag=tesla&tag=evs). Each parameter supports up to a maximum of five values.

Ready to get started with Parse.ly?

Questions?

Or

rocket emoji