webservices

Managing Events

by Administrator on ‎03-25-2011 10:06 AM

Obtaining a List of Events

 

You can obtain a list of events that you have created by calling the following URI using the GET method:

 

 

https://api.constantcontact.com/ws/customers/{username}/events

 

For detailed descriptions and specification of the returned XML, please refer to the Events Collection and Resource page.

 

The returned XML contains a list of events that are currently in your account. For example, here is a sample of the XML returned for a customer who has two events:

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<atom:feed xmlns:atom="http://www.w3.org/2005/Atom">
<atom:title>Events</atom:title>
<atom:updated>2010-08-17T16:28:10.385-04:00</atom:updated>
<atom:id>tag:api.constantcontact.com,2010:/ws/customers/joesflowers/events</atom:id>
<atom:entry>
<atom:title>Spring Orientation</atom:title>
<atom:link rel="edit" href="/ws/customers/joesflowers/events/a07e1hoasmu0e644426"/>
<atom:updated>2010-08-10T15:30:16.050-04:00</atom:updated>
<atom:id>tag:api.constantcontact.com,2010:/ws/customers/joesflowers/events/a07e1hoasmu0e644426</atom:id>
<atom:content>
<Event>
<Name>Spring Oriengation</Name>
<Description></Description>
<Title>Joes Flowers Sprint Orientation</Title>
<Registered>1</Registered>
<CreatedDate>2010-08-10T15:30:16.050-04:00</CreatedDate>
<Status>ACTIVE</Status>
<EventType></EventType>
<EventLocation>
<Location>Boston Marriott</Location>
<Address1></Address1>
<Address2></Address2>
<Address3></Address3>
<City>Chelsea</City>
<State>Massachusetts</State>
<Country></Country>
<PostalCode></PostalCode>
</EventLocation>
<RegistrationURL></RegistrationURL>
<StartDate>2010-08-11T18:00:00-04:00</StartDate>
<EndDate>2010-10-11T18:00:00-04:00</EndDate>
<PublishDate>2010-08-10T15:32:38.653-04:00</PublishDate>
<AttendedCount>0</AttendedCount>
<CancelledCount>0</CancelledCount>
</Event>
</atom:content>
</atom:entry>
<atom:entry>
<atom:title>Summer Orientation</atom:title>
<atom:link rel="edit" href="/ws/customers/joesflowers/events/a07e1hoasmzc36cecc8"/>
<atom:updated>2010-08-10T15:34:17.513-04:00</atom:updated>
<atom:id>tag:api.constantcontact.com,2010:/ws/customers/joesflowers/events/a07e1hoasmzc36cecc8</atom:id>
<atom:content>
<Event>
<Name>Summer Orientation</Name>
<Description></Description>
<Title>Summer Orientation</Title>
<Registered>5</Registered>
<CreatedDate>2010-08-10T15:34:17.513-04:00</CreatedDate>
<Status>ACTIVE</Status>
<EventType></EventType>
<EventLocation>
<Location>Boca Raton Beach</Location>
<Address1></Address1>
<Address2></Address2>
<Address3></Address3>
<City>Burlington</City>
<State>Massachusetts</State>
<Country></Country>
<PostalCode></PostalCode>
</EventLocation>
<RegistrationURL></RegistrationURL>
<StartDate>2010-08-11T18:00:00-04:00</StartDate>
<EndDate>2010-10-11T18:00:00-04:00</EndDate>
<PublishDate>2010-08-10T15:35:30.647-04:00</PublishDate>
<AttendedCount>0</AttendedCount>
<CancelledCount>0</CancelledCount>
</Event>
</atom:content>
</atom:entry>
</atom:feed>

The list of events contains a set of summary data that is useful to see at a glance, but in order to see more details, you need to get the details of individual events.  The summary includes<RegistrationURL>, which is the URL for the homepage of the event, which has the button to register.  If the homepage has not been created for the event, the URL takes the user directly to the registration form.

 

The total number of registrants, which is available through <Registered> element, includes the number of guests just like our UI page.  This number includes the number of guests.

 

In order to query more details for a given event, you need to use the relative path specified in "href" attribute of <atom:link> element.

 

Obtaining Details of an Event

 

You can obtain details of an event by calling the following URI using the GET method:

 

 

https://api.constantcontact.com/ws/customers/{username}/events/{event-id}

 

For detailed descriptions and specification of the returned XML, please refer to the Events Collection and Resource page.

 

The returned XML would look like the following:

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom">
<atom:title>Summer Orientation</atom:title>
<atom:link rel="edit" href="/ws/customers/joesflowers/events/a07e1hoasn2a917e97c"/>
<atom:updated>2010-08-10T15:37:49.686-04:00</atom:updated>
<atom:id>tag:api.constantcontact.com,2010:/ws/customers/joesflowers/events/a07e1hoasn2a917e97c</atom:id>
<atom:content>
<Event>
<Name>Summer Orientation</Name>
<Description></Description>
<Title>Summer Orientation</Title>
<Registered>20</Registered>
<CreatedDate>2010-08-10T15:37:49.686-04:00</CreatedDate>
<Status>ACTIVE</Status>
<EventType></EventType>
<EventLocation>
<Location>Hotel California</Location>
<Address1>1 Evm Place</Address1>
<Address2></Address2>
<Address3></Address3>
<City>Burlington</City>
<State>Massachusetts</State>
<Country>United States</Country>
<PostalCode>01950</PostalCode>
</EventLocation>
<RegistrationURL></RegistrationURL>
<StartDate>2010-08-11T18:00:00-04:00</StartDate>
<EndDate>2010-10-11T18:00:00-04:00</EndDate>
<PublishDate>2010-08-10T15:38:41.646-04:00</PublishDate>
<AttendedCount>0</AttendedCount>
<CancelledCount>0</CancelledCount>
<EventFeeRequired>TRUE</EventFeeRequired>
<CurrencyType>JPY</CurrencyType>
<PaymentOptions>
<PaymentOption>
<Type>PAYPAL</Type>
<PayPalAccountEmail>bla@bla.com</PayPalAccountEmail>
</PaymentOption>
<PaymentOption>
<Type>CHECK</Type>
<PaymentAddress>
<Address1>123 wsw st</Address1>
<Address2></Address2>
<Address3></Address3>
<City>Ashland</City>
<State>Massachusetts</State>
<Country>United States</Country>
<PostalCode>32423</PostalCode>
</PaymentAddress>
</PaymentOption>
<PaymentOption>
<Type>DOOR</Type>
</PaymentOption>
</PaymentOptions>
<RegistrationTypes>
<RegistrationType>
<Name>Attendee</Name>
<RegistrationLimitCount>25</RegistrationLimitCount>
<RegistrationClosedManually>FALSE</RegistrationClosedManually>
<GuestLimit>5</GuestLimit>
<Ticketing>TRUE</Ticketing>
<EventFees>
<EventFee>
<Label>Main Hall Entry Fee</Label>
<Fee>1.0</Fee>
<EarlyFee>0.0</EarlyFee>
<LateFee>0.0</LateFee>
<FeeScope>BOTH</FeeScope>
</EventFee>
<EventFee>
<Label>Additional Sessions</Label>
<Fee>2.0</Fee>
<EarlyFee>0.0</EarlyFee>
<LateFee>0.0</LateFee>
<FeeScope>REGISTRANTS</FeeScope>
</EventFee>
<EventFee>
<Label>Main Hall for Guests</Label>
<Fee>3.0</Fee>
<EarlyFee>0.0</EarlyFee>
<LateFee>0.0</LateFee>
<FeeScope>GUESTS</FeeScope>
</EventFee>
</EventFees>
</RegistrationType>
</RegistrationTypes>
</Event>
</atom:content>
</atom:entry>

The detail data for each event is very complex and contains a lot of information.  First, there is general information about the event, such as its name, description, event location as well as some of the dates associated with the event.

 

The detail also includes information about payment options as well as registration limits and fees.  The <PaymentOptions> element includes <PaymentOption> element for each of the payment types that the event organizer accepts.  <Type> signifies the payment type and it would be either PAYPAL, CHECK or DOOR.  Depending on the type of the payment, the payment option data will be different.  For PAYPAL, you will see <PayPalAccountEmail> element to indicate the PayPal email address to which the payment should be sent.  For CHECK, you will see <PaymentAddress> element that shows the address to which the payment check should be sent.  Finally, for DOOR, there is no additional data.

 

Finally, the event detail also includes data about different types of registrants and fees.  All this data is available through <RegistrationTypes> element.  We currently only support only one <RegistrationType>, whose <Name> is "Attendee".  The <RegistrationType> data includes the registration limit, whether registration will be manually closed or not, the limit on the number of guests each registrant can bring and whether ticketing option was chosen.

 

In addition to the metadata around registration, the detail also includes different fees that are defined by the event organizer.  The <EventFees> element contains <EventFee> element for each fee types that are defined by the user.  Each <EventFee> contains details for the fee label, the fee amounts, for regular, early and late fees, and <FeeScope> to signify whether a fee is applicable only to registrants, guests or both.  The fee amounts are entered in the number format as entered by the user in the UI.  <FeeScope> will have the value of BOTH if the fee applies to both registrants or guests.  "REGISTRANTS" indicates the fee is only applicable to the event registrants, "GUESTS" to the event guests and "BOTH" for both types of invitees.

 

 

Creating an Event

 

You can create an event via the REST API by using a POST request to the user's events collection. The URI for this collection is of the form:

 

https://api.constantcontact.com/ws/customers/{username}/events

 

Here is a sample of the XML that should be in the payload for this POST request:

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom">
    <atom:content>
        <Event>
            <Name>2011 Run For Dimes 5K</Name>
            <Title>2011 Run For Dimes 5K</Title>
            <EventType>OUTDOORS_RECREATION</EventType>
            <StartDate>2011-08-11T09:00:00-04:00</StartDate>
            <EndDate>2011-08-11T18:00:00-04:00</EndDate>
	    <TimeZone>
		<ID>US/Eastern</ID>
	    </TimeZone>
            <EventContact>
		<Name>John Smith</Name>
	    </EventContact>
	    <EventLocation>
                <Location>Myer Arena</Location>
            </EventLocation>
        </Event>
    </atom:content>
</atom:entry>

 

If successful, the POST response payload will contain XML similar to the following:

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom">
    <atom:title>2011 Run For Dimes 5K</atom:title>
    <atom:link rel="edit" href="/ws/customers/rajevp01/events/a07e1ht80kw4cf3bb41"/>
    <atom:updated>2011-05-18T17:21:35.648-04:00</atom:updated>
    <atom:id>tag:webservices.rnayakvm4.roving.com,2010:/ws/customers/rajevp01/events/a07e1ht80kw4cf3bb41</atom:id>
    <atom:content>
        <Event>
            <Name>2011 Run For Dimes 5K</Name>
            <Description></Description>
            <Title>2011 Run For Dimes 5K</Title>
            <Registered>0</Registered>
            <CreatedDate>2011-05-18T17:21:32.469-04:00</CreatedDate>
            <Status>DRAFT</Status>
            <EventType>OUTDOORS_RECREATION</EventType>
            <EventLocation>
                <Location>Myer Arena</Location>
                <Address1></Address1>
                <Address2></Address2>
                <Address3></Address3>
                <City></City>
                <State></State>
                <Country></Country>
                <PostalCode></PostalCode>
            </EventLocation>
            <RegistrationURL>https://events.r20.d1.constantcontact.com/register/event?oeidk=a07e1ht80kw4cf3bb41</RegistrationURL>
            <StartDate>2011-08-11T09:00:00-04:00</StartDate>
            <EndDate>2011-08-11T18:00:00-04:00</EndDate>
            <AttendedCount>0</AttendedCount>
            <CancelledCount>0</CancelledCount>
            <EventFeeRequired>FALSE</EventFeeRequired>
            <CurrencyType>USD</CurrencyType>
            <PaymentOptions/>
            <RegistrationTypes>
                <RegistrationType>
                    <Name>Attendee</Name>
                    <RegistrationLimitCount>0</RegistrationLimitCount>
                    <RegistrationClosedManually>FALSE</RegistrationClosedManually>
                    <GuestLimit>0</GuestLimit>
                    <Ticketing>FALSE</Ticketing>
                    <EventFees/>
                </RegistrationType>
            </RegistrationTypes>
        </Event>
    </atom:content>
</atom:entry>

 

 

The POST method can return a number of error codes, which are listed in the table below:

 

Errors
ConditionHTTP Status
Site Owner Does not have events 403
Non unique event name 409
Business logic validation errors 409