Skip to main content
Liaison

How the CAS API Works

  1. Last updated
  2. Save as PDF

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.

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:

  1. Back to top
  • Was this article helpful?

Recommended articles

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