Skip Main Navigation
Eventbrite
OverviewDocumentationAPI ReferenceSign In
Page Content

Creating an Event Description

Note: The event description used to live on event.description, but event.description will be deprecated soon.

The event description is comprised of a summary + the content in Structured Content.

Please use event.summary to create a shortened summary of your event. Use the concept of 'structured content' and 'modules' to create rich multi media event descriptions. Please see Event Description API Reference and Structured Content API Reference.

Structured content works as an insert only system, so any time you want to update module(s), you will need to resubmit all of the content you had previously submitted plus any changes. Structured content also works as a versioned system, so you will need to increment with a new version every time.

Important note: At Eventbrite, we consider the event description to be both the event summary (aka event.summary) + an event's structured content. If you just make an api call only to Retrieve Structured Content, that will not be the event description, as it will be missing the event summary. If you make an api call to Retrieve Event Description as HTML, that will give you the entire event description (summary + content in Structured Content).

This entire tutorial deals with the api side that powers the Event Details portion of our Event Create product, as well as the individual Event Listing. For more indepth explanation about the api endpoints themselves, please see Event Description API Reference and Structured Content API Reference

Modules in Structured Content

The three basic modules available are:

Note: on GET requests, each module comes with some extra properties that for the most part will remain null - properties such as layout, timed_display, and semantic_purpose. You can safely ignore those in the context of the event description.

For more in-depth information regarding modules and their properties, please refer to the structured content api documentation.

Also note that below are just examples of the data structures for the modules themselves, not how to actually the whole api call. For that, please jump to section Creating and Updating Structured Content

Text Module

The text module accepts both plain text and html as strings. If you are submitting HTML, the only accepted tags are:

  • caption: <aside>
  • quote: <blockquote>
  • lists: <ul>, <ol>, <li>
  • headers: <h1>, <h2>, <h3>
  • paragraph: <p>
  • bold & emphasis: <b>, <em>
  • link: <a>

POST format for text module

{
    "data": {
        "body": {
            "alignment": "left",
             "text": "<h2>Hello World</h2><ul><li>Hello Northern Hemisphere</li><li>Hello Southern Hempisphere</li></ul><p></p><p>It&#x27;s a <em>beautiful</em> day today!</p>"
        },
        "type": "text",
    },
    "type": "text"
}

GET response format for text module

{
    "data": {
        "body": {
            "alignment": "left",
             "text": "<h2>Hello World</h2><ul><li>Hello Northern Hemisphere</li><li>Hello Southern Hempisphere</li></ul><p></p><p>It&#x27;s a <em>beautiful</em> day today!</p>"
        },
    },
    "type": "text",
    "id": "12345"
}

Image Module

In order to use the image module, you will first need to upload an image to the Eventbrite media service. Then you will submit the image_id as part of the image module data.

To upload an image to the Eventbrite media service, please follow the steps located at Image Upload. In the Retrieving the Upload Token section, you will need to replace type=image-event-logo with type=image-structured-content. You will need to do the same with Uploading the Image File to the Specified URL.

POST format with image_id

{
    "data": {
        "image": {
            "type": "image",
            "image_id": "8561955"
        }
    },
    "type": "image"
}

GET response format with image_id

{
    "data": {
        "image": {
            "aspect_ratio": "1.67"
            "corner_style": "rectangular"
            "crop_mask": {}
            "edge_color": "#77634e"
            "edge_color_set": true
            "id": "85619535"
            "image_id": "85619535"
            "original": {
                "url": "https://img.evbuc.com/etc",
                "width": 604,
                "height": 453
            },
            "url": "https://img.evbuc.com/etc"
        },
    "id": "29657266",
    "type": "image",
}

Video Module

Note: currently we only support YouTube and Vimeo videos.

To create a video module, send in a valid YouTube or Vimeo link. You will receive back an embedded url and thumbnail url.

POST format for video

{
    "data": {
        "video": {
            "url": "https://www.youtube.com/watch?v=-pAz5X7ZW4",
            "display_size": "large"
        }
    },
    "type": "video"
}

GET response format for video

{
    "data": {
        "video": {
            "display_size": "large"
            "embed_url": "https://youtube.com/embed/-pAz5X7ZW4/"
            "thumbnail_url": "https://i.ytimg.com/vi/-pAz5X7ZW4/sddefault.jpg"
            "url": "https://www.youtube.com/watch?v=-pAz5XxZW4"
        },
        "id": "29665964"
    }
}

Creating and Updating Structured Content

Related api reference: Set Structured Content by Event Id and Version

Structured content works as an insert only system, so any time you want to update module(s), you will need to resubmit all of the content you had previously submitted plus any changes. Structured content also works as a versioned system, so you will need to increment with a new version every time. The first time you submit, you will want to submit with version_number=1 and every time after, increment the current page_version_number every time after.

Note: in order to make the api work correctly, you MUST send in publish=true every time. If you are not seeing your most current updates, it is probably because you forgot to send in publish=true.

2nd Note: It is adviseable you set purpose=listing to ensure that the structured content is set for the listing/event description (as there are other purposes that structured content is used for). No worries if you don't, as the default in the back end is listing.

curl -X POST   https://www.eventbriteapi.com/v3/events/{event_id}/structured_content/{version_number}   -H 'Authorization: Bearer PERSONAL_OAUTH_TOKEN'   -H "Accept: application/json"
  -d '{
       "modules":[
          {
             "type":"text",
             "data":{
                "body":{
                   "type":"text",
                   "text":"<h2>Hello World</h2><ul><li>Hello Northern Hemisphere</li><li>Hello Southern Hempisphere</li></ul><p></p><p>It's a <em>beautiful</em> day today!</p><aside><em></em></aside>",
                   "alignment":"left"
                }
             }
          },
          {
             "type":"image",
             "data":{
                "image":{
                   "type":"image",
                   "image_id":"8561955"
                }
             }
          },
          {
             "type":"video",
             "data":{
                "video":{
                   "url":"https://www.youtube.com/watch?v=-pAz5X7ZW4",
                   "display_size":"large"
                }
             }
          }
       ],
       "publish":true,
       "purpose":"listing"
    }'

Response

See Retrieve Structured Content for an example of the api response.

Set Event Summary

This is to set the event summary, a shortened explanation of the event, with some rich HTML. This is NOT considered the event description.

curl -X POST   https://www.eventbriteapi.com/v3/events/{event_id}   -H 'Authorization: Bearer PERSONAL_OAUTH_TOKEN'   -H "Accept: application/json"
  -d '{
       "event":{
          "descrption":{
             "html": "<b>I'm the event summary</b>"
          },
      }

Response

{
    "name": {
        "text": "Hello World Day",
        "html": "Hello World Day"
    },
    "description": {
        "text": "I'm the event summary",
        "html": "<B>I'm the event summary</B>"
    },
    "id": "1234556778",
    "url": "https://www.eventbrite.com/e/hello-world-tickets-1234556778",
    ...basic event info
}

Getting Event Description

Retrieve Structured Content

Related api reference: Retrieve Latest Published Version of Structured Content

Retrieve structured content with published full list of modules (aka the 'raw' module list).

Note: It is adviseable you set purpose=listing to ensure that the structured content is set for the listing/event description (as there are other purposes that structured content is used for). No worries if you don't, as the default in the back end is listing.

curl -X GET   https://www.eventbriteapi.com/v3/events/{event_id}/structured_content/?purpose=listing   -H 'Authorization: Bearer PERSONAL_OAUTH_TOKEN'

Response

{
   "resource_uris":{
      "self":"https://www.eventbriteapi.com/v3/events/83068416871/structured_content/15/",
      "add_module":"https://www.eventbriteapi.com/v3/events/83068416871/structured_content/15/module/",
      "publish":"https://www.eventbriteapi.com/v3/events/83068416871/structured_content/15/publish/",
      "preview_module":"https://www.eventbriteapi.com/v3/events/structured_content/module/preview/"
   },
   "page_version_number":"1",
   "purpose":"listing",
   "modules":[
      {
         "resource_uris":{
            "self":"module/29665960/"
         },
         "id":"29665960",
         "type":"text",
         "layout":null,
         "data":{
            "body":{
               "text":"<h2>Hello World</h2><ul><li>Hello Northern Hemisphere</li><li>Hello Southern Hempisphere</li></ul><p></p><p>It's a <em>beautiful</em> day today!</p><aside><em></em></aside>",
               "alignment":"left"
            }
         },
         "semantic_purpose":null,
         "timed_display":null
      },
      {
         "resource_uris":{
            "self":"module/29665962/"
         },
         "id":"29665962",
         "type":"image",
         "layout":null,
         "data":{
            "image":{
               "edge_color_set":true,
               "edge_color":"#77634e",
               "corner_style":"rectangular",
               "url":"https://img.evbuc.com/etc",
               "id":"85619535",
               "image_id":"85619535",
               "crop_mask":{

               },
               "aspect_ratio":"1.442386831275720164609053498",
               "original":{
                  "url":"https://img.evbuc.com/etc",
                  "width":2804,
                  "height":1944
               }
            }
         },
         "semantic_purpose":null,
         "timed_display":null
      },
      {
         "resource_uris":{
            "self":"module/29665964/"
         },
         "id":"29665964",
         "type":"video",
         "layout":null,
         "data":{
            "video":{
               "url":"https://www.youtube.com/watch?v=-pAz5X7ZW4",
               "display_size":"large",
               "thumbnail_url":"https://i.ytimg.com/vi/-pAz5X7ZW4/sddefault.jpg",
               "embed_url":"https://youtube.com/embed/-pAz5X7ZW4/"
            }
         },
         "semantic_purpose":null,
         "timed_display":null
      }
   ],
   "pagination":{
      "object_count":3,
      "page_number":1,
      "page_size":50,
      "page_count":1
   }
}

Retrieve HTML Description

Get the event summary + structured content as HTML.

curl -X GET   https://www.eventbriteapi.com/v3/events/{event_id}/description/   -H 'Authorization: Bearer PERSONAL_OAUTH_TOKEN'

Response

{
    "description": "<div>asdg</div>
<div style="margin-top: 20px"><div><div style="margin:20px 10px;font-size:15px;line-height:22px;font-weight:400;text-align:left;"><h2>Hello World</h2><ul><li>Hello Northern Hemisphere</li><li>Hello Southern Hempisphere</li></ul><p></p><p>It's a <em>beautiful</em> day today!</p><aside><em></em></aside></div><div style="margin:20px 0;line-height:22px;"><img src="https://img.evbuc.com/https%3A%2F%2Fcdn.evbuc.com%2Fimages%2F856195%2F2486666781%2F1%2Foriginal.20191227-202857?h=2000&amp;w=720&amp;auto=format%2Ccompress&amp;q=75&amp;sharp=10&amp;s=e3242109fb3d7699e4a0c9bb0ca6"/></div><div style="margin:20px 0;line-height:22px;"><iframe src="https://youtube.com/embed/-pAz5Xx7W4/" frameborder="0" allowfullscreen=""></iframe></div></div></div>
"
}

Retrieve Event Summary

The event summary is part of the basic event info, under event.description.

curl -X GET   https://www.eventbriteapi.com/v3/events/{event_id}   -H 'Authorization: Bearer PERSONAL_OAUTH_TOKEN'

Response

{
    "name": {
        "text": "Hello World Day",
        "html": "Hello World Day"
    },
    "description": {
        "text": "I'm the event summary",
        "html": "<B>I'm the event summary</B>"
    },
    "id": "1234556778",
    "url": "https://www.eventbrite.com/e/hello-world-tickets-1234556778",
    ...basic event info
}