LIAISON API SPECIFICATION DOCUMENT
WEBADMIT EXPORT MANAGER API
Table of Contents
Introduction .......................................................................................................................................................................... 2
WebAdMIT Identities ........................................................................................................................................................ 3
WebAdMIT API Permissions & Keys............................................................................................................................ 4
API Rate Limit ....................................................................................................................................................................... 5
API Methods .......................................................................................................................................................................... 6
1. user_identities ............................................................................................................................................................. 6
Request ............................................................................................................................................................................... 6
Response ............................................................................................................................................................................ 6
2. exports ........................................................................................................................................................................... 8
Request ............................................................................................................................................................................... 8
Response ............................................................................................................................................................................ 8
3. exports (by identity)................................................................................................................................................. 9
Request ............................................................................................................................................................................... 9
Response ............................................................................................................................................................................ 9
4. export_files (initiate a run) ................................................................................................................................. 10
Request ............................................................................................................................................................................ 10
Response ......................................................................................................................................................................... 10
Callback ........................................................................................................................................................................... 11
5. export_files (check status) .................................................................................................................................. 11
Request ............................................................................................................................................................................ 12
Response ......................................................................................................................................................................... 12
6. export_files (check status in batch) ................................................................................................................. 13
Request ............................................................................................................................................................................ 13
Response ......................................................................................................................................................................... 13
Copyright © 2015 Liaison International, Inc. All Rights Reserved.
www.liaison-intl.com
Introduction
The Liaison Export Manager API is designed to allow permissioned users to look up, run, and
retrieve export files designed in WebAdMIT’s Export Manager from a direct back-end API. This
allows technically-savvy users of WebAdMIT to automate the retrieval of data from WebAdMIT for
integration into other on-campus systems.
The following key points and conventions are followed in the Export Manager API:
 This is a REST-based API that will be accessed over a standard HTTP/HTTPS API client library
such as Net::HTTP or Apache HttpClient (all requests must use HTTPS).
 Access is controlled via a new “API Access” permission granted in WebAdMIT, and a secure
(and refreshable) API key is generated by the user in their account profile in WebAdMIT.
 API Access permission is based off of WebAdMIT user identities (described below). All of a
user’s exports that can be run via API are owned by one of that user’s identities.
 The user’s API key must be passed for every API request, and will be passed in the HTTP
header of the request using the “x-api-key” header.
 All API requests will be GET or POST actions against RESTful paths.
 Response bodies from API calls will be JSON objects and arrays.
The root for all API calls should be https://api.webadmit.org.
Copyright © 2015 Liaison International, Inc. All Rights Reserved.
www.liaison-intl.com
WebAdMIT Identities
All permissions in WebAdMIT cascade from the concept of “Identities”. What is an “Identity” in
WebAdMIT? Each of the selectable items in the standard WebAdMIT account dropdown are
considered to be standard admissions-level “identities” – for most universities, this ties to the
cohorts of students from each major graduate department:
There are two additional “special” types of identities available in WebAdMIT:
•
•
An “Association User” can access data for all schools in a given Centralized Application Service
(e.g. someone at ASPPH would be able to access all data for all schools of public health in
SOPHAS, and someone at AACP would be able to access data for all schools of pharmacy in
PharmCAS)
An “Institution User” can access data for all departments & programs at a university
implementing UniCAS (this type of user would be able to create a university-wide data
export)
In general, configuration entities such as Lists, Exports, Email Templates, and so on in WebAdMIT are
“owned” by one of a user’s identities. Every identity that is part of a user’s profile has a name and a
unique identifier. These can be retrieved via one of the API calls discussed below in this document.
Admissions, Association, and Institutional identities can all be addressed by name or ID in the same
manner.
Copyright © 2015 Liaison International, Inc. All Rights Reserved.
www.liaison-intl.com
WebAdMIT API Permissions & Keys
WebAdMIT user accounts who need access to the Export Manager API need to be given the new “API
Access” permission for each of the identities that they have in the WebAdMIT system and that they
wish to access via the API. This permission can also be made part of a standard WebAdMIT Work
Group.
Users with API Access enabled on at least one of their WebAdMIT identities will be able to generate
an API key in their Edit My Account section of WebAdMIT. This API key will then be associated with
that user and all of their identities within WebAdMIT. If the key is compromised, it can be
regenerated from this screen at any time. This API key must be passed in the HTTP header (key
name of “x-api-key”) of all requests to the API, or requests will be rejected.
Copyright © 2015 Liaison International, Inc. All Rights Reserved.
www.liaison-intl.com
API Rate Limit
WebAdMIT will allow an individual API Key to access the API up to 1,000 times in a 1-hour period.
This should be more than sufficient for all normal export running & retrieval, no matter how
frequently during the day a user wishes to run their exports.
Users can view the current API Rate Limit as well as how many calls an individual API Key has left in
the current 1-hour period by viewing the response headers of any API call:
Copyright © 2015 Liaison International, Inc. All Rights Reserved.
www.liaison-intl.com
API Methods
1. user_identities
Retrieve details on all user identities that are part of a user’s WebAdMIT profile and that have the
“API Access” permission assigned to them. The id associated with each identity will not change, and
only becomes something new when a new identity is created – for example at the start of a new
academic cycle.
Request
Method URL
GET
/api/v1/user_identities
Type
Params
Values
HEAD
x-api-key
String
Response
Status
Response
200
The response is the collection of user identities belonging to the current user that have
been given the “API Access” permission:
{
"href": "/api/v1/user_identities",
"user_identities": [
{
"id": 21530,
"type": "Admissions User",
"organization": "Demo University School of Public Health",
"association": "SOPHAS",
"cycle": "2013 - 2014",
“institution”: “Demo University”
},
{
"id": 37442,
"type": "Admissions User",
"organization": "Demo University School of Business",
"association": "UniCAS",
"cycle": "2014 - 2015",
“institution”: “Demo University”
},
{
Copyright © 2015 Liaison International, Inc. All Rights Reserved.
www.liaison-intl.com
}
]
}
"id": 41542,
"type": "Admissions User",
"organization": "Demo University College of Health Sciences ",
"association": "CSDCAS",
"cycle": "2014 - 2015"
“institution”: “Demo University”,
The response will be similar for users with Association-level identities:
{
"href": "/api/v1/user_identities",
"user_identities": [
{
"id": 53021,
"type": "Association User",
"organization": "",
"association": "SOPHAS Admin",
“institution”: “”,
"cycle": "2013 - 2014"
}
]
}
The response will be similar for users with Institution-level identities:
{
"href": "/api/v1/user_identities",
"user_identities": [
{
"id": 30154,
"type": "Institution User",
"organization": "",
“association”: “”,
"institution": "Demo University Admin",
"cycle": "2013 - 2014"
}
]
}
Copyright © 2015 Liaison International, Inc. All Rights Reserved.
www.liaison-intl.com
2. exports
Retrieve details on all exports (e.g. export templates) that a user has access to across all of their
identities. The id returned for each export is the value that needs to be provided in order to run that
export.
Request
Method URL
GET
/api/v1/exports
Type
Params
Values
HEAD
x-api-key
String
Response
Status
Response
200
The response is the collection of exports belonging to any identity in the current
user’s WebAdMIT profile, including the List that each export is tied to:
{
}
"href": "/api/v1/exports",
"exports": [
{
"id": 29897,
"name": "Nightly Banner Export",
"list_type": "all",
"format": "Comma-Separated Values",
"mime_type": "text/csv;charset=iso-8859-1"
},
{
"id": 23696,
"name": "Only Matriculants",
"list_type": "Matriculating Applicants",
"format": "Comma-Separated Values",
"mime_type": "text/csv;charset=iso-8859-1"
},
{
"id": 36856,
"name": "Foreign Applicants File",
"list_type": “Non US Applicants”,
"format": "Comma-Separated Values",
"mime_type": "text/csv;charset=iso-8859-1"
}
]
Copyright © 2015 Liaison International, Inc. All Rights Reserved.
www.liaison-intl.com
3. exports (by identity)
Retrieve details on all exports (e.g. export templates) that a user has access to within a specific
identity. The id returned for each export is the value that needs to be provided in order to run that
export.
Request
Method URL
GET
/api/v1/user_identities/:user_identity_id/exports
Type
Params
Values
HEAD
x-api-key
String
PARAM
user_identity_id
Numeric
Response
Status
Response
200
The response is the collection of exports belonging to a specific identity in the current
user’s WebAdMIT profile, including the List that each export is tied to:
{
}
"href": "/api/v1/user_identities/24567/exports",
"exports": [
{
"id": 29897,
"name": "Nightly Banner Export",
"list_type": "all",
"format": "Comma-Separated Values",
"mime_type": "text/csv;charset=iso-8859-1"
},
{
"id": 23696,
"name": "Only Matriculants",
"list_type": "Matriculating Applicants",
"format": "Comma-Separated Values",
"mime_type": "text/csv;charset=iso-8859-1"
}
]
Copyright © 2015 Liaison International, Inc. All Rights Reserved.
www.liaison-intl.com
4. export_files (initiate a run)
Initiate the background execution of a specific export (e.g. export template). Required parameters
are the identity that the export belongs to, and the id of the export that you wish to run. This will
create an instance of a running export_file, which is what you can monitor to determine when the
export is ready to be downloaded. The id in the response from this call is the handle to that
running export_file and what is used in future calls to check on the status of the run.
Important note: this id representing the handle to the running instance of the export is not always
uniquely generated with each run – if you attempt to run the same export several times in close
succession, you will receive back the id of the already-running instance of that export. This is a
safeguard to prevent many accidental simultaneous runs of the exact same export – one must finish
before a new one can be initiated.
Request
Method URL
POST
/api/v1/user_identities/:user_identity_id/exports/:export_id/
export_files
Type
Params
Values
HEAD
x-api-key
String
PARAM
user_identity_id
Numeric
PARAM
export_id
Numeric
PARAM
callback
String (optional callback URL)
Response
Status
Response
200
The response is the handle to the running instance of the export the user kicked off,
including the id of that export_file (the running instance) and the status of the
execution. Possible status values are “Queued”, “In Progress”, “Available”, or “Failed”.
{
"export_files": {
"id": 74780,
"href": "/api/v1/exports/86466/export_files/74780",
"export_id": 86466,
Copyright © 2015 Liaison International, Inc. All Rights Reserved.
www.liaison-intl.com
}
}
"status": "Queued"
Callback
For requests using the optional “callback” parameter, you should build your request as follows:
/api/v1/user_identities/:user_identity_id/exports/:export_id/
export_files?callback=http://someurl.com/your_callback.cgi
When the file is ready, WebAdMIT will POST to the callback URL that you specify with the
following form POST parameters:
export_file[id]
export_file[export_id]
export_file[status]
An example of the body of a POST to a callback when a file is ready is as follows:
export_file[id]=99752&export_file[export_id]=123316&export_file[status]=Available
This gives you the export_file_id of the file that’s ready for download once it is available (you will
use the export_id and the export_file_id POSTed here to form the next API call in item 5 below to
actually get the URL to download the now-ready file).
We recommend the use of the public RequestBin (http://requestb.in/) service in order to test out
how this particular call works.
5. export_files (check status)
Retrieve the status of a running export file initiated with the previous POST. Required parameters
are the id of the export (e.g. export template) and the id of the running instance of that export (e.g.
export file) that you wish to check the status of. You may continue to issue this call over a reasonable
polling interval until the file becomes ready for download. Once the status of the file becomes
“Available”, a download URL for the file will also be returned from the API. This URL is secure and
time-sensitive, expiring less than 30 seconds from when it is issued. It is the expectation that
software using this API will immediately download the file once given the URL. The download URL
can always be re-generated if it expires by re-calling this method – a new URL will be issued.
Copyright © 2015 Liaison International, Inc. All Rights Reserved.
www.liaison-intl.com
Request
Method URL
GET
/api/v1/exports/:export_id/export_files/:export_file_id
Type
Params
Values
HEAD
x-api-key
String
PARAM
export_id
Numeric
PARAM
export_file_id
Numeric
Response
Status
Response
200
The response is the status of the running instance of the export the user is checking on,
including the id of that export_file (the running instance), the export id (the export
template), the status of the execution, and the actual (time-sensitive) URL to download th
file if it is ready. Possible status values are “Queued”, “In Progress”, “Available”, or
“Failed”.
{
"export_files": {
"id": 74780,
"href": "/api/v1/exports/86466/export_files/74780",
"export_id": 86466,
"status": "Available",
"download_url": "https://webadmitproduction.s3.amazonaws.com/export_files/reports/000/074/780/d19d6c
0a34b7062c4496530f3d5dbfb_original.txt?AWSAccessKeyId=AKIAIT7746U
RBGHSHEA&Expires=1425359248&Signature=y2jwr78kbVt44xz%2BfaEnp
5dXKU%3D&response-contentdisposition=attachment%3B%20filename%3DTest-APIExport.csv&response-content-type=text%2Fcsv%3Bcharset%3Diso-8859-1
}
}
Copyright © 2015 Liaison International, Inc. All Rights Reserved.
www.liaison-intl.com
6. export_files (check status in batch)
Closely mimics the “Recent Files” screen in the WebAdMIT application. This call will display all
export files that have recently run under a particular identity, and their status. Importantly, the
download URL is not displayed in this response as these individual expiring URLs can only be
generated by calling for the status of an individual file directly using the previous call. You can use
the results of this call and loop through each one to get a download URL for each export file marked
as “Available”.
Request
Method URL
GET
/api/v1/user_identities/:user_identity_id/export_files
Type
Params
Values
HEAD
x-api-key
String
PARAM
user_identity_id
Numeric
Response
Status
Response
200
The response is the collection of id’s and statuses of the running exports for a specific
identity within a user’s WebAdMIT profile:
{
"href": "/api/v1/user_identities/37442/export_files",
"export_files": [
{
"id": 74780,
"href": "/api/v1/exports/86466/export_files/74780",
"export_id": 86466,
"status": "Available"
},
{
"id": 77384,
"href": "/api/v1/exports/89146/export_files/77384",
"export_id": 89146,
"status": "Available"
}
]
}
Copyright © 2015 Liaison International, Inc. All Rights Reserved.
www.liaison-intl.com