Skip to main content
Liaison

Working with the CAS API

This guide is for IT analysts assisting their institution's or association's CAS users in planning data integration with the CAS API.

Why Choose the CAS API?

The CAS API allows you to access applications and other data from any CAS. For example, if your institution participates in multiple CASs, you can use the CAS API to access any applications and related applicant files (e.g., transcripts, evaluations, etc.) from each of your CASs. It's also built on the same database that your applicants use to complete and submit their applications. This API is the closest you can get to the original source of applicant data. As applicants enter their information into the Applicant Portal, you can use the CAS API to call this data immediately.

From an integration standpoint, the CAS API endpoints are designed to simplify integration projects by your IT team, as they can more easily code against the API. For example, you can substitute a different ID into the HTTP request to retrieve applications from different CASs. Because the CAS API is REST-compliant, you can use almost any programming language to code against the API. Liaison provides a Java-based sample client for free; to download this sample, visit https://developer.liaisonedu.com. In addition, the CAS API is built on AWS Cloud, which enables the CAS API to adopt new technical and security standards quickly and efficiently. You can be confident that your data is secure and available when you need it.

Lastly, the CAS API has a flexible, role-based security model that can be adapted for both association and institution users.

You can use the CAS API as part of a broader integration project. For example, you can download all applications that have been updated in the last 24 hours and import them into your institution's admissions management platform. Or, you can download all applicants' documents, such as transcripts and recommendations, and archive them in your document management system.

Requesting a CAS API Account

To request a CAS API account, contact your Account Manager and provide the following information:

  • First name
  • Last name
  • Email address
  • Phone number

Liaison will then create an account for you with a default password, which you can change afterward. Visit https://developer.liaisonedu.com for more information. Since the password reset email is sent to the email address you provide, Liaison recommends using an email address account that you can check for these emails.

In addition, if your institution has multiple integration projects, then each CAS API account must have a unique email address. Creating separate API accounts for each integration application is a security best practice and is strongly recommended.

CAS API Security

The CAS API requires an OAuth 2-compliant identity token to call any endpoint. Typically the first API call your integration application makes to the CAS API is an identity token. These tokens are valid for one hour. Your integration application must refresh the identity token on an hourly basis; otherwise, your API calls will be refused with an "unauthorized" error message.

The OAuth 2 identity token also includes what data you can access. The CAS API currently supports two types of users:

  • Association user: this user can view any institution that participates in a CAS and all applicants and applications.
  • Organization user: this user can only view the applicants and applications for their specific institution.

API Keys and Rate Limiting

The CAS API uses API keys as an additional security measure and enforces rate limiting. API keys are created for individual users, not CAS API accounts. For example, you can have one API key and multiple CAS API accounts, each corresponding to separate integration applications.

Rate limiting caps the number of API calls within a given period (e.g., one API request per second). This ensures that all users can access the CAS API. If the rate limit is exceeded, a special error code is sent back to you. Additionally, the rate limit restricts the number of calls per user, not by CAS API accounts. For example, if the rate limit is one API request per second and you have three CAS API accounts, and you make an API request for all three CAS API accounts at once, then only one of the API requests will process and the others will receive a special error code.

To view the current rate limit values, visit https://developer.liaisonedu.com.

Lookups and the GET Application API

When using the CAS API to call data, many of the API endpoints are associated with numeric lookup identifiers (i.e., "lookups"). In the example below, the major (i.e., "majorId") is associated with a lookup ID, "4057."

"degrees": [
    {
        "id": 2505385,
        "typeId": 5795,
        "monthId": 8,
        "month": "5",
        "yearId": 25,
        "year": "2007",
        "majorId": 4057,
        "minorId": 6135,
        "degreeStatusId": 431,
        "collegeAttendedId": 4201656,
        "createdDate": "2018-10-02 15:50:18",
        "updatedDate": "2018-10-02 15:50:18"
    },

In order to translate this lookup ID into text, you must call a one-time, separate API endpoint through the GET Application API. This API returns a response which is typically cached as to avoid extra calls and increase the API performance. Within this response, you can search for the lookup ID to learn the associated text, as in the example below:

    {
        "id": 4057,
        "code": "Anthropology",
        "value": "Anthropology"
    },

In order to translate all lookup IDs in the GET Application response, you need to call three separate APIs. Review the GET Application Response and Mapping API Response document to learn which Mapping API to use for each lookup type.

How the CAS API Scopes Data

The CAS API scopes data in two ways:

  • By CAS and institution: the CAS API can retrieve data specific to your CAS, institution, and program. For example, CASs can process different test scores (e.g., ADEA AADSAS and the DAT test, PharmCAS and the PCAT test, etc.) and programs can have different requirements in the Program Materials section (e.g., questions, documents, etc.).
  • By API endpoint: you can use endpoints to retrieve specific data and build on a JSON-hierarchy to narrow your results. For example:
    • GET /applicationForms/{applicationFormId}/applications/{applicationId}
      • This endpoint retrieves an application that was submitted to any program at any institution within a single CAS.
    • GET /applicationForms/{applicationFormId}/organizations/{organizationId}/applications/{applicationId}
      • This endpoint retrieves an application that was submitted to any program at a single institution within a single CAS.
    • GET /applicationForms/{applicationFormId}/organizations/{organizationId}/programs/{programId}/applications/{applicationId}
      • This endpoint retrieves an application that was submitted to a single program at a single institution within a single CAS.

You can adapt the URL structure to access data from different CASs and cycles. Simply change the numeric IDs in the URL HTTP request for a different CAS or cycle. In the example below, the {applicationFormId} field matches a numeric ID that represents a CAS and cycle and the {organizationId} field matches a numeric ID that represents an institution. You can use this CAS API call format to return a list of application IDs:

GET /applicationForms/{applicationFormId}/organizations/{organizationId}/applications

Supported Integration Patterns

You can schedule the CAS API in three ways:

  1. On-demand data download, available immediately: this is the most common integration pattern, also known as the "pull" pattern. When using this pattern, your API client requests data from the CAS API, which then sends data back to your API client. You can use this pattern to download an application.
  2. On-demand data download, scheduled: when using this pattern, your API client uploads data to the CAS API, which responds with a success or failure message. You can use this pattern to upload new information about a program.
  3. Event-driven data push, scheduled: also known as a "REST Hook." When using this pattern, your API client is subscribed to an event of your choosing: for example, when an applicant submits their application or selects a program. Once the event occurs, the CAS API automatically pushes data to the destination you configured in the subscription request. You can use this pattern when you want to be notified that the specified event occurred. You can also configure this pattern to trigger another process. For example, once an applicant selects your program, you can trigger a targeted marketing campaign to the applicant through your CRM system.

CAS API Technical Standards

Review the following technical standards that the CAS API adheres to:

  • AWS Cloud: the CAS API is deployed on the AWS Cloud and leverages many AWS technologies for availability, security, and monitoring. The CAS API can then adopt new IT-centric capabilities (e.g., security standards and protocols) quickly and efficiently. Some of the specific AWS services used by the CAS API include:
    • AWS Cognito for user management and authentication (OAuth2 tokens). This technology can support millions of individual users. It also provides its own portfolio of publicly callable REST APIs, which will be used in the future to support a self-service portal for the CAS API.
    • AWS API Gateway for high availability and API key management.
    • AWS ElastiCache for Redis for API rate limiting and X-RateLimit-* header support.
    • AWS Lambda for custom authorization handling.
    • AWS CloudWatch for monitoring.
  • Highly Secure: the CAS API is highly secure. All CAS API endpoints are protected by API keys and OAuth2 identity tokens, which are both managed using AWS Cloud technologies. API keys are generated for each user and must be passed with all API requests. OAuth2 identify tokens are also required to call the CAS API endpoints. These tokens are generated via a separate API call and expire after one hour. Additionally, the CAS API provides special endpoints that allow you to change or reset your password.
  • REST-based API: the CAS API is a REST-based API, which is the most common type of API for system integrations today. The technical and development resources working on your integration project is likely to be familiar with REST-based client programming.
  • Hierarchical JSON format: the CAS API renders all data in hierarchical JSON format. JSON is the most popular data format, as compared to XML, CSV, or other formats. This gives you the most flexibility for mapping and importing data into your SIS or other destination systems.
  • GZIP Compression: the CAS API supports GZIP compression for large payloads. This is particularly useful for application downloads, where the payload size can exceed several megabytes.
  • Monitoring: the CAS API is monitored at multiple levels. CAS API-level system monitoring is handled in Liaison's enterprise New Relic monitoring system, using custom monitors that invoke actual APIs on a regular basis to ensure availability. Additionally, user-specific identifiers are injected into HTTP headers, which allows Liaison to monitor individual use of the API endpoints.
  • Speed: the CAS API is fast. Database queries used by the CAS API have been designed and tuned for best possible response performance. Additionally, all read-only API requests use a replica copy of the CAS database tuned for optimal read performance. Finally, all API requests are multi-threaded to handle concurrent spikes and anticipated future growth.

Testing the CAS API

You can test the CAS API using one of the following API client tools or sample codes from https://developer.liaisonedu.com. You must have an active CAS API account first before testing.

  • Postman is a free API testing tool; click here to download it. For steps on how to use Postman to generate an identity token and call an API endpoint, refer to Postman's Learning Center.
  • cURL is a free command-line tool for transferring data using various protocols and is available for Windows and Mac OS. To download and learn more about cURL, click here. If you have access to a bash shell, you can also try #curl --help.

We also offer screenshots and sample code for using Postman and cURL, which you can download here. Note that the screenshots included may differ from your view. If you have any questions about using Postman and cURL, contact those companies directly.

Resources

The combination of our CAS API features gives you the power to automate the moving of data out of our systems in preparation for importing to your other on-campus systems using modern standards, modern conventions, and powerful tools that simplify the process for your team. However, we realize data integration can seem overwhelming, so we’re always happy to support you through the process. As you explore your data integration options, take note of the following resources:

  • Was this article helpful?