Education Harvester API

Overview

An API key must be used to consume this web API. An API key is unique per event, per third-party vendor and must be contracted by the client. Read the EventTech REST API Overview article for information about client expectations when contracting API access for a third-party vendor. 

Download the technical documentation attached at the bottom of this page.

Rate Limiting

To ensure the health and accessibility of our APIs, Cadmium monitors traffic and reserves the right to impose a rate limit or revoke access to any misbehaving application with excessive API usage. A rate limit is a specified number of API requests an application or user can make within a defined time frame.

• When using certain methods, such as getPresentationsWithPresenters, that return a large amount of data, it’s crucial to use pagination to prevent timeouts and reduce data transfer size; this is noted in the API documentation
• A rate limit of one call per minute is enforced for the getPresentationsWithPresenters method
• For all other methods, a rate limit of one call per second is enforced
• It’s mandatory to include an expiration or sunset date in your code, usually set as the event’s end date, to ensure that API calls aren’t made unnecessarily beyond that point

Frequently Asked Questions

• This API is mostly used to PULL data FROM Education Harvester. For a POST request, you can only push data once. 
• PLEASE IMPLEMENT PAGINATION if using the method getPresentationsWithPresenters - Make a request to getPresentationCount and use the returned count number to know the max number of presentations. Then use the 'Between' parameter to paginate the results.
• Dates and Times
  • The session and presentation dates and times that the client controls are returned by the API in 24-hour format and are NOT adjusted to GMT or UTC. They are returned exactly as they were entered into the system and represent the native time-zone of the event. 
  • DateAdded and DateUpdated fields are always in Eastern time.
  • When a presentation is added or edited the "PresentationDateAdded" or "PresentationDateEdited" fields are updated.
  • For presenters, this is also true BUT assigning a presenter to a presentation is NOT the same as adding a presenter to a presentation. "PresenterDateAdded" is the date the presenter was added to the master roster. You could have a presenter who was added to your roster back in 2018 and "PresenterDateAdded" would reflect that. When the client "assigns" a presenter to a presentation, the "PresenterDateAdded" and "PresenterDateEdited" fields are NOT updated because the update is to the presentation record. The only time "PresenterDateEdited" is updated is when an update is made to the presenter (profile) record. The alternative is to reference presentationDateEdited, look up if any presenters were added to the presenter array for that presentation, and create your own date added field for that presenter based on that information.
• Build Codes
  • Presentations with "SessionBuilderCode" = “H” are supposed to be hidden.
  • SessionBuilderCode3 is not currently available in the API
• Presenter Roles
  • Presenters can have two different types of roles:
    • "PresenterEventDetailsOverallRoles" is unique per presenter and is used for roles like Staff, Board Member, VIP, etc. This can be pulled using the method getPresenters.
    • "PresentationRosterRole" is unique per presentation+presenter combination and is used for roles like Moderator, Panelist, Speaker, etc.
      • Because a presenter can can be associated with one or more presentations and can have a different role for each presentation, "PresentationRosterRole" is only available for methods that associate a presenter with a presentation such as getPresentationswithPresenters. 
• Presenter Photos
  • Photo access is not automatically enabled for an API key. If a third-party is having difficulty accessing photos, the client should reach out to integrationservices@gocadmium.com to request the photo path be enabled.
  • There are two photo fields available in the API:
    • "PresenterPhotoFileName" will provide the original photo the end-user uploaded and can be any dimensions. The client has the ability to configure the following in the photo upload task.
      • Minimum/Maximum Acceptable Image Width (pixels)
      • Minimum/Maximum Acceptable Image Height (pixels)
      • Minimum/Maximum Acceptable Image File Size (kb)
      • Acceptable Image File Types (bmp, jpg, png)
      • Force Photo into Acceptable Image Width/Height - Yes/No
      • Offer Option to Opt Out of Upload - Yes/No
    • "PresenterPhotoWebFileName" will provide the cropped photo at 480x600 pixels.
      • This option is only available if the end-user completed the photo upload task and used the photo cropping tool. A client can see which presenters have cropped their photos under Education Harvester >>> Users >>> Pages >>> User Photos. The 'Final' column is the cropped version.