COVERITLIVE API - EVENT/CREATE (V. 2.0)

The Request

This method allows users to create CoveritLive events on the fly. Events can be created simply by specifying just a title and start date / time, or additional parameters can be included for finer-grained control of the event particulars. This method returns the event code if the event is successfully created, allowing for further interactions through the API.

URL:
https://api.coveritlive.com/remote/2/event/create
Response Format:
JSON
HTTP Method(s):
POST
API Rate Limited:
true (no more than 500 events created in a 24 hour period)
In addition to the parameters listed in the Request Parameters section, the event/create method also includes the following parameters:

Parameter Description Required
title The title of the event to be created. May not be > than 90 characters in length. yes
is_ticker Indicates whether the event to be created is a ticker. Set this parameter to 'y' to denote that the event is a ticker. no
category

Defines the general category of the event. Correctly categorizing your event makes it easier for Readers to find and potentially increases your live event traffic. Possible values include:

value associated category
18Business
11Education
20Entertainment
22Health
24Lifestyle
26News
5Sports
28Technology
 yes
scheduled_startdate

The scheduled start date of the event, in the following format:

YYYY-MM-DD

If no timezone is provided, this date defaults to the timezone provided in the user account which is denoted by the token parameter. For upcoming events that have a Title Page, this date (along with the scheduled start time) will be displayed to viewers.

 yes
scheduled_starttime

The scheduled start time of the event, in 24 hour format:

HH:MM (24-hour format of an hour without leading zeros:minutes with leading zeros). MM must be one of 00, 15, 30, 45 (ie, only 15 minute start time increments are allowed).

For upcoming events that have a Title Page, this time (along with the scheduled start date) will be displayed to viewers.

 yes
timezone

The timezone that the event falls into, represented as a decimal number. The scheduled_startdate and scheduled_starttime parameters are assumed to be in this timezone. If not provided, it defaults to the timezone provided in the user account which is denoted by the token parameter. Possible values include:

value associated timezone
-12 (GMT -12:00) Eniwetok, Kwajalein
-11 (GMT -11:00) Midway Island, Samoa
-10 (GMT -10:00) Hawaii
-9 (GMT -9:00) Alaska
-8 (GMT -8:00) Pacific Time (US & Canada)
-7 (GMT -7:00) Mountain Time (US & Canada)
-6 (GMT -6:00) Central Time (US & Canada)
-5 (GMT -5:00) Eastern Time (US & Canada), Bogota, Lima
-4 (GMT -4:00) Atlantic Time (Canada), Caracas, La Paz
-3.5 (GMT -3:30) Newfoundland
-3 (GMT -3:00) Brazil, Buenos Aires, Georgetown
-2 (GMT -2:00) Mid-Atlantic
-1 (GMT -1:00 hour) Azores, Cape Verde Islands
0 (GMT) Western Europe Time, London, Lisbon, Casablanca
1 (GMT +1:00 hour) Brussels, Copenhagen, Madrid, Paris
2 (GMT +2:00) Kaliningrad, South Africa
3 (GMT +3:00) Baghdad, Riyadh, Moscow, St. Petersburg
3.5 (GMT +3:30) Tehran
4 (GMT +4:00) Abu Dhabi, Muscat, Baku, Tbilisi
4.5 (GMT +4:30) Kabul
5 (GMT +5:00) Ekaterinburg, Islamabad, Karachi, Tashkent
5.5 (GMT +5:30) Bombay, Calcutta, Madras, New Delhi
6 (GMT +6:00) Almaty, Dhaka, Colombo
7 (GMT +7:00) Bangkok, Hanoi, Jakarta
8 (GMT +8:00) Beijing, Perth, Singapore, Hong Kong
8.5 (GMT +8:30)
9 (GMT +9:00) Tokyo, Seoul, Osaka, Sapporo, Yakutsk
9.5 (GMT +9:30) Adelaide, Darwin
10 (GMT +10:00) Eastern Australia, Guam, Vladivostok
10.5 (GMT +10:30)
11 (GMT +11:00) Magadan, Solomon Islands, New Caledonia
12 (GMT +12:00) Auckland, Wellington, Fiji, Kamchatka
no
location

The web address of the event. This address will be included in any shared Facebook and Twitter links, on event email invites, reader reminders and in the Live Now Listings. It's important to provide the correct public location as this address is used to drive traffic back to your live event.

*Note - if you do not wish to share the event location, make it private by including the private request parameter and setting its value to 'y'

 yes*
private

Indicate whether an event is private. Facebook and Twitter sharing is disabled for private events. Private events do not appear in the Live Now Listings, and the email reminder is hidden for Upcoming private events. The location request parameter is not required for private events.

Possible values:

y - event is private

n - event is not private

 no
template_id Explicitly set the template that will be used for the viewer window for the event. The template id value can be retrieved using the template/list method. IF not specified, the template for the event is set to the default template for the user. no
tweet_text If the event to be created is not private, a tweet will be published to the CiLEvents Twitter account when the event is started. This tweet will contain the title and location of the event, as well as any additional text contained in the tweet_text parameter (space permitting). May not exceed 140 characters in length. no
enable_title_page

Indicate whether an event should have a title page. By default the Viewer Window includes a built in Title Page (also referred to as a "Veil"). The Title Page displays your event title, event status, and main image. It is particularly useful for displaying custom branding. Readers click the Title Page to view your live event. If disabled the Title Page will no longer appear for Live Events and Replays.

Possible values:

y - event has titlepage

n - event does not have titlepage

 no
enable_email_comments

Allow your live event Readers to submit comments and images via email. All submitted items can be previewed from the Console. Defaults to disabled if not specified.

Possible values:

y - email comments enabled

n - email comments disabled

 no
enable_rdr_attachments

Allow your live event Readers to attach images to their comments. All submitted images can be previewed from your Console, and published at your discretion. This option is not available when Reader Comments have been turned off (check your template settings). Reader comments and attachments can also be managed from your Writer's Console. Defaults to enabled if not specified.

Possible values:

y - reader attachments enabled

n - reader attachments disabled

 no
show_live_listings

If this parameter is set to 'y', your Live Event can be found and watched by any Reader browsing the CoveritLive "Live Now" Listings. Private events do not appear in Live Listings. If private request parameter is included and set to 'y', the show_live_listings parameter is ignored.

Possible values:

y - event will appear in live listings

n - event will not appear in live listings

 no
allow_rss

If this parameter is set to 'y', CoveritLive will provide three RSS feeds for your readers at the bottom of your Viewer Window:

  • Live event: The RSS feed will display every published entry from a specific event
  • Writer: The RSS feed will display a listing and links to every upcoming, live and completed event from that CiL username
  • Groups: For Group members; the RSS feed will display a listing and links for all upcoming, live and completed events from all writers within the Group

Possible values:

y - rss is enabled for the event

n - rss is disabled for the event

 no
show_writer_avatars

This option turns avatars on for all event Writers / Contributors. Avatars appear next to the posted comment.

Possible values:

y - writer avatars enabled

n - writer avatars disabled

 no
show_reader_avatars

When Reader Login Options are enabled, this option allows you to control Reader avatar display. When enabled, the Reader's associated avatar will appear beside their published comment.

Possible values:

y - reader avatars enabled

n - reader avatars disabled

 no

The Response

The event code of a successfully created event is returned in the data field of a general response. This field will consist of an event_code field, which contains the event code.


Example response to a successful event/create request:


{
	"result" : "success",
	"message" : "true",
	"type" : "event",
	"action" : "create",
	"version" : 2,
	"data":{
		"event_code" : "ab3499981d"
	}
}

event/create Error Responses

A variety of error responses (in addition to the common error responses) to event/create requests, and instructions on how to rectify them:

result response message response solution
event_threshold_reached You have reached the maximum number of events you are permitted to create in a day: 500 You must wait until the 24 hour period expires before you can create further events.
missing_title_param Required parameter empty: title Ensure the title request parameter is present when making a event/create request.
invalid_title_param Exceeded maximum title length of: 90 Ensure the title request parameter is does not exceed 90 characters in length.
invalid_is_ticker_param The is_ticker parameter is invalid. Valid values include: y. When creating a ticker, ensure the is_ticker request parameter is set to 'y'. Do not include the parameter if you are creating a regular event.
missing_location_param Required parameter empty: location. Location may only be omitted if event is private. Ensure the location request parameter is present when making a event/create request. The only exception is if the private parameter is also included in the request with a value of 'y'
invalid_private_param The private parameter is invalid. Valid values include: y, n. If the private parameter is included in the request, its value must be one of 'y', 'n'
missing_category_param Required parameter empty: category Ensure the category request parameter is present when making a event/create request.
invalid_category_param The category parameter is invalid. Valid values include: 18, 11, 20, 22, 24, 26, 5, 28. Ensure the category request parameter contains a valid value.
missing_scheduled_startdate_param Required parameter empty: scheduled_startdate. Ensure the scheduled_startdate request parameter is present when making a event/create request.
invalid_scheduled_startdate_param Various Ensure the scheduled_startdate request parameter is in the correct format (YYYY-MM-DD) and not prior to the current date.
missing_scheduled_starttime_param Required parameter empty: scheduled_starttime. Ensure the scheduled_starttime request parameter is present when making a event/create request.
invalid_scheduled_starttime_param Various Ensure the scheduled_starttime request parameter is in the following format: HH:MM, where MM is one of 00, 15, 30, 45.
invalid_timezone_param The timezone parameter is invalid. Valid values: -12, -11, -10, -9, -8, -7, -6, -5, -4, -3.5, -3, -2, -1, 0, 1, 2, 3, 3.5, 4, 4.5, 5, 5.5, 6, 7, 8, 8.5, 9, 9.5, 10, 10.5, 11, 12. Ensure the timezone request parameter is one of the values listed in the error message.
invalid_tweet_text_param Exceeded maximum tweet_text length of: 140. Ensure the tweet_text request parameter is does not exceed 140 characters in length.
invalid_enable_title_page_param The enable_title_page parameter is invalid. Valid values include: y, n. If the enable_title_page parameter is included in the request, its value must be one of 'y', 'n'
invalid_enable_email_comments_param The enable_email_comments parameter is invalid. Valid values include: y, n. If the enable_email_comments parameter is included in the request, its value must be one of 'y', 'n'
invalid_enable_rdr_attachments_param The enable_rdr_attachments parameter is invalid. Valid values include: y, n. If the enable_rdr_attachments parameter is included in the request, its value must be one of 'y', 'n'
invalid_show_live_listings_param The show_live_listings parameter is invalid. Valid values include: y, n. If the show_live_listings parameter is included in the request, its value must be one of 'y', 'n'
invalid_allow_rss_param The allow_rss parameter is invalid. Valid values include: y, n. If the allow_rss parameter is included in the request, its value must be one of 'y', 'n'
invalid_template_id_param The template_id parameter is invalid. Ensure that the template_id parameter is correct, and that the user has access to the specified template
invalid_show_writer_avatars_param The show_writer_avatars parameter is invalid. Valid values include: y, n. If the show_writer_avatars parameter is included in the request, its value must be one of 'y', 'n'
invalid_show_reader_avatars_param The show_reader_avatars parameter is invalid. Valid values include: y, n. If the show_reader_avatars parameter is included in the request, its value must be one of 'y', 'n'