Retrieving Documents via the WebAdMIT API

Setting Up in WebAdMIT

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.

WebAdMIT API Key

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.

Root URLs

The root URL for your API call depends on which environment you're trying to interact with:

Retrieve Documents from WebAdMIT

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 PDF Manager template you want to run. Pull down a list of all PDF Manager templates available to the selected user identity using the “PDF Manager Template List” endpoint (GET /api/v1/user_identities/:user_identity_id/pdf_manager_templates https://liaison-intl.github.io/pdf_m..._template.html). Identify the appropriate PDF Manager template using the “name,” “list_name,” and “document_source_title” fields returned in the response. You’ll use the “id”—the PDF Manager template ID—field from the response to generate an export file.

With the user identity and PDF Manager template chosen, you’re ready to generate an PDF Manager batch. Make a call to the “PDF Manager Batch Initiate Run” endpoint (POST /api/v1/user_identities/:user_identity_id/pdf_manager_batches https://liaison-intl.github.io/pdf_manager_batch.html) including in the body of the request a JSON string matching the following format.

{
  "pdf_manager_batch": {
    "pdf_manager_template_id": :pdf_manager_template_id
  }
}

This call triggers the generation of PDFs, compressed in zip directories, according to the PDF Manager template. Each PDF will following the naming convention configured in the PDF Manager template, and it will include the document type selected for the population of applicants included in the selected list. The response to this call contains an important ID for the PDF Manager batch you’ve triggered—“id”. You’ll need this PDF Manager batch ID to check on the status of the file generation.

WebAdMIT limits the size of each zip directory to 1 GB, so, for especially large document exports, you should expect multiple zip directories. With careful list design, you can limit the documents included with each run of a PDF Manager template to avoid handling multiple zip files. Using the “Last Printed Date” feature will also help you avoid exporting the same document repeatedly.

Now that the PDF files are being generated, you’ll need to keep an eye on the generation to find out when files are ready to download. PDF Manager templates that include large document types (e.g., Full Application PDF), that include document types that are likely to have multiple documents per applicant (e.g., letters of recommendation), or that have lists that include a lot of applications can take a long time to generate. You’ll want to make regular calls to the “PDF Manager Batch Show” endpoint (GET /api/v1/user_identities/:user_identity_id/pdf_manager_batches/:pdf_manager_batch_id https://liaison-intl.github.io/pdf_manager_batch.html) to determine when the PDF zip files are ready for download. When the value in the “status” field of the response to this call is “Available,” the PDF zip files are 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 an important element: “download_hrefs.” This element is an array that includes a partial URL for each PDF zip directory to be downloaded. If there’s only one PDF zip directory, then this array will have just a single partial URL. You’ll use these partial URLs to retrieve your PDF zip files.

Once your PDF zip files are ready, you’ll want to retrieve them so that you can load the PDFs to your local systems. Take each value in the “download_hrefs” element from the status check call (see above) and make a call to the “PDF Manager Zip File Download” endpoint (GET /api/v1/user_identities/:user_identity_id/pdf_manager_zip_files/:pdf_manager_zip_file_id/download https://liaison-intl.github.io/pdf_m..._zip_file.html). You’ll notice that the “download_hrefs” values are already in the format of the download endpoint. Looping through each value and prepending it with the root URL (see above) for your CAS’s API will allow you to download each file. Save the zip files to your desired local directory.

Now that you have the zip directories on hand, you’ll want to load the PDFs to your local systems. Each institution has its own processes for loading data. The ability to customize PDF filenames in the PDF Manager enables you to include all the information about the document you’ll need to load it to your local systems: who the applicant is, which application it’s for, and what type of document it is. Many SIS and CRM systems have tools for loading PDFs in bulk. While some of these tools can ingest zip directories full of PDF files and use the PDF filenames for mapping the documents, other tools require the zip directory to include an index file listing all of the PDFs present (Document Import Processor format). WebAdMIT’s PDF zip files don’t include an index file. If your system requires an index file for bulk PDF upload, you’ll have to create that outside of WebAdMIT. Some systems don’t have tools for loading images in bulk, so you’ll have to process each PDF individually.

Sample Retrieving Documents Files

Use our  Sample WebAdMIT Retrieve Documents PY file for assistance retrieving documents through the WebAdMIT API.