cancel
Showing results for 
Search instead for 
Did you mean: 

Managing Registrants and Guests

Administrator

Obtaining a List of Registrants for an Event

 

General Notes:

1. All URIs listed below should be prefixed with https://api.constantcontact.com/ws/customers/{user-name}, where {user-name} is the login name of the user whose data is being requested. 

2. For brevity, we show the relative URI below only.

 

You can obtain a list of registrants for each event by calling the following URI using the GET method:

 

/events/{event-id}/registrants

 

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

 

As an example, the returned XML for an event with a single registrant who had attended the event would look like:

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<atom:feed xmlns:atom="http://www.w3.org/2005/Atom">
<atom:title>Registrants</atom:title>
<atom:updated>2010-08-18T15:30:04.220-04:00</atom:updated>
<atom:id>tag:api.constantcontact.com,2010:/ws/customers/joesflowers/events/a07e1hoasn2a917e97c/registrants</atom:id>
<atom:link rel="current" href="/ws/customers/joesflowers/events/a07e1hoasn2a917e97c/registrants"/>
<atom:link rel="first" href="/ws/customers/joesflowers/events/a07e1hoasn2a917e97c/registrants"/>
<atom:link rel="next" href="/ws/customers/joesflowers/events/a07e1hoasn2a917e97c/registrants?pageNumber=1"/>
<atom:entry>
<atom:title>Test User 1</atom:title>
<atom:link rel="edit"
href="/ws/customers/joesflowers/events/a07e1hoasn2a917e97c/registrants/001xn3Y4OR91FzwO30b8qN3LWcOS1FX1xC4V67bXB7
q_g5pDr_tBvaQX89QvmkTNnVy"/>
<atom:updated>2010-08-10T15:51:11-04:00</atom:updated>
<atom:id>tag:api.constantcontact.com,2010:
/ws/customers/joesflowers/events/a07e1hoasn2a917e97c/registrants/001xn3Y4OR91FzwO30b8qN3LWcOS1FX1xC4V67bXB7q_g5pD
r_tBvaQX89QvmkTNnVy</atom:id>
<atom:content>
<Registrant>
<LastName>Test</LastName>
<FirstName>User</FirstName>
<EmailAddress>testuser@example.com</EmailAddress>
<RegistrationStatus>REGISTERED</RegistrationStatus>
<RegistrationDate>2010-08-10T15:51:11-04:00</RegistrationDate>
              <AttendanceStatus>
                <Status>ATTENDED</Status>
                <Type>GROUP</Type>
              </AttendanceStatus>
                <GuestCount>1</GuestCount>
                <PaymentStatus>PAID</PaymentStatus>
            </Registrant>
        </atom:content>
    </atom:entry>
</atom:feed>

 

 

The list contains a list of registrants only and does not include guests as a separate entry.  In other words, the list returned by this API represents the list of registrants as they appear on our UI page, which does not include guests.  The only available data for guests is the number of guests each registrant is bringing to the event, but we will soon be releasing an API for obtaining more detailed guest information as well.

 

At the summary level, the list of registrants contains only basic information about each registrant.  It includes first and last names, email address and the registrant's registration and payment statuses.  To get more detailed information, you need to query data for each registrant by following the "href" attribute of <atom:link> element.

 

Obtaining Details of a Registrant

 

You can obtain details of a registrant by calling the following URI using the GET method:

 

/events/{event-id}/registrants/{registrant-id}

For detailed descriptions and specification of the returned XML, please refer to the Registrants 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>Tanmand Evm1</atom:title>
    <atom:link rel="edit"
    href="/ws/customers/joesflowers/events/a07e1hoasn2a917e97c/registrants/001xn3Y4OR91FzwO30b8qN3LStB0UpRcvutof486SE6nOx
 kJfpX0y7-ugr6yQGBX-ke"/>
    <atom:updated>2010-08-10T15:53:11.804-04:00</atom:updated>
    <atom:id>tag:api.constantcontact.com,2010:
    /ws/customers/joesflowers/events/a07e1hoasn2a917e97c/registrants/001xn3Y4OR91FzwO30b8qN3LStB0UpRcvutof486SE6nOxkJfpX0
    y7-ugr6yQGBX-ke</atom:id>
    <atom:content>
        <Registrant>
            <LastName>Test</LastName>
            <FirstName>User</FirstName>
            <EmailAddress>testuser@example.com</EmailAddress>
            <PersonalInformation>
                <Label>Personal Information</Label>
                <Address1></Address1>
                <Address2></Address2>
                <Address3></Address3>
                <City></City>
                <State></State>
                <PostalCode></PostalCode>
                <Province></Province>
                <Country></Country>
                <Phone></Phone>
                <CellPhone></CellPhone>
            </PersonalInformation>
            <BusinessInformation>
                <Label>Business Information</Label>
                <Company></Company>
                <JobTitle></JobTitle>
                <Department></Department>
                <Address1></Address1>
                <Address2></Address2>
                <Address3></Address3>
                <City></City>
                <State></State>
                <PostalCode></PostalCode>
                <Province></Province>
                <Country></Country>
                <Phone></Phone>
                <Fax></Fax>
                <Website></Website>
                <Blog></Blog>
            </BusinessInformation>
            <CustomInformation1>
                <CustomField>
                    <Question>Would you like chicken or beef?</Question>
                    <Answers>
                        <Answer>Beef</Answer>
                    </Answers>
                </CustomField>
                <CustomField>
                    <Question>When are you arriving?</Question>
                    <Answers>
                        <Answer>2010-08-20T04:00:00+00:00</Answer>
                    </Answers>
                </CustomField>
            </CustomInformation1>
            <CustomInformation2/>
            <RegistrationStatus>REGISTERED</RegistrationStatus>
            <RegistrationDate>2010-08-10T15:53:11.804-04:00</RegistrationDate>
            <AttendanceStatus>
              <Status>ATTENDED</Status>
              <Type>GROUP</Type>
            </AttendanceStatus>
            <GuestCount>4</GuestCount>
            <PaymentStatus>PAID</PaymentStatus>
            <OrderAmount>10.0</OrderAmount>
            <CurrencyType>JPY</CurrencyType>
            <PaymentType>DOOR</PaymentType>
            <Costs>
                <Cost>
                    <Count>2</Count>
                    <FeeType>Event fee</FeeType>
                    <Rate>1.0</Rate>
                    <Total>2.0</Total>
                </Cost>
                <Cost>
                    <Count>1</Count>
                    <FeeType>Bus fee</FeeType>
                    <Rate>2.0</Rate>
                    <Total>2.0</Total>
                </Cost>
                <Cost>
                    <Count>2</Count>
                    <FeeType>Hotel fee</FeeType>
                    <Rate>3.0</Rate>
                    <Total>6.0</Total>
                </Cost>
            </Costs>
        </Registrant>
    </atom:content>
</atom:entry>

 

The registrant detail includes all of the personal and business information of the registrant, the answers to the custom questions and payment information.  The answers to the custom questions can be found under <CustomInformation1> and <CustomInformation2> elements, which correspond to the same in the UI.  Each set of question and its answers is included in <CustomField> element.  Because we allow for multiple-answer questions, the answers are included in <Answers> element, where each answer is included in <Answer> element.

 

The registrant detail also provides detailed payment information.  The payment status is included in <PaymentStatus> element and the total amount paid is in <OrderAmount> element.  The cost break down of the total order is included in <Costs> element, where each <Cost> element indicates each cost line item paid by the registrant.

 

Obtaining A List of Guests

 

Many events allow attendees to invite guests. Programmers can obtain a list of guests invited by a given attendee (formally, a 'registrant') by making a GET request on the 'guests' subresource for the registrant. The URI for the subresource is of the form:

 

/events/{event-id}/registrants/{registrant-id}/guests

 

This call if successful returns an XML document containing the guests for the registrant specified by {registrant-id}. Below is a sample of the XML returned by the GET request for the case where the registrant has guests:

 

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<atom:feed xmlns:atom="http://www.w3.org/2005/Atom">
    <atom:title>Guests</atom:title>
    <atom:updated>2011-05-05T15:50:25.785-04:00</atom:updated>
    <atom:id>tag:https://api.constantcontact.com/ws/customers/{username}/events/{event-id}/registrants/{registrant-id...</atom:id>
    <atom:entry>
        <atom:title>Doe Jane</atom:title>
        <atom:link rel="edit" href="/ws/customers/{username}/events/{event-id}/registrants/{registrant-id}/guests/{guest-id}"/>
        <atom:updated>27223-07-29T07:45:47.491-04:00</atom:updated>
        <atom:id>tag:https://api.constantcontact.com/ws/customers/{username}/events/{event-id}/registrants/{registrant-id...</atom:id>
        <atom:content>
            <Guest>
                <FirstName>Jane</FirstName>
                <LastName>Doe</LastName>
            </Guest>
        </atom:content>
    </atom:entry>
    <atom:entry>
        <atom:title>Doe John</atom:title>
        <atom:link rel="edit" href="//ws/customers/{username}/events/{event-id}/registrants/{registrant-id}/guests/{guest-id}"/>
        <atom:updated>27223-07-29T09:13:08.491-04:00</atom:updated>
        <atom:id>tag:https://api.constantcontact.com/ws/customers/{username}/events/{event-id}/registrants/{registrant-id...</atom:id>
        <atom:content>
            <Guest>
                <FirstName>John</FirstName>
                <LastName>Doe</LastName>
            </Guest>
        </atom:content>
    </atom:entry>
</atom:feed>

 

 

If the registrant does not have guests, the XML returned is similar to:

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<atom:feed xmlns:atom="http://www.w3.org/2005/Atom">
    <atom:title>Guests</atom:title>
    <atom:updated>2011-05-06T06:49:14.355-04:00</atom:updated>
    <atom:id>tag:https://api.constantcontact.com/ws/customers/{username}/events/{event-id}/registrants/{registrant-id...</atom:id>
</atom:feed>

 

 In both cases, certain error conditions can occur when making this call. The errors are listed in the table below:

 

Errors
ConditionHTTP Status
Site Owner Does not own Event or Registrant 403
Invalid Event Id 400
Invalid Registrant Id 400

 

 

Managing Registrant Status


Given a registrant, programmers can obtain the registrant status without having to obtain the entire registrant record. This can be done by performing a GET on the following URI:

 

/events/{event-id}/registrants/{registrant-id}/registrationstatus

 

If the registrant exists, the XML  returned will be 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>Registration Status</atom:title>    <atom:id>tag:api.constantcontact.com:/ws/customers/joesflowers/events/a07e1hnck1ba13cb6e4/registrants/001JGfmj1lDMfjnFdtzgDKxXo7k8myrBW4r-emL99zX_WkjN9jAOuxt53dsqNNBol2q/registrationstatus</atom:id>    <atom:content>
        <RegistrationStatus>
           <Status>CANCELLED</Status>
           <OverrideRegLimit>NO</OverrideRegLimit>
        </RegistrationStatus>
</atom:content>
</atom:entry>

 

 If the request cannot be completed, the following error conditions may be returned:

 

Errors
ConditionHTTP Status
Site Owner Does not own Event or Registrant 403
Invalid Event Id 400
Invalid Registrant Id 400

 

Once the registration status is obtained via the GET operation, it can be updated by editing the returned XML and sending it via a PUT operation. The error conditions are the same as above.

 

 

Obtaining Guest Details

 

Given a list of guests, programmers can obtain details of an individual guest by performing a GET operation on the guest resource. The URI for this resource is of the form:

 

/events/{event-id}/registrants/{registrant-id}/guests/{guest-id}

 

Below is a sample of the XML returned by the GET request:

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom">
    <atom:title>Jim Smith</atom:title>
    <atom:link rel="edit" href="/ws/customers/r{username}/events/{event-id}/registrants/{registrant-id}/guests/{guest-id}"/>
    <atom:updated>2011-05-06T17:24:30.033-04:00</atom:updated>
    <atom:id>tag:api.constantcontact.com/ws/customers/{username}/events/{event-id}/registrants/{registrant-id}/guests/{guest-id}</atom:id>
    <atom:content>
        <Guest>
            <FirstName>Jim</FirstName>
            <LastName>Smith</LastName>
            <CustomFields>
                <CustomField>
                    <Question>First Name:</Question>
                    <Answers>
                        <Answer>Jim</Answer>
                    </Answers>
                </CustomField>
                <CustomField>
                    <Question>Last Name:</Question>
                    <Answers>
                        <Answer>Smith</Answer>
                    </Answers>
                </CustomField>
                <CustomField>
                    <Question>Select your dinner option</Question>
                    <Answers>
                        <Answer>Fish</Answer>
                    </Answers>
                </CustomField>
                <CustomField>
                    <Question>I am interested in:</Question>
                    <Answers>
                        <Answer>Golf</Answer>
                        <Answer>Scuba Diving</Answer>
                        <Answer>Tennis</Answer>
                    </Answers>
                </CustomField>
                <CustomField>
                    <Question>Arrival Date</Question>
                    <Answers>
                        <Answer>2011-05-25T04:00:00+00:00</Answer>
                    </Answers>
                </CustomField>
                <CustomField>
                    <Question>Passport Number:</Question>
                    <Answers/>
                </CustomField>
                <CustomField>
                    <Question>Comments:</Question>
                    <Answers>
                        <Answer>Look forward to the event!</Answer>
                    </Answers>
                </CustomField>
            </CustomFields>
        </Guest>
    </atom:content>
</atom:entry>

 

This request can return certain error conditions, which are listed in the table below:

 

Errors
ConditionHTTP Status
Site Owner Does not own Event or Registrant 403
Invalid Event Id 400
Invalid Registrant Id 400
Invalid Guest Id 400

 

 

 

Updating Attendance Status

 

The AttendanceStatus of a registrant is managed via a URI of the following form

 

/events/{event-id}/registrants/{registrant-id}/attendancestatus

The AttendanceStatus can be obtained by performing a GET on this URI, and it can be updated by performing a PUT operation. (For detailed descriptions and specification of the required XML, please refer to the Registrants Collection and Resource page.)

 

The proper flow of control to update AttendanceStatus is:

1. Determine the registrant ID. This can be done by performing a GET on the registrants list for the event and extracting the <atom:id> tag for the registrant. This represents the unique URI for the registrant. Append "/attendancestatus" to this URI.

2. Perform a GET on the resulting URI to get the current AttendanceStatus

3. Edit the returned XML to updated the value of the AttendanceStatus. For example, for an registrant who actually attended the event, you would change the AttendanceStatus to:

 

            <AttendanceStatus>

              <Status>ATTENDED</Status>

              <Type>GROUP</Type>

            </AttendanceStatus>

 

4. Send the edited XML document to the REST server by performing a PUT on the same URI.

 

Errors

ConditionHTTP Status
Site Owner Does not own Event or Registrant 403
Invalid Event Id 400
Invalid Registrant Id 400
Invalid Guest Id 400

 

 

Managing Payment Status

Payment status for a registrant can be managed via the API. The API currently supports the GET and PUT operations, as described below.

 

Get Payment Status

 
URI

/events/{event-id}/registrants/{registrant-id}/paymentstatus

 
Method - GET
Sample XML

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<atom:entry xmlns:atom="http://www.w3.org/2005/Atom">

<atom:title>Attendance Status</atom:title>    <atom:id>tag:api.constantcontact.com,2010:/ws/customers/joesflowers/events/a07/registrants/001/paymentstatus</atom:id>

<atom:content>

<PaymentStatus>

<Status>PAID</Status>

<Type>GROUP</Type>

</PaymentStatus>

</atom:content>

</atom:entry>

 
Errors

Condition

HTTP Status

Site Owner Does not own Event or Registrant

403

Invalid Event Id

400

Invalid Registrant Id

400

 

Update Payment Status

URI

/events/{event-id}/registrants/{registrant-id}/paymentstatus

 
Method - PUT
Sample Atom for Body

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<atom:entry xmlns:atom="http://www.w3.org/2005/Atom">

<atom:content>

<PaymentStatus>

<Status>PAID</Status>

<Type>GROUP</Type>

</PaymentStatus>

</atom:content>

</atom:entry>

 
Return Code

On successful update a 204 (No Content) is returned. Status update can be verified by doing a GET on the same URI.

 
Errors

Condition

HTTP Status

Site Owner Does not own Event or Registrant

403

Invalid Event Id

400

Invalid Registrant Id

400

Invalid Payment Status

400

Marking Abandoned Registrant as Paid

400

webservices