Managing Registrants and Guests

webservices · ‎03-25-2011

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

Condition	HTTP 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

Condition	HTTP 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

Condition	HTTP 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:

<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

Condition	HTTP 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>

<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>

<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

Managing Registrants and Guests

Obtaining a List of Registrants for an Event

Obtaining Details of a Registrant

Errors

Errors

Errors

Updating Attendance Status

Errors

Managing Payment Status

Get Payment Status

URI

Method - GET

Sample XML

Errors

Update Payment Status

URI

Method - PUT

Sample Atom for Body

Return Code

Errors

Learning & Resources

Social Media

Call-To-Action Links

Welcome Your Audience