Retrieving Data via the CAS API

Last updated
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 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 Credentials

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 IDs

Additionally, you’ll have a list of ID numbers (called “Instance IDs,” “Form IDs,” or “Application Form IDs”) which represent the data sets that you have access to. 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 Data 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 and 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.
- “includeNulls” – Available values: true, false
  - This URL string parameter allows you to force the response to include the same number of elements every time. The default setting of “false” will hide elements for which the selected applicant has no data. For example, if an applicant didn’t enter their middle name, the default payload for that applicant wouldn’t include a middle name element. Setting “includeNulls=true” will return all elements in the data model whether or not the selected applicant has data for each element. This setting is useful because it will guarantee a consistent structure to the application data. That will help when parsing the JSON structure or if you are returning data in a flat file format.
Headers
- “Accept” – “text/csv”
  - This header allows you to cause the application details payload to be returned as a flat file in CSV format. The default setting returns the payload as a JSON structure. This setting is useful if you intend to upload a CSV to your local system.
- “X-API-CSV-COLUMN-SEPARATOR” – Available values: COMMA, TAB, PIPE, SEMICOLON, Default value: COMMA
  - This header is to be used only in combination with the “Accept:text/csv” header. This parameter allows you to define the delimiter you want to use in your flat file. While the default delimiter is a comma, you can choose tab, pipe, or semicolon delimiters. This is a handy feature that can accommodate the ingestion requirements of a variety of on-campus systems.

You might notice the other endpoints that allow you to retrieve application details—“Get Application” and “Get Application by Organization”—and wonder why we don’t recommend using those 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.

Once you’ve retrieved the application data for a single application, you’re ready to load it to your local systems. The power of the JSON payload is that you can programmatically transfer complex data objects from our database to yours. At this point, there are several possible approaches.

One at a time, insert each raw application in its entirety into your database (to be transformed and loaded to the appropriate tables after the initial insert).
One at a time, parse each raw application for desired data elements and transform them to meet the requirements of your database, then load the pared-down and transformed application data to the relevant tables.
Retrieve the details for all applications and store them together in an object, then insert that object with all the raw application details to your database (to be transformed and loaded to the appropriate tables after the initial insert).
As you retrieve details for each application, parse the raw application for desired data elements and transform them to meet the requirements of your database. Then, group these pared down and transformed applications into an object and load that object to the relevant tables.

You are the expert in the nuances of loading data to your local databases, so you will know best which approach fits your situation. You will also know best how exactly to carry that out.

Sample Retrieving Data Files

Use our Sample Retrieve Data as JSON PY file for assistance retrieving data through the CAS API with Python 3.