Everyday 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 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 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 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 Event ID (and/or External Activity ID) field as appropriate. Which field(s) you'll use depends on the level of tracking granularity you're implementing. In most cases you'll want to save your code as the external id on an AlumnIQ Activity.

Object Model

  • Events have Activities

  • Events must have at least one Activity

  • Events are shells; Activities are what a Person signs up to attend

Check in timestamps are recorded on the person-event and person-activity combinations; the person-event one is a latch trigger fired when the first activity 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 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.

Events have a lifecycle in AlumnIQ. Creation, operation, and then closure. Closure is a deliberate action taken by the event manager to say "we're done and the data will not change further." Because 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_DOMAIN/api

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

Option 1: Post-Closure (simplest, but latest data delivery)

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_DOMAIN/api/v1/index.cfm

  1. GET /events?closedonorafter=YYYY-MM-DD

  2. Loop those, GET /events/EVENT_ID_GOES_HERE

  3. Use metadata to create the Event in your CRM

  4. PUT /events/EVENT_ID_GOES_HERE/?xcode=YOUR_CRM_EVENT_ID

  5. Loop the activities collection within the Event metadata

  6. Use metadata to create each Activity in your CRM

  7. PUT /events/activities/ACTIVITY_ID_GOES_HERE/?xcode=YOUR_CRM_ACTIVITY_ID

  8. Then GET /events/EVENT_ID_GOES_HERE/attendees

  9. RECOMMENDED: if you create constituent records for Person entities lacking an xid assignment, please call PUT /attendees/PERSON_ID_GOES_HERE?xid=XID_GOES_HERE with the value

  10. Create CRM registration records for each person

  11. Then for each activity, GET /events/activities/ACTIVITY_ID_GOES_HERE/attendees to fetch and update CRM participation records

Option 2: Update as you go (better distribution across your org)

Execute this daily, or more often if you dare. Doing all of these steps ensures AlumnIQ has your event/activity/constituent identifiers on as many records as possible.

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

  1. GET /events?onorafter=YYYY-MM-DD&onlyOpenEvents=1

  2. Loop those, GET /events/EVENT_ID_GOES_HERE

  3. If not in CRM, use metadata to create the Event in your CRM then PUT /events/EVENT_ID_GOES_HERE/?xcode=YOUR_CRM_EVENT_ID

  4. Loop the activities collection within the Event metadata

  5. If not in CRM, use metadata to create each Activity in your CRM then PUT /events/activities/ACTIVITY_ID_GOES_HERE/?xcode=YOUR_CRM_ACTIVITY_ID

  6. Then GET /flat/events/EVENT_ID_GOES_HERE/activities/ACTIVITY_ID_GOES_HERE/attendees

  7. RECOMMENDED: if you create constituent records for Person entities lacking an xid assignment, please call PUT /attendees/PERSON_ID_GOES_HERE?xid=XID_GOES_HERE with the value

  8. Pay close attention to the registrationState value to create and update CRM registration records for each person

Best Practices

Making sure that your CRM's event, activity, and constituent identifiers are set appropriately in AlumnIQ will speed data exchange and minimize manual clean-up needed later.

Getting the identifiers there, as you saw in the previous section, is a process of iteration, evaluation, and callback - but it makes future requests more consistent and less likely to result in duplication.

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_DOMAIN/api/v1/index.cfm

GET /events/transactions?txDate=YYYY-MM-DD&apikey=API_KEY_GOES_HERE

  • all transactions, across all events, regardless of method, that happened on the given date

  • primarily helpful for credit card reconciliation purposes

GET /events/EVENT_ID_GOES_HERE/transactions/detail?apikey=API_KEY_GOES_HERE

  • only the transactions related to a specific event

  • useful after the event is closed (maybe)

GET /events/gifts?giftDate=YYYY-MM-DD&apikey=API_KEY_GOES_HERE

  • just gifts received and paid on the given date (reminder: only gifts given incidentally as part of event registration)

GET /events/EVENT_ID_GOES_HERE/balance-sheet?apikey=API_KEY_GOES_HERE

  • tells you where to put actual dollars post-event closure

GET /events/EVENT_ID_GOES_HERE/ledger/detail?apikey=API_KEY_GOES_HERE

  • thorough detail to complement the balance sheet report

  • tells you how we arrived at the bottom line numbers for this event

Ensuring account codes/subaccount codes are set on the AlumnIQ chart of accounts will also help with transfers.

PreviousIntegration RecipesNextSignature Events

Last updated