Retrieve a campaign or asset report (get)

The get Ortto endpoint of the report entity is used to retrieve a campaign or an asset report. It enables you to retrieve reports for:

Campaigns: email, SMS, push notification, journey, and playbook.
Campaign assets/shapes/messages: email, SMS, and push notifications within journeys and playbooks.
A/B tested campaigns and campaign assets (as a comparison or variant A/B report, with or without a winner).

NOTE:

This request can only be made for campaigns which have been sent – it cannot retrieve data on campaigns which are scheduled or in a draft state.
There is a report request limit of 60 requests per 10 minutes.

This page provides descriptions of this endpoint’s:

request resource and method,
valid parameters, headers, and request body values, as well as
the response payload.

HTTP method and request resources

Campaign report endpoint


 POST https://api.ap3api.com/v1/campaign/reports/get

NOTE: Ortto customers who have their instance region set to Australia or Europe will need to use specific service endpoints relative to the region:

Australia: https://api.au.ap3api.com/
Europe: https://api.eu.ap3api.com/

For example: https://api.eu.ap3api.com/v1/<entity/endpoint>

All other Ortto users will use the default service endpoint (https://api.ap3api.com/).

Path and query parameters

This endpoint takes no additional path and/or query parameters.

Headers

This endpoint requires a custom API key and content type (application/json for the request body) in the header of the request:

X-Api-Key: CUSTOM-PRIVATE-API-KEY
Content-Type: application/json

Request body

The request body consists of a JSON object with the valid elements listed in the table below.

To get the ID for a campaign, asset, shape, or message, view the required item in Ortto and copy the ID from the campaign/asset’s URL, or use the GET campaign calendar endpoint to access the asset_id.

Single-send campaigns (email, SMS and push notifications)

Below are sample JSON requests for retrieving reports on single-send email and SMS messages, and push notification campaigns.

For most single-send campaign requests (including requests for A/B tested campaigns where you want the comparison report), you only need to specify the campaign_id, which will return the performance report and related performance data (e.g. including revenue data).

For an A/B tested single-send campaign where you want to get the report for one of the variants (variant A report/variant B report), you need to supply the asset ID of the desired variant along with the campaign ID. See below an example of that request, including how to find the variant asset ID value.

NOTE: By default, a request for a single-send campaign report will retrieve report data for all time. A timeframe cannot be set on these request types.

Example retrieve an email, SMS or push notification campaign report request body

json
 {
 "campaign_id": "660f29e1c6e6a097e7b0ac9f"
}

Example retrieve an A/B tested campaign variant report request body

json
 {
 "campaign_id": "660f29e1c6e6a097e7b0ac9f",
 "asset_id": "65c9d2711de06dcc18b076b3"
}

NOTE: To find the asset ID of variant A or B of an A/B campaign, use the GET campaign calendar endpoint and within the desired campaign object, look at the a_b_testing object and you can find the assets under:

variant_a_asset_id or
variant_a_asset_id

For an email campaign that has been resent to contacts who didn't open the original email, the report for the first send and the resend are separate, and must be fetched separately using the asset_id of the original email asset and the resend id for the second send. Both of these IDs can be accessed via the GET campaign calendar endpoint.

Journey and playbook campaigns (including message assets)

Below is a series of example JSON requests for retrieving reports on journey and playbook campaigns, and the assets used within them (i.e. email and SMS message shapes, and push notification shapes in a journey; email messages in a playbook).

NOTE: By default, the request will retrieve report data from the last month. You can change this to any of the options you would usually be able to select when creating a report (e.g. last 7 days, last 14 days, last quarter). The timeframe options are listed in the Report timeframes table.

Example retrieve a journey or playbook campaign report request body

json
 {
  "campaign_id": "660f29e1c6e6a097e7b0ac9f",
  "timeframe": "last-14-days"
}

Example retrieve a journey shape A/B test variant (email, SMS or push notification asset) report request body

json
 {
    "campaign_id": "660f29e1c6e6a097e7b0ac9f",
	"asset_id": "661e36a9c1e688f232b46681",
	"shape_id": "6"
}

Example retrieve a playbook message (email) report request body

json
 {
  "campaign_id": "660f29e1c6e6a097e7b0ac9f",
  "message_id": "006600ffde1b4f1067ff6a69"
}

Valid request body elements

The following table lists all valid, optional request body elements (arrays, objects, or fields), which are available to this endpoint.

Element	Type	Description
`campaign_id`	`string`	The ID of the campaign for which you wish to retrieve a report.
`asset_id`	`string`	The ID of the asset/shape/message for which you wish to retrieve a report.
`shape_id`	`string`	The ID of the journey shape for which you wish to retrieve a report.
`message_id`	`string`	The ID of the playbook email message for which you wish to retrieve a report.
`timeframe`	`string`	The timeframe for which you want the report to return data. The timeframe takes any of the string values listed in the Report timeframes table, for example `"timeframe: "last-7-days"`.

Element matrix

This matrix provides an overview of the element permutations.

Open image in a new tab to view a larger version

Report timeframes

A table listing the timeframe value options for retrieving reports on journeys or playbooks is available at Report timeframes.

NOTE: Timeframe values are calculated according to the timezone set in your Ortto account (at Settings > General > Timezone) at the time the report is generated.

Response payload

The response payload consists of a JSON object with the elements listed in the table below.

The following JSON object is an example of the custom field data that Ortto retrieves from your Ortto account’s CDP after a request to this endpoint.

Example retrieve an email, SMS or push notification campaign report request body

json
 {
    "last_updated": "2024-02-08T23:58:49.312Z",
    "timeframe": {
        "type": "",
        "custom_from": {
            "year": 0,
            "month": 0,
            "day": 0,
            "timezone": "UTC"
        },
        "custom_to": {
            "year": 0,
            "month": 0,
            "day": 0,
            "timezone": "UTC"
        }
    },
    "precision": "",
    "report_type": "revenue",
    "attr_model": "",
    "reports": {
        "performance": {
            "name": "Performance",
            "revenue": 0,
            "conversions": 0,
            "asp": 0,
            "sent": 1,
            "deliveries": 1,
            "clicks": 1,
            "unique_clicks": 1,
            "unique_deliveries": 0,
            "unique_sent": 0,
            "last_clicked": "Thu Jan 11 2024 10:29 AM",
            "invalid": 0,
            "unique_invalid": 0,
            "not_delivered": 0
        },
        "message_performance": {
            "name": "24 hours performance",
            "chart_type": "line-graph",
            "from": "2024-01-10T23:58:09.638Z",
            "to": "2024-01-11T23:58:09.638Z",
            "timezone": "Australia/Adelaide",
            "timeframe": {
                "type": "custom",
                "custom_from": {
                    "year": 2024,
                    "month": 1,
                    "day": 11,
                    "timezone": "Australia/Adelaide"
                },
                "custom_to": {
                    "year": 2024,
                    "month": 1,
                    "day": 12,
                    "timezone": "Australia/Adelaide"
                },
                "custom_from_hour": 10,
                "custom_to_hour": 10
            },
            "time_precision": "hours",
            "is_cumulative": true,
            "snapshot": {
                "graph": [
                    {
                        "t": "20240111:10",
                        "v": {
                            "0": 1,
                            "1": 1
                        }
                    }
				//<Extra graph plot points removed for brevity>
                ],
                "legend": [
                    {
                        "label": "Opens",
                        "type": "integer"
                    },
                    {
                        "label": "Clicks",
                        "type": "integer"
                    },
                    {
                        "label": "Conversions",
                        "type": "integer"
                    }
                ]
            }
        },
        "top_links": {
            "name": "Top links",
            "links": [
                {
                    "url": "https:#anchor",
                    "clicks": 1
                }
            ]
        },
        "products": {
            "name": "Products sold from this campaign",
            "items": []
        },
        "revenue": {
            "name": "Attributed orders and revenue",
            "conversions": 0,
            "clicked": 1,
            "opened": 1,
            "unique_clicked": 1,
            "unique_clicked_raw": 1,
            "unique_clicked_base": 1,
            "unique_delivered": 0,
            "unique_opened": 1,
            "delivered": 1,
            "revenue": 0,
            "bounced": 0,
            "invalid": 0,
            "asp": 0
        },
        "revenue_graph": {
            "name": "Attributed revenue",
            "chart_type": "line-graph",
            "from": "2024-01-10T23:58:09.638Z",
            "to": "2024-01-11T23:58:09.638Z",
            "timezone": "Australia/Adelaide",
            "timeframe": {
                "type": "custom",
                "custom_from": {
                    "year": 2024,
                    "month": 1,
                    "day": 11,
                    "timezone": "Australia/Adelaide"
                },
                "custom_to": {
                    "year": 2024,
                    "month": 1,
                    "day": 12,
                    "timezone": "Australia/Adelaide"
                },
                "custom_from_hour": 10,
                "custom_to_hour": 10
            },
            "time_precision": "hours",
            "is_cumulative": true,
            "snapshot": {
                "graph": [
                    {
                        "t": "20240111:10",
                        "v": {
                            "0": 0
                        }
                    },
      			//<Extra graph plot points removed for brevity>
                ],
                "legend": [
                    {
                        "label": "Revenue",
                        "type": "currency"
                    }
                ]
            }
        },
        "ios_performance": null,
        "android_performance": null,
        "web_performance": null
    },
    "report_content_type": ""
}

Example retrieve a journey shape (email) A/B test variant report request body

json
 {
    "last_updated": "2024-04-16T08:34:08.615Z",
    "timeframe": {
        "type": "last-month",
        "custom_from": {
            "year": 0,
            "month": 0,
            "day": 0,
            "timezone": "UTC"
        },
        "custom_to": {
            "year": 0,
            "month": 0,
            "day": 0,
            "timezone": "UTC"
        }
    },
    "precision": "days",
    "report_type": "revenue",
    "attr_model": "last",
    "reports": {
        "email_summary": {
            "chart_type": "line-graph",
            "from": "2024-02-29T13:30:00Z",
            "is_cumulative": true,
            "name": "Email summary",
            "snapshot": {
                "graph": [
                    {
                        "t": "20240301",
                        "v": {
                            "0": 0,
                            "1": 0,
                            "2": 0,
                            "3": 0,
                            "4": 0
                        }
                    },	              
                    //<Extra graph plot points removed for brevity>                
                ],
                "legend": [
                    {
                        "label": "Opens",
                        "type": "integer"
                    },
                    {
                        "label": "Clicks",
                        "type": "integer"
                    },
                    {
                        "label": "Conversions",
                        "type": "integer"
                    },
                    {
                        "label": "Invalid",
                        "type": "integer"
                    },
                    {
                        "label": "Bounced",
                        "type": "integer"
                    }
                ]
            },
            "time_precision": "days",
            "timeframe": {
                "custom_from": 0,
                "custom_to": 0,
                "type": "last-month"
            },
            "timezone": "Australia/Adelaide",
            "to": "2024-03-31T13:29:59Z"
        },
        "performance": {
            "name": "Performance",
            "sentiment": {},
            "unique_clicks_base": 0,
            "unique_clicks_raw": 0
        },
        "products": {
            "items": [],
            "name": "Products sold from this campaign"
        },
        "reactions": {
            "graph": {
                "angry": 0,
                "dislike": 0,
                "like": 0,
                "love": 0,
                "ok": 0
            },
            "latest_reactions": [],
            "name": "Reactions"
        },
        "revenue": {
            "asp": 0,
            "bounced": 0,
            "clicked": 0,
            "conversions": 0,
            "delivered": 0,
            "invalid": 0,
            "name": "Attributed orders and revenue",
            "opened": 0,
            "revenue": 0,
            "unique_clicked": 0,
            "unique_clicked_base": 0,
            "unique_clicked_raw": 0,
            "unique_delivered": 0,
            "unique_opened": 0
        },
        "revenue_graph": {
            "chart_type": "line-graph",
            "from": "2024-02-29T13:30:00Z",
            "is_cumulative": true,
            "name": "Attributed revenue",
            "snapshot": {
                "graph": [
                    {
                        "t": "20240301",
                        "v": {
                            "0": 0
                        }
                    },
                   //<Extra graph plot points removed for brevity>
                ],
                "legend": [
                    {
                        "label": "Revenue",
                        "type": "currency"
                    }
                ]
            },
            "time_precision": "days",
            "timeframe": {
                "custom_from": 530629367,
                "custom_to": 530644727,
                "type": "custom"
            },
            "timezone": "Australia/Adelaide",
            "to": "2024-03-31T13:29:59Z"
        },
        "top_base_links": {
            "name": "Top base links"
        },
        "top_links": {
            "name": "Top links"
        },
        "top_locations": {
            "chart_type": "geo-chart",
            "name": "Top opens by location",
            "snapshot": {
                "graph": [],
                "label": "Top opens by location",
                "legend": []
            }
        },
        "top_raw_links": {
            "name": "Top raw links"
        }
    },
    "report_content_type": "",
    "asset_a": {
        "id": "661e36a9c1e688f232b46681",
        "name": "Journey asset for API campaign report (Variant A)",
        "subject": "Subject A API test",
        "subject_json": {
            "preview": "Subject A API test",
            "tags": [
                {
                    "id": "",
                    "type": "text",
                    "icon": "",
                    "title": "Subject A API test",
                    "display_type": "",
                    "liquid_name": "",
                    "default_value": "",
                    "format_option": "",
                    "field_id": "",
                    "activity_id": ""
                }
            ]
        },
        "folder_id": "000000000000000000000000",
        "instance_id": "yourorttoaccount",
        "state": "published",
        "published_at": "2024-04-16T08:28:53.041Z",
        "type": "email",
        "campaign_id": "661e3652ef6156fbe716648c",
        "campaign_type": "journey",
        "campaign_name": "A/B test for API",
        "created_at": "2024-04-16T08:28:25.55Z",
        "created_by_name": "user@email.com",
        "edited_at": "2024-04-16T08:28:53.041Z",
        "edited_by_name": "user@email.com",
        "font_families": [
            "Arvo",
            "ComicSansMS"
        ],
        "draft": {
            "name": "Journey asset for API campaign report (Variant A)",
            "subject": "Subject A API test",
            //<Extra Draft email content removed for brevity>
        "published": {
            "name": "Journey asset for API campaign report (Variant A)",
            "subject": "Subject A API test",
            //<Extra Published email content removed for brevity>
       }

Response payload elements

The following table lists all elements (arrays, objects, or fields) in the response from a request to this endpoint.

Element	Type	Description
`last_updated`	`string`	The time and date the campaign was last updated
`timeframe`	object	The timeframe for the report data
`precision`	`string`	The precision value by which the report data is presented, e.g. `days`
`report_type`	`string`	The report type for the campaign, e.g. `revenue`
`attr_model`	`string`	The attribution model set for the campaign, e.g. `last` for Last touch
`reports`	object	The reports object can include the following properties (depending on the campaign type): `performance/variant_a/b_performance`: key performance metrics for the campaign, including open rate and click rate. Learn more about these campaign statistics and how they are calculated. `message_performance/variant_a/b_snapshot/compare_snapshots`: a line graph showing key metrics including opens, clicks and conversions. `products`: where you have an e-commerce data source connected, you can see product metrics associated with this campaign `revenue`: key campaign metrics including any revenue attributed to the campaign `revenue_graph/variant_a/b_revenue_graph/compare_revenue_graph`: a graph of key campaign metrics including any revenue attributed to the campaign `android_performance`: push notification metrics for sends to Android devices `ios_performance`: push notification metrics for sends to iOS devices `web_performance`: push notification metrics for sends to web browsers `email_summary/summary`: a graph showing the opens, clicks, conversions, invalid and bounced metrics. `reactions`: a summary of the reaction icons clicked by recipients `sentiment`: the overall positive, neutral or negative response to the message based on reactions `top_links/top_raw_links/top_base_links`: a list of the most-clicked links in the campaign `top_locations/top_opens`: data showing the top locations in which recipients engaged with the campaign `survey_responses`: for SMS campaigns, the survey response report data as a graph and an array of latest responses `redeemed_coupons`: for SMS campaigns, an array of redeemed coupons `confirmed`: for SMS campaigns, a graph showing recipient confirmations using the confirmation link `sent_by_countrycode`: for SMS campaigns, data on the number of sent SMS messages by country code.
`report_content_type`	`string`	The type of report show in the graph data included with the `message_performance` report property, e.g. `deliveries`, `clicks`
`asset`	object	The `asset` object contains the asset’s data, such as the name and subject of the asset, and its content (such as the HTML of an email asset body).
`folder_id`	`string`	The ID of the folder in which the campaign is stored (if applicable)
`instance_id`	`string`	The name of the Ortto account (instance) from which the data was retrieved
`state`	`string`	The state of the asset, e.g. draft, published
`published_at`	`string`	The time and date the asset was published
`type`	`string`	The type of asset, e.g. `email`
`campaign_id`	`string`	The unique identifier for the campaign
`campaign_type`	`string`	The type of campaign, e.g. `journey`
`campaign_name`	`string`	The name given to the campaign
`created_at`	`string`	The time and date the campaign was created
`created_by_name`	`string`	The name of the Ortto account user who created the campaign
`edited_at`	`string`	The time and date the campaign was last edited
`edited_by_name`	`string`	The name of the Ortto account user who last edited the campaign
`draft`	object	The content of the asset in its draft state, including its setup details
`published`	object	The content of the asset in its published state, including its setup details