Reporting API Guide
Introduction
The following documentation reviews the REST API (Application Programming Interface) for authenticating and accessing Reporting data on the Webcast platform.
This API require API credentials to be created for your company. These credentials are used to authenticate your account before you can access Webcast report data. To request an API account, please contact Support for assistance.
Authentication
In order to access Webcast reporting data, you must first authenticate using your Webcast API credentials. Below is an exmaple of a Authentication Request. After successful authentication, you will be provided with Session ID and User ID that will be used to access reporting data.
The bold values in this example need to be updated to include your API Username and Password in the corresponding fields. Refer to the example URL and Parameters below for more details. Contact Support to request an API account.
Sample Authentication Request
https://api.webcasts.com/api/login?username=Username&password=Password&ver=2.0
| Parameter | Description |
|---|---|
| Authorized API Username | |
| Authorized API Password | |
| API Version Number (2.0) |
XML Return on Authentication Success
Properly formatted requests will return the following XML like seen in the example below:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<convey_api version="2.0">
<currentDateTime>2019-05-15 14:39:09</currentDateTime>
<currentTimeZone>GMT</currentTimeZone >
<result>
<returnCode>1</returnCode>
<success>
<sessionid>
<description>Authenticated session ID.</description>
<value>00e60096592bdead6feb1cf3112c2f68d988d5ec</value>
</sessionid>
<userid>
<description>Authenticated user ID.</description>
<value>9b21cf03885a7677bdf835d7aa857075dcbf753c</value>
</userid>
</success>
</result>
</convey_api>
Authentication Result Nodes
| Node/Node Attribute | Description |
|---|---|
| Session ID | |
| User ID | |
| Defines the API version. Requests should include "2.0" as this value. | |
| Timestamp of report creation | |
| Selected time zone for all times displayed in this report. If none is defined, it will default to GMT. | |
| Result of the API request. A value of 1 indicates a successful result. Other values indicate failures and correspond to specific error messages defined in the section "XML Return Codes on Failure". | |
| Node contains all event data returned. |
Time Zone Values Request
To pull a list of all available time zone values, connect to the URL below via https GET or Post. The supported Time Zone value is based on the JVM version being used, which may change periodically.
The bold values in this example need to be updated to include your User ID and Session ID in the corresponding fields. Refer to the example URL and Parameters below for more details.
Sample Time Zone Request
https://reporting.webcasts.com/api/reporting/timezones?ui=USER_ID&si=SESSION_ID
XML Return on Time Zone Request
<convey_api>
<timezone_id>Etc/GMT+12</timezone_id>
<timezone_id>Etc/GMT+11</timezone_id>
<timezone_id>Pacific/Midway</timezone_id>
<timezone_id>Pacific/Niue</timezone_id>
<timezone_id>Pacific/Pago_Pago</timezone_id>
<timezone_id>Pacific/Samoa</timezone_id>
<timezone_id>US/Samoa</timezone_id>
<timezone_id>America/Adak</timezone_id>
<timezone_id>America/Atka</timezone_id>
<timezone_id>Etc/GMT+10</timezone_id>
<timezone_id>HST</timezone_id>
<timezone_id>Pacific/Honolulu</timezone_id>
<timezone_id>Pacific/Johnston</timezone_id>
<timezone_id>Pacific/Rarotonga</timezone_id>
<timezone_id>Pacific/Tahiti</timezone_id>
...
</convey_api>
Event Reporting Request
To access reporting data for a Webcast event, connect to the URL below via https GET or Post. Accounts must have permission to view reporting for the requested Event ID.
The bold values in this example need to be updated to include your User ID, Session ID, Event ID and Data Format in the corresponding fields. A "DATA_FORMAT" can be specified or if the parameter can is removed, reports will default to XML format. Addtional parameters can be added to your request. Refer to the example URL and tables below for more details.
Sample Report Request
Data Format Options
| URL Data Format Parameter | Description | Content-Type |
|---|---|---|
| XML Format (default return type) | application/xml;charset=utf-8 | |
| JSON Format | application/json;charset=utf-8 | |
| CSV Format | text/plain;charset=utf-8 |
Available Parameters
| Parameter | Description |
|---|---|
| Valid User ID | |
| Valid Session ID | |
| Defines the API version. Requests should include "2.0" as this value. | |
| Webcast Event ID | |
| Time Zone for all times displayed in this report. Defaults to GMT if undefined. | |
| Start date of the report date range. Timestamp is automatically set to 12:00:00 AM on the selected start date. | |
| End date of the report date range. Timestamp is automatically set to 11:59:59 PM on the selected end date. | |
| Restricts results by including only registrants who registered within the selected date range. If undefined, it will default to on. | |
| Restricts results by including only registrants who have viewing duration of any type within the selected date range. If undefined, it will default to on. | |
| Restricts results by including only registrants who accessed the event using a URL containing a Campaign Source Tracking Identifier. If undefined, it will default to off. Separate multiple values with pipes. | |
| Restricts results by excluding any registrants with emails on the specified domain. If undefined, it will default to off. Separate multiple values with pipes. Cannot be used with "inclu_domain". | |
| Restricts results by including any registrants with emails on the specified domain. If undefined, it will default to off. Separate multiple values with pipes. Cannot be used with "excl_domain". | |
| Restricts results by including only registrants who asked a question. If undefined, it will default to off. | |
| Restricts results by including only registrants who responded to one or more surveys. If undefined, it will default to off. | |
| Restricts results by including only registrants with no viewing sessions of any type. If undefined, it will default to off. | |
| Restricts results by including only registrants with one or more live viewing sessions. If undefined, it will default to off. | |
| Restricts results by including only registrants with one or more On-Demand or Archive viewing sessions. If undefined, it will default to off. | |
| Restricts results by including only registrants with one or more Sim-Live viewing sessions. If undefined, it will default to off. |
Notes:
- A "*" next to a parameter name in the table above indicates the field is required.
- A "**" next to a parameter name in the table above indicates the accepted values for parameter are "on" / "off" (case sensitive).
- Parameter values should be properly URL encoded (Ex. Blank spaces should be replaced with %20).
Report Request Examples
Request all user data for a single Webcast Event including registration information, questions and answers, survey responses, usage (viewing) and an overview of event analytics.
Click on a Report format below to view details on each request type.
Use these links to access a sample of a XML Return, a list of XML Nodes and a list of Return Codes for failed requests.
XML Return on Successful Request
<convey_api version="2.0">
<currentTimeZone>Eastern Standard Time</currentTimeZone>
<currentDateTime>12/20/2014 03:30:13 PM</currentDateTime>
<result>
<returnCode>
1</returnCode>
<report_type>Audience Details Report</report_type>
<report_date_range/>
<filters>
<sti_filter/>
<email_domain_exclude_filter/>
<email_domain_include_filter/>
<qa_data_filter>off</qa_data_filter>
<survey_data_filter>off</survey_data_filter>
<no_show_filter>off</no_show_filter>
<live_viewers_filter>off</live_viewers_filter>
<od_viewers_filter>off</od_viewers_filter>
<simlive_viewers_filter>off</simlive_viewers_filter>
</filters>
<report_data>
<eventid>123456</eventid>
<eventtitle>API Report Sample</eventtitle>
<costcenter>Marketing</costcenter>
<event_create_time>11/04/2014 02:39:43 PM</event_create_time>
<live_start_time>11/04/2014 03:04:01 PM</live_start_time>
<live_end_time>11/04/2014 03:08:07 PM</live_end_time>
<od_first_published_time>11/04/2014 03:08:00 PM</od_first_published_time>
<od_expiration_time>05/04/2015 03:03:40 PM</od_expiration_time>
<event_analytics>
<total_sessions>5</total_sessions>
<total_registrants>6</total_registrants>
<no_shows>2</no_shows>
<total_conversion_rate>66.7%</total_conversion_rate>
<live_sessions>1</live_sessions>
<unique_live_viewers>1</unique_live_viewers>
<live_registrants>2</live_registrants>
<live_conversion_rate>50%</live_conversion_rate>
<od_sessions>3</od_sessions>
<unique_od_viewers>2</unique_od_viewers>
<simlive_sessions>1</simlive_sessions>
<unique_simlive_viewers>1</unique_simlive_viewers>
</event_analytics>
<registration_questions>
<rq id="firstname">First Name</rq>
<rq id="lastname">Last Name</rq>
<rq id="company">Company</rq>
<rq id="email">Email</rq>
<rq id="title">Title</rq>
<rq id="country">Country</rq>
<rq id="address1">Address 1</rq>
<rq id="address2">Address 2</rq>
<rq id="city">City</rq>
<rq id="state">State/Province/Region</rq>
<rq id="postalcode">Postal Code</rq>
<rq id="phone">Phone Number</rq>
<rq id="mobile">Mobile Number</rq>
<rq id="fax">Fax Number</rq>
<rq id="source_track_id">Campaign ID</rq>
<rq id="559607bd0f63f65f6892eff0477b5be1c123582d_123456">Department</rq>
<rq id="86cb4cddbaf8762010db311d9e035d59c755ad3a_123456">Have you previously attended one of our webcasts?</rq>
</registration_questions>
<surveys>
<survey id="5458e5c0bef1f4.34548499" name="Halftime Survey" type="In Event">
<sq id="5458e5d1ee0891.61344744" type="Radio Vertical">Are you enjoying this presentation?</sq>
<sq id="5458e5c1451728.31353993" type="Textbox">Is there any topic that you would like us to discuss in a future webcast?</sq>
</survey>
<survey id="5458e5eee7e073.49742677" name="Attendance Check" type="Attendance"/>
<survey id="5458e61d2dca04.58375990" name="Ending Questionaire" type="Post Event">
<sq id="5458e6d05a6341.17478629" type="Checkbox Vertical">Which of the following social media platforms do you use regularly for your business?</sq>
<sq id="5458e61d96b9a3.90404248" type="Radio Vertical">Do you directly manage your company's social media accounts?</sq>
<sq id="5458e62d69a857.50529993" type="Text Area">What is your business's Twitter handle?</sq>
</survey>
</surveys>
<viewers>
<viewer>
<registration_date>11/04/2014 07:53:35 PM</registration_date>
<registration_answers>
<ra id="firstname">Alice</ra>
<ra id="lastname">Williams</ra>
<ra id="company">YourCo</ra>
<ra id="email">awilliams@yourco.com</ra>
<ra id="source_track_id">Linkedin Campaign</ra>
<ra id="559607bd0f63f65f6892eff0477b5be1c123582d_123456">Marketing</ra>
<ra id="86cb4cddbaf8762010db311d9e035d59c755ad3a_123456">Yes</ra>
</registration_answers>
<sessions>
<session>
<type>Live</type>
<start_time>11/04/2014 08:04:01 PM</start_time>
<end_time>11/04/2014 08:08:07 PM</end_time>
<duration>246000</duration>
<media/>
</session>
</sessions>
<qa>
<question>
How do you engage with customers using social media in a meaningful way?
<answer>Great question! We will be addressing this shortly.</answer>
</question>
<question>
Is there a way to more easily follow / unfollow large numbers of users on twitter?
</question>
</qa>
<survey_responses>
<sr survey_id="5458e5c0bef1f4.34548499" question_id="5458e5c1451728.31353993">I'd
love to hear more about advertising on social media.</sr>
<sr survey_id="5458e5c0bef1f4.34548499"
question_id="5458e5d1ee0891.61344744">Yes</sr>
<sr survey_id="5458e5eee7e073.49742677">Yes</sr>
<sr survey_id="5458e61d2dca04.58375990"
question_id="5458e61d96b9a3.90404248">No</sr>
<sr survey_id="5458e61d2dca04.58375990"
question_id="5458e62d69a857.50529993">@yourcompany</sr>
<sr survey_id="5458e61d2dca04.58375990"
question_id="5458e6d05a6341.17478629">Twitter | Facebook | Pinterest</sr>
</survey_responses>
</viewer>
<viewer>
<registration_date>11/04/2014 07:54:29 PM</registration_date>
<registration_answers>
<ra id="firstname">Michael</ra>
<ra id="lastname">Scott</ra>
<ra id="company">CompanyX</ra>
<ra id="email">mscott@companyx.com</ra>
</registration_answers>
<sessions>
<session>
<type>On-Demand</type>
<start_time>12/10/2014 11:50:18 PM</start_time>
<end_time>12/10/2014 11:51:30 PM</end_time>
<duration>72000</duration>
<media/>
</session>
<session>
<type>On-Demand</type>
<start_time>12/11/2014 10:20:30 PM</start_time>
<end_time>12/11/2014 10:22:47 PM</end_time>
<duration>137000</duration>
<media/>
</session>
</sessions>
<qa/>
<survey_responses/>
</viewer>
<viewer>
<registration_date>11/04/2014 08:33:47 PM</registration_date>
<registration_answers>
<ra id="firstname">Martin</ra>
<ra id="lastname">Thomas</ra>
<ra id="company">Second City Bank</ra>
<ra id="email">mthomas@secondcitybank.com</ra>
</registration_answers>
<sessions>
<session>
<type>On-Demand</type>
<start_time>11/04/2014 08:33:47 PM</start_time>
<end_time>11/04/2014 08:37:52 PM</end_time>
<duration>245000</duration>
<media/>
</session>
</sessions>
<qa>
<question>
How can I use Twitter to increase sales on my website?
</question>
</qa>
<survey_responses>
<sr survey_id="5458e5c0bef1f4.34548499"
question_id="5458e5c1451728.31353993">ecommerce</sr>
<sr survey_id="5458e5c0bef1f4.34548499"
question_id="5458e5d1ee0891.61344744">Yes</sr>
<sr survey_id="5458e5eee7e073.49742677">Yes</sr>
<sr survey_id="5458e61d2dca04.58375990"
question_id="5458e61d96b9a3.90404248">No</sr>
<sr survey_id="5458e61d2dca04.58375990"
question_id="5458e62d69a857.50529993">@secondcitybank</sr>
<sr survey_id="5458e61d2dca04.58375990"
question_id="5458e6d05a6341.17478629">Twitter</sr>
</survey_responses>
</viewer>
<viewer>
<registration_date>11/04/2014 08:39:09 PM</registration_date>
<registration_answers>
<ra id="firstname">Alexandra</ra>
<ra id="lastname">Graystone</ra>
<ra id="company">Company X</ra>
<ra id="email"agraystone@companyx.com</ra>
<ra id="559607bd0f63f65f6892eff0477b5be1c123582d_123456">Engineering</ra>
<ra id="86cb4cddbaf8762010db311d9e035d59c755ad3a_123456">No</ra>
</registration_answers>
<qa/>
<survey_responses/>
</viewer>
<viewer>
<registration_date>11/04/2014 08:40:41 PM</registration_date>
<registration_answers>
<ra id="firstname">Marie</ra>
<ra id="lastname">Davis</ra>
<ra id="company">Your Co</ra>
<ra id="email">mdavis@yourco.com</ra>
<ra id="559607bd0f63f65f6892eff0477b5be1c123582d_123456">Product Strategy</ra>
<ra id="86cb4cddbaf8762010db311d9e035d59c755ad3a_123456">Yes</ra>
</registration_answers>
<qa/>
<survey_responses/>
</viewer>
<viewer>
<registration_date>11/04/2014 08:41:39 PM</registration_date>
<registration_answers>
<ra id="firstname">Arthur</ra>
<ra id="lastname">Collins</ra>
<ra id="company">2nd City Bank</ra>
<ra id="email">arthur.collins@gmail.com</ra>
<ra id="559607bd0f63f65f6892eff0477b5be1c123582d_123456">Sales</ra>
<ra id="86cb4cddbaf8762010db311d9e035d59c755ad3a_123456">No</ra>
</registration_answers>
<sessions>
<session>
<type>SimLive</type>
<start_time>11/04/2014 08:41:40 PM</start_time>
<end_time>11/04/2014 08:49:08 PM</end_time>
<duration>448000</duration>
<media/>
</session>
</sessions>
<qa/>
<survey_responses>
<sr survey_id="5458e5c0bef1f4.34548499"
question_id="5458e5c1451728.31353993">not
sure</sr>
<sr survey_id="5458e5c0bef1f4.34548499"
question_id="5458e5d1ee0891.61344744">Yes</sr>
<sr survey_id="5458e5eee7e073.49742677">Yes</sr>
<sr survey_id="5458e61d2dca04.58375990"
question_id="5458e61d96b9a3.90404248">No</sr>
<sr survey_id="5458e61d2dca04.58375990"
question_id="5458e62d69a857.50529993">I
don't know</sr>
<sr survey_id="5458e61d2dca04.58375990"
question_id="5458e6d05a6341.17478629">Facebook | Twitter</sr>
</survey_responses>
</viewer>
</viewers>
</report_data>
</result>
</convey_api>
Report Result Nodes
| Node/Node Attribute | Description | Values |
|---|---|---|
| answer | An answer from a presenter to question represented by the parent Question node | xs:string |
| convey_api | Defines the API version. Requests should include "2.0" as this value. | xs:complexType elements |
| costcenter | Displays Cost Center(s) for the selected event. Used for enhanced billing tracking. | xs:string |
| currentDateTime | Timestamp of report creation | xs:date |
| currentTimeZone | Selected time zone for all times displayed in this report. If none is defined, it will default to GMT. | xs:date |
| duration | The length of a single viewing session | xs:long |
| email_domain_exclude_filter | Restricts results by excluding any registrants with emails on the specified domain. | xs:string |
| email_domain_include_filter | Restricts results by including only registrants with emails on the specified domain. | xs:string |
| end | End date of the report date range. Timestamp is automatically set to 11:59:59 PM on the selected end date. | xs:date |
| end_time | Timestamp at the end of a viewing session | xs:date |
| event_analytics | Overview statistics for the presentation | xs:complexTypeelements |
| event_create_time | Timestamp of event creation | xs:date |
| eventid | Selected event ID | xs:string |
| eventtitle | Selected event name | xs:string |
| filters | Shows the values of the filters applied to this report | xs:complexType elements |
| live_conversion_rate | The percentage of registrants, at the time the Live event concluded, that attended the Live event | xs:string |
| live_end_time | Timestamp at the conclusion of the Live event | xs:date |
| live_registrants | Number of Registrants at Live Event Conclusion | xs:int |
| live_sessions | Number of viewing sessions on the Live event | xs:int |
| live_start_time | Timestamp at the start of the Live event | xs:date |
| live_viewers_filter | Restricts results by including only registrants with one or more live viewing sessions | xs:string |
| media | Type of media player used in a viewing session | xs:string |
| no_show_filter | Restricts results by including only registrants with no viewing sessions of any type | xs:string |
| no_shows | Number of registrants that did not login to watch the event | xs:int |
| od_expiration_time | The date on which the On-Demand or Archive event will expire and no longer be accessible to viewers | xs:date |
| od_first_published_time | Timestamp when the event was originally archived or was first published | xs:date |
| od_sessions | Number of viewing sessions on the On-Demand or Archived event | xs:int |
| od_viewer_filter | Restricts results by including only registrants with one or more On-Demand or Archive viewing sessions | xs:string |
| qa | Node containing all Questions asked by the viewer and any Answers to those questions from a Presenter or Moderator. | xs:complexType elements |
| qa_data_filter | Restricts results by including only registrants who asked a question | xs:string |
| questoin | A question asked by a viewer | xs:complexType elements |
| ra | A response to a registration question. | xs:string |
| registration_answers | Node containing all responses to registration question for a single registrant | xs:complexType elements |
| registration_date | Timestamp when a single registrant submitted the registration form | xs:date |
| registration_date_filter | Restricts results by including only registrants who registered within the selected date range | xs:string |
| regisration_questions | Node containing a full list of all default and custom registration questions | xs:complexType elements |
| report_data | Node containing identifying information about the selected event | xs:complexType elements |
| report_date_range | Restricts results by including only activity within a selected date range. If no date range is defined, all data will be included in the report. | xs:complexType elements |
| report_type | Defines which type of report data is selected | xs:string |
| result | Node contains all event data returned | xs:complexType elements |
| returnCode | Result of the API request. A value of 1 indicates a successful result. Other values indicate failures and correspond to specific error messages defined in the section "XML Return Codes on Failure". | xs:int |
| rq | A registration question for the selected event | xs:string |
| session | A single viewing session | xs:complexType elements |
| sessions | Node containing all viewing sessions for an individual viewer | xs:complexType elements |
| simlive_sessions | Number of viewing sessions on the Simulated Live event | xs:int |
| simelive_viewers_filter | Restricts results by including only registrants with one or more Simulated Live viewing sessions | xs:string |
| sq | An survey question for the selected event | xs:string |
| sr | A survey response by a single viewer. The survey ID in the viewer's response corresponds to the survey ID found in the "surveys" node. | xs:string |
| start | Start date of the report date range. Timestamp is automatically set to 12:00:00 AM on the selected start date. | xs:date |
| start_time | Timestamp at the beginning of a viewing session | xs:date |
| sti_filter | Restricts results by including only registrants who accessed the event using a URL containing a Campaign Source Tracking Identifier | xs:string |
| survey | A single survey containing one or more questions from the selected event | xs:complexType elements |
| survey_data_filter | Restricts results by including only registrants who responded to one or more surveys | xs:string |
| survey_responses | Node containing survey responses from a single viewer | xs:complexType elements |
| surveys | Node containing all survey questions from the selected event | xs:complexType elements |
| total_conversion_rate | Percentage of Total Unique Registrants, not including No Shows, that logged in to the event | xs:string |
| total_registrants | Total number of registrants for the event | xs:int |
| total_sessions | Total number viewing sessions on the event | xs:int |
| type | Type of viewing session | xs:string |
| unique_live_viewers | Number of unique email addresses that viewed the Live event | xs:int |
| unique_od_viewers | Number of unique email addresses that viewed the On-Demand or Archived event | xs:int |
| unique_simlive_viewers | Number of unique email addresses that viewed the Simulated Live event | xs:int |
| viewer | Node containing data for a single unique registrant | xs:complexType elements |
| viewers | Node containing records for all unique registrants | xs:complexType elements |
| viewing_session_date_filter | viewing_session_date_filter | xs:string |
Return Codes for Failed Rquests
| Return Code | Description |
|---|---|
| 0 | General error |
| 1 | Success |
| 10 | You are not authorized to run a report on this event. Please check you have the correct Event ID. |
| 11 | The User ID or Session ID is invalid. |
| 50 | The reporting service is not available at this time. Please conact Support for assistance. |
| 51 | There was invalid data in the report. Please conact Support for assistance. |
| 60 | The reporting service is not available at this time. Please conact Support for assistance. |
| 61 | You have reached the maximum number of reports that can be run for an event. Please try again later. |
| 62 | You have reached the maximum number of reports that can be run within one hour. Please try again later. |
| 70 | Pleaes remove any insecure tages from the input paramters and try again. |
| 71 | Please use a valid version number ("2.0"). |
| 72 | There were missing or invalid input parameters in request. |
| 73 | Ambigous platform |
| 74 | Could not identify the Reporting Resource requested |
Use these links to access a sample of a JSON Return, a list of JSON Nodes and a list of Return Codes for failed requests.
JSON Return on Successful Request
{
"currentTimeZone":"Greenwich Mean Time",
"api_version":"2.0",
"report_run_time":"05/31/2017 02:19:32 PM",
"report_type":"Audience Details Report",
"event_data":{
"event_creation_date":"05/24/2017 03:25:03 PM",
"event_od_last_published_time":"",
"event_od_expiration_time":"11/24/2017 03:43:35 PM",
"event_duration":"00:11:00",
"event_live_start_time":"05/24/2017 03:37:28 PM",
"event_title":"Sample API Event",
"event_analytics":{
"unique_od_viewers":"0",
"total_registrants":"4",
"live_conversion_rate":"100%",
"od_sessions":"0",
"simlive_sessions":"0",
"unique_simlive_viewers":"0",
"total_conversion_rate":"100%",
"live_sessions":"7",
"unique_live_viewers":"4",
"live_registrants":"4",
"total_sessions":"7",
"no_shows":"0"
},
"event_id":"20786",
"event_live_end_time":"05/24/2017 03:48:28 PM",
"event_sim_live_scheduled_time":"",
"event_cost_center":"",
"event_creator":"admin1",
"event_pre_live_scheduled_time":"05/24/2017 04:00:00 PM"
},
"filters":{
"incl_domain":[
],
"od_viewers":false,
"user_survey":false,
"live_viewers":false,
"excl_domain":[
],
"simlive_viewers":false,
"sti_filter":[
],
"users_qa":false,
"no_shows":false
},
"data_headers":[
"Event Id",
"Event Title",
"Cost Center",
"Registered On",
"First Name",
"Last Name",
"Company",
"Email",
"Title",
"Country",
"Address 1",
"Address 2",
"City",
"State/Province/Region",
"Postal Code",
"Phone Number",
"Mobile Number",
"Fax Number",
"Sample Registration Question",
"Campaign ID",
"Live Sessions",
"On-Demand Sessions",
"SimLive Sessions",
"Total Sessions",
"Live Duration",
"On-Demand Duration",
"SimLive Duration",
"Total Duration",
"Referrer",
"Question 1",
"Answer 1",
"Question 2",
"Answer 2",
"Question 3",
"Answer 3",
"Survey: Sample Survey 1: Question 1",
"Survey: Sample Survey 1: Question 2",
"Survey: Sample Survey 2: Question 1",
"Survey: Sample Attendance Survey: ",
"Survey: Post Event Survey: Did you enjoy the webcast ?",
"sessions"
],
"data_rows":[
[
"20786",
"Sample API Event",
"",
"05/24/2017 03:30:40 PM",
"",
"",
"",
"user1@company.com",
"",
"",
"",
"",
"",
"",
"",
"",
"",
"",
"",
"3",
"0",
"0",
"3",
"00:33:00",
"00:00:00",
"00:00:00",
"00:33:00",
"",
"greta?",
"answer",
"good morning?",
"yes it is",
"another question",
"another answer",
"Answer 1|Answer 2",
"Answer 2|Answer 1",
"Answer 2|Answer 1",
"Yes|Yes|No",
"No|Yes|Yes",
[
[
"Live",
"05/24/2017 03:37:28 PM",
"05/24/2017 03:48:28 PM",
660000,
"Unknown"
],
[
"Live",
"05/24/2017 03:37:28 PM",
"05/24/2017 03:48:28 PM",
660000,
"Unknown"
],
[
"Live",
"05/24/2017 03:37:28 PM",
"05/24/2017 03:48:28 PM",
660000,
"Unknown"
]
]
],
[
"20786",
"Sample API Event",
"",
"05/24/2017 03:32:36 PM",
"Josh",
"Jones",
"Company",
"user2@company.com",
"Senior",
"United States of America",
"100 John Lane",
"",
"New York",
"New York",
"11111",
"888-888-8888",
"999-999-9999",
"111-111-1111",
"",
"1",
"0",
"0",
"1",
"00:11:00",
"00:00:00",
"00:00:00",
"00:11:00",
"",
"Answer 1",
"Yes",
"Yes",
[
[
"Live",
"05/24/2017 03:37:28 PM",
"05/24/2017 03:48:28 PM",
660000,
"Unknown"
]
]
],
[
"20786",
"Sample API Event",
"",
"05/24/2017 03:33:58 PM",
"Wilber",
"Smith",
"Company 2",
"user3@company.com",
"Jr",
"United States of America",
"2345 API Dr.",
"Apt 3",
"Boston",
"Massachusetts",
"23456",
"123-456-7890",
"098-765-4321",
"",
"",
"2",
"0",
"0",
"2",
"00:10:02",
"00:00:00",
"00:00:00",
"00:10:02",
00:10:02",
"",
"Answer 1",
"Answer 1",
"Answer 1",
"No",
[
[
"Live",
"05/24/2017 03:37:28 PM",
"05/24/2017 03:40:04 PM",
156000,
"Unknown"
],
[
"Live",
"05/24/2017 03:41:02 PM",
"05/24/2017 03:48:28 PM",
446000,
"HTML5 Video"
]
]
],
[
"20786",
"Sample API Event",
"",
"05/24/2017 03:41:33 PM",
"",
"",
"",
"user4@company.com",
"",
"",
"",
"",
"",
"",
"",
"",
"",
"",
"",
"1",
"0",
"0",
"1",
"00:06:54",
"00:00:00",
"00:00:00",
"00:06:54",
"",
"kool?",
"great webcast, very good",
[
[
"Live",
"05/24/2017 03:41:34 PM",
"05/24/2017 03:48:28 PM",
414000,
"Unknown"
]
]
]
]
}
Report Result Nodes
| Node/Node Attribute | Description | Values |
|---|---|---|
| report_type | Defines which type of report data is selected | json:string |
| api_version | Defines the API version. Requests should include "2.0" as this value. | json:string |
| currentTimeZone | Selected time zone for all times displayed in this report. If none is defined, it will default to GMT. | json:string |
| event_data | JSON object containing all event meta-data | json:object |
| event_data.event_creation_date | Formatted date date of event creation | json:string MM/DD/YYYY hh:mm:ss |
| event_data.last_published_time | Formatted date time of last instance event was published On-Demand | json:strong MM/DD/YYYY hh:mm:ss |
| event_data.event_id | Select Event ID | json:string |
| event_data.od_expiration_time | Formatted date on which the On-Demand or Archive event will expire and no longer be accessible to viewers | json:string MM/DD/YYYY hh:mm:ss |
| event_data.event_live_end_time | Formatted timestamp of conclusion for the Live event | json:string MM/DD/YYYY hh:mm:ss |
| event_data.sim_live_scheduled_time | Formatted timestamp of the scheduled start time for a Simlive event | json:string MM/DD/YYYY hh:mm:ss |
| event_data.event_duration | Formatted time interval for total event duration | json:string hh:mm:ss |
| event_data.event_cost_center | json:string | Displays Cost Center(s) for the selected event. Used for enhanced billing tracking |
| event_data.event_live_start_time | Formatted timestamp of the start time of the Live event | json:string MM/DD/YYYY hh:mm:ss |
| event_data.event_title | Title of selected event | json:string |
| event_data-event_creator | Username of admin who created selected event | json:string |
| event_data.event_pre_live_scheduled_time | Formatted timestamp of the scheduled time for live event | json:string MM/DD/YYYY hh:mm:ss |
| event_data.evnet_analytics | Object containing overview statistics for the presentation | json:object |
| event_data.even_alaytics.unique_od_viewers | json:string | |
| event_data.even_alaytics.total_registrants | json:string | |
| event_data.even_alaytics.live_conversion_rate | json:string | |
| event_data.even_alaytics.od_sessions | json:string | |
| event_data.even_alaytics.simlive_sessions | json:string | |
| event_data.even_alaytics.unique_simlive_sessions | json:string | |
| event_data.even_alaytics.total_conversion_rate | json:string | |
| event_data.even_alaytics.live_sessions | json:string | |
| event_data.even_alaytics.unique_live_viewers | json:string | |
| event_data.even_alaytics.live_registrants | json:string | |
| event_data.even_alaytics.total_sessions | json:string | |
| event_data.even_alaytics.no_shows | json:string | |
| filters | Object containing the values of the filters applied to report | json:object |
| filters.dr_regs | Restricts results by including only registrants who registered within the selected date range | json:boolean |
| filters.dr_sessions | Restricts results by including only registrants who have viewing duration of any type within the selected date range | json:boolean |
| filters.incl_domain | Restricts results by including any registrants with emails on the specified domain. If undefined, it will default to off. | json:array[s1,s2,s…] |
| filters.excl_domain | Restricts results by excluding any registrants with emails on the specified domain. If undefined, it will default to off. | json:array[s1,s2,s…] |
| filters.od_viewers | Restricts results by including only registrants with one or more On-Demand or Archive viewing sessions | json:boolean |
| filters.live viewers | Restricts results by including only registrants with one or more live viewing sessions | json:boolean |
| filters.simliveviewers | Restricts results by including only registrants with one or more Sim-Live viewing sessions | json:boolean |
| filters.sti_filters | Restricts results by including only registrants who accessed the event using a URL containing a Campaign Source Tracking Identifier | json:array[s1,s2,s…] |
| filters.users_qa | Restricts results by including only registrants who asked a question | json:boolean |
| filters.user_survey | Restricts results by including only registrants who responded to one or more surveys | json:boolean |
| filters.no_shows | Restricts results by including only registrants with no viewing sessions of any type | json:boolean |
| data_headers | Array containing ordered header information for data_rows | json:array |
| data_rows | Arrays of arrays containing the data. Internal array indexes correspond with data_header indexes. | json:array[arr1,arr2,arr…] |
| sessions | The data_rows index corresponding to the data_headers index of the value “sessions” will contain session data for that viewer | json:array[arr1,arr2,arr…] |
| sessions[0] | Type: type of viewer session. Live, Simlive, On-Demand, etc. | json:string |
| sessions[1] | Sessions Start Time: Formatted datetime of viewing session start time | json:string MM/dd/yyyy hh:mm:ss a |
| sessions[2] | Session End Time: Formatted datetime of viewing session end time | json:string MM/dd/yyyy hh:mm:ss a |
| sessions[3] | Session Duration: Long value for viewing durationZ | json:long |
| sessions[4] | Session Media Type: Type of media player used in a viewing session | json:string |
Return Codes for Failed Rquests
| Return Code | Description |
|---|---|
| 0 | General error |
| 1 | Success |
| 10 | You are not authorized to run a report on this event. Please check you have the correct Event ID. |
| 11 | The User ID or Session ID is invalid. |
| 50 | The reporting service is not available at this time. Please conact Support for assistance. |
| 51 | There was invalid data in the report. Please conact Support for assistance. |
| 60 | The reporting service is not available at this time. Please conact Support for assistance. |
| 61 | You have reached the maximum number of reports that can be run for an event. Please try again later. |
| 62 | You have reached the maximum number of reports that can be run within one hour. Please try again later. |
| 70 | Pleaes remove any insecure tages from the input paramters and try again. |
| 71 | Please use a valid version number ("2.0"). |
| 72 | There were missing or invalid input parameters in request. |
| 73 | Ambigous platform |
| 74 | Could not identify the Reporting Resource requested |
CSV Return on Successful Request
Report data can also be formatted using comma separated values (CSV) and follow RFC 4180 standards. The first row contains the header information and column names, with each following row containing the report data.
CSV Return on Failed Request
In the case that a CSV reporting request cannot be successfully completed, the first column in the header row will have a value of "error". The first row will contain the error header information, with following rows containing error data.
API Limits
The API has the following limitations on the amount of requests that can be made within certain time thresholds.
- Authentication is valid for two (2) hours. For additional time, a new session may be required.
- One (1) standard report request can be made at one time. Subsequent concurrent requests will be blocked.
- Up to 1,000 reporting requests can be made within one hour. Subsequent requests within the hour will be blocked.
- Expired presentation data will not run be included in standard reporting requests. A separate request must be made to get expired presentation data.
- One (1) expired report request can be made at one time. Subsequent concurrent requests will be blocked.
- One (1) report per expired presentation can be run within a 48 hour period.
- Up to 50 reporting requests can be made within one hour for expired events. Subsequent requests within the hour will be blocked.
Event ID List Request
To access a list of Webcast Event IDs, connect to the URL below via https GET or Post. Accounts will only see Event IDs their account has permission to view.
The bold values in this example need to be updated to include your User ID and Session ID in the corresponding fields. Refer to the example URL and table below for more details.
Sample Request
https://api.webcasts.com/api/reporting/eventlist?si=SESSION_ID&ui=USER_ID
| Parameter | Description |
|---|---|
| Session ID | |
| User ID |
XML Return on Event ID List Request
<event_info cost_center="" event_expiry="2019-07-24 15:39:40" id="2227117" is_expired="false" folder_id="4fdc91f0ec60425c502f02f965c72b3abcc5ca71" latest_registration="1554920268000" latest_session="1554920650000" sched_end="" sched_start="">test event</event_info>
Use Case
In most common scenarios, clients and vendors will take the information contained in the successful XML example to produce a master event analytics and/or registration report. The following example shows reports in CSV format.
Sample Event Analytics Report
Sample Master Registration Report
Password Reset
The password used to authenticate an API account can be reset within the API. To reset your account password, use any of URLs below. The bold values in this example need to be updated to include your Username, current Password and new Password you desire in the corresponding fields. Refer to the example URL and Parameters below for more details.
You will see a "Password change successful" message to indicate the account's password has been changed.
https://api.webcasts.com/api/passwordchange?username=Username¤ttpassword=Current_Password&newpassword=New_Password&ver=2.0
https://api.webcasts.com/api/passwordchange/xml?username=Username¤tpassword=Current_Password&newpassword=New_Password&ver=2.0
https://api.webcasts.com/api/passwordchange/json?username=Username¤tpassword=Current_Password&newpassword=New_Password&ver=2.0