Skip to main content
Liaison

Retrieving Documents via the CAS API

  1. Last updated
  2. Save as PDF

Getting Access to the CAS API

You’ll need to get access to the CAS API before you can begin using it to retrieve data. Reach out to Liaison customer service or a member of your Liaison account team to request access. Be ready to provide the necessary information: your name, institution where you work, CAS you’re requesting access to, admissions cycle year you’re interested in, your phone number, and your email address.

Working with API CredentialsEdit section

Once you have access, you’ll get credentials for accessing the CAS API: API key, username, and password. Store these credentials in a secure location; you’ll need to use them every time you interact with the CAS API.  

Application Form IDsEdit section

Additionally, you’ll have a list of ID numbers (called “Instance IDs,” “Form IDs,” or “Application Form IDs”), which represent the data sets to which you have access. A single ID represents a combination of a single CAS with a single admissions cycle year (e.g., “CASPA 2023-2024”). Store this list for future reference; you’ll need to send an Instance ID with every call to the CAS API.

Root URLs

The root URL to use for the CAS API can depend on which CAS and environment (i.e., production, prelaunch) you want to use. For production data, the default root URL is https://api.liaisonedu.com. Unless otherwise informed, this is the root URL to use. Contact Liaison customer service if you’re unsure of which root URL to use.

Authorization

To successfully make any calls to the CAS API, you’ll need an authorization token. The authorization call is the first call you’ll make in any interaction with the CAS API. The token is valid for one hour, so you may need to reauthorize if your operation lasts a long time. To retrieve an authorization token, make a call to the “Sign In” endpoint (POST /v1/auth/token https://api.liaisonedu.com/reference...ecurity/signIn). You’ll need to include two headers:

  • Content-Type: "application/json"
  • x-api-key: "{your API key here}"

You’ll also need to include your credentials in the body of the request:

{
"UserName": "{your username here}"
,"Password": "{your password here}"
}

The response to this call will include a “Token” element. This “Token,” along with your API key, must be included in the headers of all subsequent calls to the CAS API. Your calls will all have these two headers:

  • x-api-key: "{your API key here}"
  • Authorization: “{your auth Token here}”

Retrieve Applicant Documents from the CAS API

In the CAS data model, each applicant has a profile. An applicant uses that profile to apply to specific programs offered by organizations (schools/colleges/universities) that are members of the CAS. We want to retrieve (a) the applicant’s profile and (b) application information for each specific program applied to. To accomplish that, we’ll first need to retrieve information about organizations and programs.

First, decide which CAS you want to retrieve data for. Each Application Form ID you were given when you gained access to the CAS API provides access to data for a specific CAS and admissions cycle year. You’ll include the Application Form ID for the CAS/cycle of interest in the URL of every subsequent call to the CAS API.

Next, you’ll want to retrieve a list of the organizations you have access to. Remembering to include your API key and authorization token as headers, make a call to the “Get Organizations” endpoint (GET /v1/applicationForms/:applicationFormID/organizations https://api.liaisonedu.com/reference...tOrganizations). The response to this call will include a list of all the organizations (schools/colleges/universities) within the chosen CAS that you have access to. In many cases, you’ll have access to just one organization – for example, in SOPHAS, you’ll likely just have access to your institution’s school of public health. In other CASs, however, your institution will likely have many organizations – for example, in GradCAS, your institution will likely have separate organizations for each college on campus. With this list, you can choose an individual organization to retrieve data from, or you can loop through all available organizations retrieving all available data. The “id” field from each organization in the list is the “organizationId” used in the URL strings of subsequent calls.

You’ll need to retrieve lists of the programs offered by each organization. Make a call to the “Get Organization Programs” endpoint (GET /v1/applicationForms/:applicationFormID/organizations/:organizationID/programs https://api.liaisonedu.com/reference...zationPrograms). The response to this call will include a list of all the programs offered by the chosen organization in the chosen CAS. Again, your chosen organization may offer one or many programs. You can choose an individual program to retrieve data from, or you can loop through all available programs retrieving all available data. The “id” field from each program in the list is the “programId” used in the URL string of subsequent calls.

For each program, you’ll want to include some details about the program with the application data. Retrieve program details by making a call to the “Get Program Info” endpoint (GET /v1/applicationForms/:applicationFormID/organizations/:organizationID/programs/:programId https://api.liaisonedu.com/reference...getProgramInfo. The response to this call will include details—such as campus, level, academic year, and delivery method—about the chosen program. Store these program details as an object so that you can include them with each application to the program.

Next, you’ll retrieve a list of all applications to each selected program offered by the chosen organization. Call the “Get Application Submissions by Program” endpoint (GET /v1/applicationForms/:applicationFormId/organizations/:organizationId/programs/:programId/applications https://api.liaisonedu.com/reference...sionsByProgram). The response to this call will be a list of all the applicants who have applied to the chosen program. You’ll want to loop through all of the applicants in the list and retrieve all application data available. The “applicationID” item will be used in the URL of a subsequent call to retrieve the full application data for individual applications.

The calls that return lists of applications can be augmented to change the way the lists are delivered. There are two optional URL string parameters that will change which applications are returned.

  • URL string parameters
    • “fromDate” – date format: “yyyy-mm-dd”
      • Use this URL string parameter to limit the applications returned to those that were updated on or after the date indicated.
    • “toDate” – date format: “yyyy-mm-dd”
      • Use this URL string parameter to limit the applications returned to those that were updated on or before the date indicated.

With the list of applications, we’re ready to retrieve application data. For each application in the list, make a call to the “Get Application by Organization and Program” endpoint (GET /v1/applicationForms/:applicationFormId/organizations/:organizationId/programs/:programId/applications/:applicationId https://api.liaisonedu.com/reference...tionAndProgram). The response to this call will include all available data related to the selected application.

The calls that return application details can be augmented to change the way the details are delivered. There are two optional URL string parameters and an optional header that will change the format of the data.  

  • URL string parameters
    •  “expand” – Available values: lookups, config, all
      • This URL string parameter allows you to change the form of the data returned. The default form includes numeric codes for all data points. For example, instead of returning the name of a country, the default might return a numeric identifier for that country. The “lookups” option will replace those numeric identifiers with values from the universal, CAS-wide lookup tables. The “config” option will replace those numeric identifiers with values from the user-controlled, custom elements (either at the CAS level or at the organization or program level). The “all” option will replace all numeric identifiers with values from the lookup tables or custom values. The “all” option is the most recommended, as it eliminates the need for you to translate any numeric identifiers.  

You might notice the other endpoints that allow you to retrieve application details—“Get Application” and “Get Application by Organization”—and wonder why they aren't recommended for use here. Those endpoints will retrieve all applications for a single applicant within the selected CAS and/or organization. Many applicants submit more than one application to a single CAS and/or organization. Using these endpoints would require parsing the “programsSelected” element to sift out the different applications included. Using the “Get Application by Organization and Program” endpoint guarantees that the application details returned will apply to a single application.

Now that we have collected all of the details from the applications we’re interested in, we need to search these details to find available documents. There are seven document types made available through the CAS API: college transcripts, official foreign transcript evaluations (WES, ECE), App Gateway applicant-uploaded documents (i.e., supplemental documents uploaded after application submission), letters of recommendation (CAS-level and program-level), and CAS application applicant-uploaded documents (CAS-level and program-level). The presence of any of these documents and the information needed to retrieve them is included in the application details. Loop through all applications collected and pull out information for each document type, storing this information in a new list of documents.

Here are the documents and their locations in the standard CAS API application details JSON structure:

  1. academicHistory/transcriptEntry/transcripts/
  2. academicHistory/transcriptEntry/vendorTranscriptEvaluations/
  3. appGateway/documentUpload/gatewayAttachments/
  4. programMaterials/evaluations/evaluationResponses/
  5. programMaterials/supplementalAttachments/
  6. supportingInfo/documents/attachments/
  7. supportingInfo/evaluations/evaluationResponses/

With this new list of documents, we’ll now proceed to identify which are ready for download. Some document types will show up in the application details before a document is available. For example, letters of recommendation get attached to an application when the request is made to the recommender and can exist before the letter is actually submitted. Each document type has slightly different metadata. Loop through each possible document and determine if it is ready for download. Store the information for the documents that are ready to download in a new list.

Now that we’ve prepared a list of documents ready for download, it’s time to retrieve them. Loop through the list of available documents and make a call to the “Get File” endpoint (GET /v1/applicationForms/{applicationFormId}/files/{fileId} https://api.liaisonedu.com/reference...s/File/getFile) for each one.

At this point, it’s necessary to start thinking about how the documents are going to be loaded to your local systems. The upload approach will determine the download approach. For example, if your local system prefers to upload PDFs as a zip file, you’ll want to put all PDFs downloaded from the CAS API in this session into a single directory so that you can zip it up when done downloading. If, on the other hand, your local system has a tool for uploading individual PDFs that you plan to make use of programmatically, then you’ll want to deliver each document to that tool as it’s downloaded. As a final example, your local systems might require manual PDF uploads, in which case, you’ll probably want to organize the downloaded PDFs in a way that’s convenient for the people who will be processing them.

You are the expert on your local systems and business processes. Use your understanding of how PDFs are loaded to local systems and the business need for transferring PDFs to local systems to craft an approach that meets your institution’s needs.

Sample Retrieving Documents Files

Use our CAS API Retrieve Documents file for assistance retrieving documents through the CAS API with Python 3.

  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Page type
    Topic
  2. Tags
    This page has no tags.