Before you can automate your data integration using the WebAdMIT API, you’ll need to think through your business process. The WebAdMIT API exposes data and document exports that have been configured within WebAdMIT. You’ll have to build the Lists, Exports, PDF Manager templates, and Custom Fields you need in WebAdMIT before you can interact with them using the API. Be sure to always include enough information in your exports to completely identify in your local systems the person and application to which the data or documents belong.
First, you’ll need to get an API key from WebAdMIT. Log in to WebAdMIT and click on Account in the top right corner. Once there, click the Edit My Account button. Scroll down to the API Key section. If you don’t already have an API key, click Generate New Key. If you do have a key, click Show Key. Record the alphanumeric string displayed here—you’ll need to include with every call you make to the WebAdMIT API.
The root URL for your API call depends on which environment you're trying to interact with:
|
Environment |
Root URL |
|---|---|
|
Production |
|
|
Prelaunch |
With the appropriate API key and root URL in hand, pull down all user identities accessible to the user with the “User Identity List” endpoint (GET /api/v1/user_identities https://liaison-intl.github.io/user_identity.html). Each user identity corresponds to a specific combination of cycle, association, and organization. Users frequently have more than one user identity, especially when there’s more than one CAS on campus. For example, a user will have one user identity for accessing CASPA 2023-2024 data, and a different one for accessing PTCAS 2023-2024 data. Think about which applicants you’re interested in and select the appropriate user identity—you’ll use the “id” for this user identity to retrieve the data.
Now that you’ve chosen the appropriate user identity, you’ll need to pick the export you want to run. Pull down a list of all exports available to the selected user identity using the “Export/Report List” endpoint (GET /api/v1/user_identities/:user_identity_id/exports https://liaison-intl.github.io/expor..._identity.html). Identify the appropriate export using the “name,” “list_type,” and “format” fields returned in the response. You’ll use the “id”—the export ID—field from the response to generate an export file.
With the user identity and export chosen, you’re ready to generate an export file. Make a call to the “Export/Report Files (initiate a run)” endpoint (POST /api/v1/user_identities/:user_identity_id/exports/:export_id/export_files https://liaison-intl.github.io/export_files.html). This call triggers the generation of the selected export. The export file will include all the fields selected when building the export for all the records included in the chosen list. The response to this call contains an important ID for the export file you’ve triggered—“id.” You’ll need this export file ID to check on the status of the file generation.
Now that the export file is being generated, you’ll need to keep an eye on it to find out when it’s ready to download. Exports that include a lot of fields or that have lists that contain a lot of applications can take a long time to generate. You’ll want to make regular calls to the “Export/Report Files (check status) Show” endpoint (GET /api/v1/exports/:export_id/export_files/:export_file_id https://liaison-intl.github.io/expor...les_check.html) to determine when the export file is ready for download. When the value in the “status” field of the response to this call is “Available,” the file is ready (possible status values are "Initializing," "Queued," "In Progress," "Available," "Success With Errors," "Empty List," and "Failed"). The response to this status check call includes another important term: “download_url.” The value in this field is the URL where you can download the generated export file.
Once your export file is ready, you’ll want to retrieve it so that you can load to your local systems. Take the “download_url” value from the status check call (see above) and make a GET call to that URL, saving the output to the desired local directory.
Now that you have the export file on hand, consider whether the file format, field headers, and field values need to be transformed to meet the requirements of your local systems. For example, your local system may only accept “|” delimited files, so you’d need to convert the WebAdMIT export file to match that format. Your system may require that fields have particular names: for instance, last name might need to be called “lname” instead of “last_name.” Finally, your system may only be able to accommodate certain field values: for example, “M” and “F” instead of “Male” and “Female.”
Once your file and its contents are formatted correctly, you’ll want to load the file to your local systems. Each institution has its own processes for loading data. You may be able to schedule a job that picks up files from a specific location and loads them to your SIS. You may be able to deliver files to a SFTP directory, from where they will be automatically retrieved and loaded. You may have to manually run a process through your SIS or CRM interface to import each file. You may be able to load data programmatically with direct access to the database for your local system, in which case you may want to read the export file into an object and load it from there.
Use our Sample Retrieve Data PY file for assistance retrieving data through the WebAdMIT API with Python 3.