API: Conversions endpoint use and overview
The Parse.ly Conversions API addresses 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/api-top-10-endpoint/). 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_type | Determines 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_type | One 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_label | One or more of your custom conversion labels. Defaults to returning conversion label-level metrics for all of your conversion labels if not specified. |
| page_type | One or more page types to consider conversion from. Either post or index. Defaults to returning conversions across all page types if not specified. |
| period_start | Start of date range to consider conversions from; see Date/Time Handling for formatting details. Defaults to 3 days ago. |
| period_end | End 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 14 days. |
| pub_date_start | Publication filter start date; see Date/Time Handling for formatting details. This option is only available for posts. |
| pub_date_end | Publication 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. |
| url | A 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. |
| limit | Number of records to retrieve; defaults to 10. Maximum is 2000. |
| page | Page number to retrieve if multiple pages are available; defaults to 1. Retrieving a page that is unavailable returns an empty record list. |
| callback | JSON-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/api-top-10-endpoint/
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_type | Determines 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_type | One 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_label | One or more of your custom conversion labels. Defaults to aggregating metrics across all of your conversion labels if not specified. |
| page_type | One 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_start | Start of date range to consider conversions from; see Date/Time Handling for formatting details. Defaults to 14 days ago. |
| period_end | End 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_start | Publication filter start date; see Date/Time Handling for formatting details. This option is only available for posts. |
| pub_date_end | Publication 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. |
| sort | Either conversions or converting_visitors, if that feature is enabled; defaults to conversions. |
| limit | Number of records to retrieve; defaults to 10. Maximum is 2000. |
| page | Page number to retrieve if multiple pages are available; defaults to 1. Retrieving a page that is unavailable returns an empty record list. |
| callback | JSON-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.
Last updated: August 15, 2024