Creating Data and Document Subscriptions
This article details the subscription configuration that works with the standard Slate Source Formats.
Before you can begin working with the CAS API, your CAS API account needs to be created at least one program must be active.
HTTPS Tools
You may use any tool for interacting with HTTPS endpoints to create your subscription. Popular options include:
- cURL: a command-line tool for interacting with HTTPS endpoints available out of the box in most operating systems.
- Coding languages: versatile and powerful languages with a variety of tools for interacting with HTTPS endpoints, such as Python, Java, Perl, C#, and JavaScript.
- Postman: a graphic user interface for interacting with HTTPS endpoints.
Review the API Reference Guide for a list of available endpoints and full API documentation.
Creating a CAS API Subscription
If you're using Postman, review the Using Postman to Setup the CAS API Slate Integration information. To create a CAS API Subscription:
- Select the target environment:
- Prelaunch root URL: https://api.prelaunch.liaisonedu.com
- Production root URL: https://api.liaisonedu.com
- Call the Authorization Token by:
- Sending the POST /v1/auth/token endpoint.
- Sending the username and password in the body of the request.
- Sending the API key as a header with key “x-api-key".
Once you generate the Authorization Token, it remains valid for an hour. After an hour, you will receive an error message indicating that you need to re-run the POST /v1/auth/token endpoint to generate a new token.
- Retrieve the identifiers. These will be provided when your CAS API account is created and can also be retrieved using the GET /v1/accounts/info endpoint, and are used in the URL string parameters:
- Application Form ID: identifies the CAS/cycle combination of interest (e.g., “CSDCAS 23-24” or “BusinessCAS 24-25”).
- Organization ID: identifies the institution within a CAS.
- Create your subscription(s) using the samples below or create your own based on the available business events.
Notes and Best Practices
- You need to subscribe to each CAS separately. If you want to integrate three different applications from CAS to Slate, then you must create three CAS API subscriptions.
- The sample subscriptions are set at the organization scope, which means that any time an event occurs on any application to any program at your organization, a payload will be delivered to the Slate SFTP by the CAS API. Subscribing at the organization scope means that you can freely add, open, and close CAS programs, knowing that the application data and documents will be delivered to Slate.
- When you post a subscription through the CAS API, the API sends an empty, auto-generated test file to Slate’s SFTP before the subscription is created to confirm that the destination is correctly set up (i.e., a health check). This enhancement prevents the API from attempting to access an unreachable or misconfigured destination and alerts you to errors in the destination setup. The test file name replaces any integer-based tokens with 0 and string-based tokens with TEST. For example:
- Path template: CAS_pers_<casApplicantId>__<documentSubType>__<fileId>!<deliveredDate>.pdf
- Test file: CAS_pers_0__TEST__0!2022-10-04_16:00:00.pdf
- If you use one Source Format in Slate to import applicant data at multiple stages, be aware that Slate sweeps the SFTP for new files to import every 15 minutes. As a result, if the CAS API sends multiple files to the SFTP between Slate's sweeps, files may periodically be imported out of order. To account for this, we recommend that you do one of the following:
- Change the SFTP Path Template in your subscription to be the same across all data subscription events. Then, if multiple files are sent to the Slate SFTP between pickups, the most recent file sent from the CAS API will replace the previous file, ensuring that the most up-to-date data is imported. You can use the following path template for data business events (note that you do not need to change document subscription events):
[ENTER CAS NAME HERE]_<instanceId>_<organizationId>_<programId>_<applicationId>_<casApplicantId>.csv - Create a query to identify records that may have been imported out of order. For example, you can search for applications with a submitted date that also have an In Progress application status. Once you identify the applicant record, then you can search for the submitted file in the Source Format and retroactively refresh that file.
- Change the SFTP Path Template in your subscription to be the same across all data subscription events. Then, if multiple files are sent to the Slate SFTP between pickups, the most recent file sent from the CAS API will replace the previous file, ensuring that the most up-to-date data is imported. You can use the following path template for data business events (note that you do not need to change document subscription events):
- If you use multiple Source Formats in Slate to import applicant data at multiple stages, the SFTP Path Template must direct the files to the appropriate Source Format. Here are some examples:
- For in progress applications being loaded to the In Progress Applications Source Format, add “inprogress-” before the CAS Name. [inprogress-ENTER CAS NAME HERE]_<instanceId>_<organizationId>_<programId>_<applicationId>_<casApplicantId>.csv. An example of the corresponding Import Path/Mask would be: liaison/inprogress-GradCAS*.csv
- For submitted applications being loaded to the Applications Source Format, add “submitted-” before the CAS Name. [submitted-ENTER CAS NAME HERE]_<instanceId>_<organizationId>_<programId>_<applicationId>_<casApplicantId>.csv. An example of the corresponding Import Path/Mask would be: liaison/submitted-GradCAS*.csv
In Progress Data Subscription by Organization
This subscription delivers application data at the point of program selection. This is when the applicant first selects one of your institution's programs on the Program Selection page in the CAS Applicant Portal.
Note that a CAS can allow full, partial, or no view of In Progress applications. The CAS to Slate integration only works if the CAS you're interested in allows you to view In Progress applications. Consult the documentation for your CAS to determine if there are any visibility restrictions on In Progress applications.
The Slate standard In Progress Applications Source Format will create person records for each In Progress application delivered. If you want unsubmitted applications to be created, you may want to use the standard Applications Source Format.
Your request should be as follows. Remember to replace our [SAMPLE TEXT APPEARING IN BRACKETS] with the appropriate values.
POST
/v1/applicationForms/[APPLICATIONFORMID]/organizations/[ORGANIZATIONID]/subscriptions
Authorization: [A VALID AUTHORIZATION TOKEN RETRIEVED FROM POST /v1/auth/token]
Content-Type: application/json
x-api-key: [YOUR CAS API KEY]
Host: [THE APPROPRIATE CAS API ROOT URL: PRODUCTION – api.liaisonedu.com, PRELAUNCH – api.prelaunch.liaisonedu.com]
{
"notificationEmailAddress": "[ENTER A MONITORED EMAIL ADDRESS TO RECEIVE NOTIFICATIONS ABOUT YOUR SUBSCRIPTIONS]",
"subscriptionDetails": [
{
"destinationType": "SFTP",
"event": "application.program.selected",
"responseLevel": "program",
"responseType": "fullResponse",
"responseOptions": "expand=all,includeNulls=true,contentType=text/csv,columnSeparator=COMMA,csvHeaderTruncationSize=4,csvShortName=question",
"apiVersion": "v2",
"sftpDestination": {
"sftpHost": "ft.technolutions.net",
"sftpPort": 22,
"sftpUser": "[ENTER SFTP USERNAME HERE]",
"sftpPassword": "[ENTER SFTP PASSWORD HERE]",
"sftpBaseDirectory": "/incoming/liaison/",
"sftpPathTemplate": "[ENTER CAS NAME HERE]_<instanceId>_<organizationId>_<programId>_<applicationId>_<casApplicantId>.csv"
}
}
]
}
Submitted Data Subscription by Organization
This subscription delivers application data at the point of submission. This is when the applicant clicks the Submit button, pays the application fee, and all submission requirements (e.g., questions, document uploads, etc.) are complete.
Review the Common Business Events for additional business events you can subscribe to.
Your request should be as follows. Remember to replace our [SAMPLE TEXT APPEARING IN BRACKETS] with the appropriate values.
POST
/v1/applicationForms/[APPLICATIONFORMID]/organizations/[ORGANIZATIONID]/subscriptions
Authorization: [A VALID AUTHORIZATION TOKEN RETRIEVED FROM POST /v1/auth/token]
Content-Type: application/json
x-api-key: [YOUR CAS API KEY]
Host: [THE APPROPRIATE CAS API ROOT URL: PRODUCTION – api.liaisonedu.com, PRELAUNCH – api.prelaunch.liaisonedu.com]
{
"notificationEmailAddress": "[ENTER A MONITORED EMAIL ADDRESS TO RECEIVE NOTIFICATIONS ABOUT YOUR SUBSCRIPTIONS]",
"subscriptionDetails": [
{
"destinationType": "SFTP",
"event": "application.program.received",
"responseLevel": "program",
"responseType": "fullResponse",
"responseOptions": "expand=all,includeNulls=true,contentType=text/csv,columnSeparator=COMMA,csvHeaderTruncationSize=4,csvShortName=question",
"apiVersion": "v2",
"sftpDestination": {
"sftpHost": "ft.technolutions.net",
"sftpPort": 22,
"sftpUser": "[ENTER SFTP USERNAME HERE]",
"sftpPassword": "[ENTER SFTP PASSWORD HERE]",
"sftpBaseDirectory": "/incoming/liaison/",
"sftpPathTemplate": "[ENTER CAS NAME HERE]_<instanceId>_<organizationId>_<programId>_<applicationId>_<casApplicantId>.csv"
}
}
]
}
Updated Data Subscription by Organization
This subscription delivers application data in response to updates made by applicants. Specifying a DataHold setting allows you to control when update events will trigger delivery of application data. The most common application update use cases are listed on the Data Hold page.
Application Update Events
Almost every action an applicant takes on the application is considered an update. Each CAS has its own configuration for which update events will trigger delivery by the CAS API, so you may observe differences in behaviors across different CASs. Additionally, update files are held for approximately 10 minutes before being delivered. Here are examples of actions that trigger the application.update event:
- An applicant enters or changes responses in a section of the application and clicks Save and Continue.
- An official test score is matched to an application.
When to Capture Application Updates and How to Load Them
The CAS API's DataHold feature makes it possible to set up your CAS API subscription to only deliver files for applications in certain statuses. The application statuses specified in a CAS API subscription will be excluded from delivery. For example, a CAS API subscription with "dataHold":"InProgress" will not deliver files for applications in the In Progress application status.
It is a best practice to only deliver data that you intend to use in some concrete business process. To properly configure your CAS API subscription for updates, it is important to start by thinking through the business process you intend to support. Ask yourself:
- What am I trying to do with application data?
- What kinds of updates do I need to capture to do that?
For example, if you want applicants to maintain their contact information in the CAS instead of in your system, you might want to receive all updates from CAS after application submission so you always have the latest contact information. Our Application Locking Behavior guide provides more information on what an applicant may change after submitting their application.
Once you've identified what you intend to do with application update data, you'll need to determine which Source Format to use to load that data to Slate.
- The All CAS by Liaison - Applications standard Source Format will create and update Slate application records. If your business process involves updating existing applications, then use this Source Format.
- The All CAS by Liaison - In Progress Applications standard Source Format will create and update person-scoped Slate "Inquiry" records. If your business process involves keeping track of updates on your Slate Inquiries to tailor your communications, then use this Source Format.
Your request should be as follows. Remember to replace our [SAMPLE TEXT APPEARING IN BRACKETS] with the appropriate values.
POST
/v1/applicationForms/[APPLICATIONFORMID]/organizations/[ORGANIZATIONID]/subscriptions
Authorization: [A VALID AUTHORIZATION TOKEN RETRIEVED FROM POST /v1/auth/token]
Content-Type: application/json
x-api-key: [YOUR CAS API KEY]
Host: [THE APPROPRIATE CAS API ROOT URL: PRODUCTION – api.liaisonedu.com, PRELAUNCH – api.prelaunch.liaisonedu.com]
{
"notificationEmailAddress": "[ENTER A MONITORED EMAIL ADDRESS TO RECEIVE NOTIFICATIONS ABOUT YOUR SUBSCRIPTIONS]",
"subscriptionDetails": [
{
"destinationType": "SFTP",
"event": "application.updated",
"dataHold": "[ENTER APPLICATION STATUSES TO EXCLUDE FROM DELIVERY - SEE DATA HOLD PAGE]",
"responseLevel": "program",
"responseType": "fullResponse",
"responseOptions": "expand=all,includeNulls=true,contentType=text/csv,columnSeparator=COMMA,csvHeaderTruncationSize=4,csvShortName=question",
"apiVersion": "v2",
"sftpDestination": {
"sftpHost": "ft.technolutions.net",
"sftpPort": 22,
"sftpUser": "[ENTER SFTP USERNAME HERE]",
"sftpPassword": "[ENTER SFTP PASSWORD HERE]",
"sftpBaseDirectory": "/incoming/liaison/",
"sftpPathTemplate": "[ENTER CAS NAME HERE]_<instanceId>_<organizationId>_<programId>_<applicationId>_<casApplicantId>.csv"
}
}
]
}
Document Subscription by Organization
This subscription delivers all application documents present at the time of submission and any documents received after submission as they arrive in the CAS. For a description of the documents delivered with each document business event, review the Common Business Events.
By default, the code below will return the standard Full Application PDF along with the other applicable documents. An alternate version of this PDF that removes race and ethnicity information is also available. To have this version delivered instead, add "pdfType=reviewer" to the reponseOptions for the appropriate business event: "responseOptions": "contentType=application/pdf,pdfType=reviewer". Note that this alternative is available only for the Full Application PDF.
Specifying a DataHold setting will allow you to control when events will trigger the delivery of data. The most common DataHold for documents is "dataHold":"InProgress", which prevents documents from being delivered for applications in the In Progress application status. Review the Common Data Holds for additional options.
Your request should be as follows. Remember to replace our [SAMPLE TEXT APPEARING IN BRACKETS] with the appropriate values.
POST
/v1/applicationForms/[APPLICATIONFORMID]/organizations/[ORGANIZATIONID]/subscriptions
Authorization: [A VALID AUTHORIZATION TOKEN RETRIEVED FROM POST /v1/auth/token]
Content-Type: application/json
x-api-key: [YOUR CAS API KEY]
Host: [THE APPROPRIATE CAS API ROOT URL: PRODUCTION – api.liaisonedu.com, PRELAUNCH – api.prelaunch.liaisonedu.com]
{
"notificationEmailAddress": "[ENTER A MONITORED EMAIL ADDRESS TO RECEIVE NOTIFICATIONS ABOUT YOUR SUBSCRIPTIONS]",
"subscriptionDetails": [
{
"destinationType": "SFTP",
"event": "application.program.received",
"responseLevel": "program",
"responseType": "fullResponse",
"responseOptions": "contentType=application/pdf",
"apiVersion": "v1",
"sftpDestination": {
"sftpHost": "ft.technolutions.net",
"sftpPort": 22,
"sftpUser": "[ENTER SFTP USERNAME HERE]",
"sftpPassword": "[ENTER SFTP PASSWORD HERE]",
"sftpBaseDirectory": "/incoming/liaison/",
"sftpPathTemplate": "[ENTER CAS NAME HERE]_app_<casApplicantId>_<programId>_fullAppPDF__<applicationId>!<deliveredDate>.pdf"
}
},
{
"destinationType": "SFTP",
"event": "file.attachment.updated",
"responseLevel": "organization",
"responseType": "fullResponse",
"dataHold": "InProgress",
"sftpDestination": {
"sftpHost": "ft.technolutions.net",
"sftpPort": 22,
"sftpUser": "[ENTER SFTP USERNAME HERE]",
"sftpPassword": "[ENTER SFTP PASSWORD HERE]",
"sftpBaseDirectory": "/incoming/liaison/",
"sftpPathTemplate": "[ENTER CAS NAME HERE]_pers_<casApplicantId>__<documentSubType>__<fileId>!<deliveredDate>.pdf"
}
},
{
"destinationType": "SFTP",
"event": "file.supplementalAttachment.updated",
"responseLevel": "program",
"responseType": "fullResponse",
"dataHold": "InProgress",
"sftpDestination": {
"sftpHost": "ft.technolutions.net",
"sftpPort": 22,
"sftpUser": "[ENTER SFTP USERNAME HERE]",
"sftpPassword": "[ENTER SFTP PASSWORD HERE]",
"sftpBaseDirectory": "/incoming/liaison/",
"sftpPathTemplate": "[ENTER CAS NAME HERE]_app_<casApplicantId>_<programId>_<documentSubType>__<fileId>!<deliveredDate>.pdf"
}
},
{
"destinationType": "SFTP",
"event": "file.evaluation.updated",
"responseLevel": "program",
"responseType": "fullResponse",
"dataHold": "InProgress",
"sftpDestination": {
"sftpHost": "ft.technolutions.net",
"sftpPort": 22,
"sftpUser": "[ENTER SFTP USERNAME HERE]",
"sftpPassword": "[ENTER SFTP PASSWORD HERE]",
"sftpBaseDirectory": "/incoming/liaison/",
"sftpPathTemplate": "[ENTER CAS NAME HERE]_app_<casApplicantId>_<programId>_<docType>__<fileId>!<deliveredDate>.pdf"
}
},
{
"destinationType": "SFTP",
"event": "file.transcript.updated",
"responseLevel": "organization",
"responseType": "fullResponse",
"dataHold": "InProgress",
"sftpDestination": {
"sftpHost": "ft.technolutions.net",
"sftpPort": 22,
"sftpUser": "[ENTER SFTP USERNAME HERE]",
"sftpPassword": "[ENTER SFTP PASSWORD HERE]",
"sftpBaseDirectory": "/incoming/liaison/",
"sftpPathTemplate": "[ENTER CAS NAME HERE]_pers_<casApplicantId>__<docType><transcriptType>_<collegeAttendedId>_<fileId>!<deliveredDate>.pdf"
}
},
{
"destinationType": "SFTP",
"event": "file.vendorTranscriptEval.updated",
"responseLevel": "organization",
"responseType": "fullResponse",
"dataHold": "InProgress",
"sftpDestination": {
"sftpHost": "ft.technolutions.net",
"sftpPort": 22,
"sftpUser": "[ENTER SFTP USERNAME HERE]",
"sftpPassword": "[ENTER SFTP PASSWORD HERE]",
"sftpBaseDirectory": "/incoming/liaison/",
"sftpPathTemplate": "[ENTER CAS NAME HERE]_pers_<casApplicantId>__<docType>_<collegeAttendedId>_<fileId>!<deliveredDate>.pdf"
}
}
]
}
Coursework Subscription by Organization
This subscription delivers application coursework data at the point of verification.
The All CAS by Liaison - Coursework standard Source Format will create course records for each course entered by the applicant in the CAS application.
Your request should be as follows. Remember to replace our [SAMPLE TEXT APPEARING IN BRACKETS] with the appropriate values.
POST /v1/applicationForms/[APPLICATIONFORMID]/organizations/[ORGANIZATIONID]/subscriptions
Authorization: [A VALID AUTHORIZATION TOKEN RETRIEVED FROM POST /v1/auth/token]
Content-Type: application/json
x-api-key: [YOUR CAS API KEY]
Host: [THE APPROPRIATE CAS API ROOT URL: PRODUCTION – api.liaisonedu.com, PRELAUNCH – api.prelaunch.liaisonedu.com]
{
"notificationEmailAddress": "[ENTER A MONITORED EMAIL ADDRESS TO RECEIVE NOTIFICATIONS ABOUT YOUR SUBSCRIPTIONS]",
"subscriptionDetails": [
{
"destinationType": "SFTP",
"event": "application.program.verified",
"responseLevel": "program",
"responseType": "fullResponse",
"responseOptions": "expand=all",
"apiVersion": "v2",
"sftpDestination": {
"sftpHost": "ft.technolutions.net",
"sftpPort": 22,
"sftpUser": "[ENTER SFTP USERNAME HERE]",
"sftpPassword": "[ENTER SFTP PASSWORD HERE]",
"sftpBaseDirectory": "/incoming/liaison/",
"sftpPathTemplate": "[ENTER CAS NAME HERE]_casapi-coursework_<instanceId>_<organizationId>_<programId>_<applicationId>_<casApplicantId>!<deliveredDate>.json"
}
}
]
}