Getting data out of AlumnIQ (API)

AlumnIQ REST API

We have a REST API from which you can get the vast majority of the data unique to your AlumnIQ usage. The API itself is self-documenting. You can see the list of available resources and the documentation for each at: https://example.alumniq.com/api/ (substituting your school's prefix for "example")

Usage of the API requires an API Key, and all requests must be made over SSL (HTTPS).

Our API accepts and returns JSON data, the modern industry standard for similar data transmissions.

In your QA AlumnIQ environment, in addition to the documentation, you will find tools to make test requests against the API and see the responses it returns.

API Quick Guide

PRODUCTION API BASE: https://YOURDOMAIN/api/v1/index.cfm/ QA API BASE: https://qa-YOURDOMAIN/api/v1/index.cfm/ (then put the stubs below on the end) (with your apikey as an apikey=XXX url param -OR- in the body for a put or post)

API Keys

Your API key is not good forever. Pay special attention to the response header x-api-key-days-remaining which will serve as your early warning before your calls start to fail.

To reissue an API key manually, in the AlumnIQ admin under Security > API Keys you can create a new one for immediate use.

Alternatively (and certainly easier to script), you can generate a fresh key by trading in your old non-expired key:

GET /api/v1/index.cfm/exchange?emailaddress=RESPONSIBLE_PARTY_EMAIL_GOES_HERE&apikey=API_KEY_GOES_HERE

An API key is generally good for a year. If you script the /exchange call to run semi-annually, you'll be more than good to run autonomously in perpetuity.

GZip

All http responses from AlumnIQ, including the API, are GZip compressed. Some clients may not handle this scenario by default. Below are some examples of how we've seen this manifest, and how to work around it.

PowerShell

PowerShell's Invoke-WebRequest does not handle gzip compression by default. You need to add an appropriate header to indicate that you want it to handle gzip:

Invoke-WebRequest -Uri "https://you.alumniq.com/api/v1/..." -Headers @{
 set  "Accept-Encoding"="gzip, deflate, br"
}

Profiles and Contact Updates

New Profiles

GET /directory/created-since?since=yyyy-mm-dd

  • new profiles created on or after that day

  • useful if you're recording who's ever signed in to the portal

Updates to Profiles (VERSION 1/LEGACY)

GET /directory/updates?changeDate=yyyy-mm-dd

  • all updates that happened on that day

  • probably want to fetch and process daily

GET /directory/updates-since?since=yyyy-mm-dd

  • all updates that happened on or after that day

Updates to Profiles (VERSION 2/CURRENT/FALL 2021)

GET /directory/changes/homeaddress?changeDate=yyyy-mm-dd

  • any changes to home contact information on that date (local time)

  • optional param: autoprocess (default false). if true, we'll mark these changes as "processed" - meaning we're trusting you to deal with them and will apply them to your system of record.

  • sample response payload

PUT /directory/changes/homeaddress/{changeid}

  • marks an individual address update as processed; preferred over the autoprocess flag because the callback can happen after you actually do the update (assuming you do)

GET /directory/changes/workaddress?changeDate=yyyy-mm-dd

  • any changes to work contact information on that date (local time)

  • optional param: autoprocess (default false). if true, we'll mark these changes as "processed" - meaning we're trusting you to deal with them and will apply them to your system of record.

  • sample response payload

PUT /directory/changes/workaddress/{changeid}

  • marks an individual work address update as processed; preferred over the autoprocess flag because the callback can happen after you actually do the update (assuming you do)

GET /directory/changes/identity?changeDate=yyyy-mm-dd

  • any changes to identity (name-type and related) information on that date (local time)

  • optional param: autoprocess (default false). if true, we'll mark these changes as "processed" - meaning we're trusting you to deal with them and will apply them to your system of record.

  • sample response payload

PUT /directory/changes/identity/{changeid}

  • marks an individual identity update as processed; preferred over the autoprocess flag because the callback can happen after you actually do the update (assuming you do)

GET /directory/changessince/homeaddress?changeDate=yyyy-mm-dd

  • any changes to home contact information on or after that date (local time)

GET /directory/changessince/workaddress?changeDate=yyyy-mm-dd

  • any changes to work contact information on or after that date (local time)

GET /directory/changessince/identity?changeDate=yyyy-mm-dd

  • any changes to identity (name-type and related) information on or after that date (local time)

coming soon: additional resources for simplified custom field update capture

Loopback

GET /loopback/unprocessed

  • all unprocessed loopback records

  • probably want to fetch and process daily

PUT /loopback/unprocessed?loopbackIds=1,2,3,4

  • tell AlumnIQ you've properly handled the loopback record

Memberships

Getting New Ones

GET /memb/memberships?createdRangeBegin=yyyy-mm-dd&createdRangeEnd=yyyy-mm-dd

  • pay attention to the status column

  • probably want to fetch and process daily

GET /memb/memberships/{membershipId}

  • membershipId is the AlumnIQ PK for the membership (given to you in the call above)

  • probably want to fetch and process daily

GET /memb/members/{memberId}

  • gets an AlumnIQ member record (memberid is found in the call above)

Updating Foreign Keys (and other useful fields)

PUT /memb/members/{memberId} (with a payload)

  • pass xMemberId to set your member number on this individual

  • pass xid to set your constituent identifier on this individual

  • pass overwrite = true to force your values on top of whatever might have already been set for this person

  • recommend you do this as soon as memberships are added to your database

Transaction Reconciliation

GET /memb/transactions?rangeBegin=yyyy-mm-dd&rangeEnd=yyyy-mm-dd

  • if you reconcile daily or monthly, this will give you all transactions processed for memberships for the given period

Gifts

Pledge = parent of one or more gifts Gift = dollars to a fund for a term on a frequency Note: event gifts are managed separately

Pledges and Gifts

GET /giving/pledges/?date=yyyy-mm-dd

  • all pledges created on that date

  • probably want to fetch and process daily

GET /giving/gifts/?date=yyyy-mm-dd

  • all gifts created on that date

  • a more loosely formed version of the prior call

GET /giving/gifts/cancelled?date=yyyy-mm-dd

  • any gifts cancelled on the given date

  • you'll need to call this to find out if you need to term a gift already booked

  • probably want to fetch and process daily

Payments and Transactions

GET /giving/giftpayments/?date=yyyy-mm-dd

  • all payments processed on that date

  • probably want to fetch and process daily

Events

Event Metadata

Events have a lifecycle. 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."

Consider that when choosing how to add event attendee and financial data into Advance.

GET /events

  • three options for filters:

  • onOrAfter=yyyy-mm-dd

  • createdOnOrAfter=yyyy-mm-dd

  • closedOnOrAfter=yyyy-mm-dd

  • sample response payload

GET /events/{eventid}

  • neat feature: eventid = the AlumnIQ event id. But if you put the Advance event ID on the event, you can also fetch by the Advance event ID using a slightly different syntax.

  • Advance event ID = b1234

  • then GET /events/x-b1234 will work too

  • sample response payload

GET /events/{eventid}/activities

Attendees

A few small pointers to guide you:

  • Reservation = the party. A reservation has one or more Person records under it.

  • The first Person is the primary registrant, and the one responsible for payment (and hard credited for the gift as a result)

  • an individual reservation may have multiple transactions executed against it (this is not how iModules works)

GET /events/{eventid}/attendees

  • all people registered regardless of what they signed up for

GET /events/activities/{activityid}/attendees

  • all people signed up for this activity specifically

PUT /attendees/{personid}

  • Update an individual human's registration data

  • xid = 12412352

Finances and Accounting

GET /events/transactions?txDate=yyyy-mm-dd

  • all transactions regardless of method that happened on that date

  • primarily helpful for credit card reconciliation purposes

GET /events/gifts?giftDate=yyyy-mm-dd

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

GET /events/{eventId}/transactions/detail

  • only the transactions related to a specific event

  • useful after the event is closed (maybe)

GET /events/{eventId}/balance-sheet

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

GET /events/{eventId}/ledger/detail

  • awesome detail to complement the balance sheet report

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

PreviousSending us your dataNextAPI: Financial Data

Last updated