Signature Events

There is 1 specific policy decision you should make before you start capturing registrant data: Do you want it to start showing up in your CRM as soon as possible, or do you want it once the master event is "closed" (meaning it's an immutable permanent record)?

You can get it into your CRM faster by pulling data from us on a regular basis (even up to several times per hour), but you must be prepared to handle changes and cancellations, too. Post-closure pulls are simpler because you will only ever need to pull each master event's data once, and it will correctly indicate actual attendance, at the cost of having to wait longer for the data to be available in your CRM.

Either way, the master event will need to exist in your CRM before you can map registrants/attendees to it. This isn't something we can do for you, but once it's done be sure to add the CRM activity code to AlumnIQ in the External Master Event ID (and/or External Event ID) field as appropriate. Which field(s) you'll use depends on the level of tracking granularity you're implementing. Most customers adopt the high level participation only approach by mapping exclusively to the AlumnIQ Master Event.

Object Model

• Master Events have Events

• Master Events must have at least one Event

• Events are what a Person signs up to attend. They are not required to be signed up for any Events, however.

• Registration is package-based, offering 0 or more events to choose from.

Check in timestamps are recorded on the person and person-event combinations; the person one is a latch trigger fired when the first event is checked in to.

• Reservations have People

• a Reservation must have at least one Person

• the first Person is called the Primary Registrant and is always an adult

• the age cutoff for adult vs. minor is set on a per master event basis

• the Primary Registrant is responsible for payment

• the Primary Registrant should therefore be given hard credit for any gift made at the time of registration

A primary registrant may make at most one gift to one fund during checkout.

• Payments are credited to the Reservation, not an individual Person

• A Reservation may have zero or more Transactions

• A transaction represents money changing hands and could be a payment or refund

• Discounts and adjustments are made per reservation, not per person or person-activity. Each has an optional note and captures the operator who made the change.

• The only 1:1 guaranteed transaction is between a gift and a payment to fulfill it (we support combined or separate charging and to date all customers have chosen separate)

It is rare to be able to associate a single transaction with a specific non-gift line item on a party's registration. Transactions credit and debit the party as a whole.

Process

How often you'll pull this data depends on how fast you want registrant info to appear in your CRM. Some prefer to see reasonably up to date participation (which is harder to manage state) and others delay until the data is no longer changing (post-closure) for permanent archival.

Master Events have a lifecycle in AlumnIQ. Creation, operation, and then closure. Closure is a deliberate action taken by the program manager to say "we're done and the data will not change further." Because master events in flight may be modified at any time -- time, date, location, name, and category are all moving parts -- recognize that you may need to refresh this object periodically, not just once.

Reminder: many of the API resources we'll reference below have additional optional arguments documented at https://YOUR_ALUMNIQ_SIGNATURE_DOMAIN/api

YOUR_ALUMNIQ_SIGNATURE_DOMAIN more than likely is in the form *.events.alumniq.com

These additional arguments have different uses that may fit your model more appropriately.

Option 1: Post-Closure (simplest, but latest data delivery), just high level participation

Execute this daily. Doing all of these steps ensures AlumnIQ has your event/activity/constituent identifiers on as many records as possible. If you don't care to store activity-level participation you can omit those steps entirely.

All of the API URLs below are appended to the API base url: https://YOUR_ALUMNIQ_SIGNATURE_DOMAIN/api/index.cfm

You can use a valid and active AlumnIQ Platform API key or a signature-system specific API key (found on the Security page in admin) for all of these calls.

Option 2: Post-Closure, individual event participation

Option 3: Update as you go

Best Practices

Making sure that your CRM's event, activity, and constituent identifiers are set appropriately on the corresponding AlumnIQ Master Event, Event, and Person records will speed data exchange and minimize manual clean-up needed later.

Finances and Accounting

Similar theme: because registrations are mutable, so too are the funds. For that reason it's best to hold off on pulling the balance sheet (for transfer purposes) until the event is closed.

You are welcome to pull reconciliation data anytime so they can square up against bank statements.

All of the API URLs below are appended to the API base url: https://YOUR_ALUMNIQ_SIGNATURE_DOMAIN/api/index.cfm

GET /transactions/since?mastereventid=MASTEREVENTID&since=YYYY-MM-DD

• all transactions regardless of method, that happened on or after the given date

• primarily helpful for internal reconciliation purposes

GET /cctransactions/since?mastereventid=MASTEREVENTID&since=YYYY-MM-DD

• CREDIT CARD ONLY transactions regardless of method, that happened on or after the given date

• primarily helpful for credit card reconciliation purposes

General API Overview

Metadata

/masterevents – a feed of mastereventIDs which you'll need to pass along on many of the other API calls so that you're pulling the right segment of data.

/events/ - (req: mastereventid) a feed of event metadata (name, dates/times, tags, location, fees, etc.) that can be read, cached, transformed, and reused to populate event data on your website. For obvious reasons we strongly recommend doing your own caching of the data as it doesn't change much and your site visitors surely don't need to wait for round trip API calls just to see a schedule of events.

People

/people – (req: mastereventid, opt: registrationdate) everybody registered regardless of what they're registered for. A great feed for bio updates, extraction for an email list, or temporary storage. We recommend purging your local copy and reloading daily if that's your plan – people cancel all the time.

/person/{personid} – bio data for one individual registrant. You can also POST to that same endpoint to update (if passed) each or any of: xid, prefclassyear, badgenameoverride, badgelastnameoverride, badgeannotation, donormeta, and volunteermeta. This is a convenient way for you to do your own constituent matching algo and update our end with that new xid data.

/cancellations – (req: mastereventid, opt: canceldate) fairly self explanatory

Events/Participation

/events/{eventid}/attendees – get an array of people registered for a given event, indicating whether or not they attended.

Person-Event Combo

/participants -- (req: mastereventid, opt: eventid) - a summary/narrow version of participants broken down by lower-level activity including indicators of participation

/activityparticipation -- (req:mastereventid) - only includes events with a code and participants with an xid. completely omits the irrelevant/unmatched.

/gridreference – (req: mastereventid) – this gives you the column mappings to understand and interpret the response from the grid endpoint

/grid – (req:mastereventid) – people down the left, columns for each event indicating participation (registered or attended if true) at each intersection. A basic set of personal info is included; we expect you'll hit the /people endpoints to get more if needed.

Gifts

/gifts - (required: datePaid=yyyy-mm-dd) - all gifts, regardless of event/masterevent, paid on the requested date.