Admissions OpenAPI (REST JSON)
- Robert Lenk
- Nate Parsell
- Miranda Thomas
About Campus Cafe Admission Open API
Campus Cafe has an open application programming interface (API). With this API, software developers can create automated services to send to and retrieve data from Campus Cafe directly and automatically. For example, you may wish to exchange course registration information with your learning management system or send information about those who submit an admissions application in Campus Cafe to your marketing system.
Campus Cafe has built API integrations to send data to many systems such as Canvas, PayPal and MessageMedia. But if we haven’t, you may be able to use our Open API to build a connection.
Campus Cafe’s Open API adheres to REST syntax and semantics using JavaScript Object Notation (JSON) and Hypertext Transfer Protocol (HTTP) actions, such as POST, GET, DELETE, etc.
Admissions portal setup for API
Admissions Portal Configuration Screen Campus Cafe accepts inquiry and application data through an Open API. In this article, an inquiry is defined as a prospective student who has expressed interest in the given school and should be contacted to begin the process of applying. The API relies upon an admissions portal. Although the API does not provide a user interface, it is necessary to configure a portal to set the appropriate major codes available, entering semesters available, and defining required fields.
For information regarding setting up an admissions portal, refer to the admissions documentation.
Campus Cafe now supports Open API submission of Applications, creating an applicant in Campus Cafe. This capability must be configured within your organization's Campus Cafe database and cannot be activated from the Campus Cafe user interface. To request more information about this capability, please submit a support ticket to Campus Cafe's helpdesk.
Custom Control
Once the inquiry or application form has been created in admissions portal configuration, set the Custom Control ‘REST_INQ’ to the name of the default inquiry or application form created for use with the Open API.
Go to Admin > Custom Control
In the Search box enter REST_INQ
If control "REST_INQ" 1-1 already exists, click edit and enter the name of the rest API inquiry form exactly as it appears in the portal configuration. Example below is for a form titled restapi_inq.
Click Save
If control "REST_INQ" 1-1 does not exist, Enter REST_INQ in the Prog ID box
In the Seq # box enter 1
In the Context drop down, select Admissions
Click Add
In the Parameter Value 1 box enter the name of the admissions portal
Click Save
Configure Token
Campus Café provides a security feature to ensure that request data is being sent from a legitimate source. You will need to obtain a token from the system sending the lead information.
Navigate to Admin > Web App Config
Locate the parameter OPEN_API_TOKEN
Double click in the Value box and enter the token
Contact Campus Cafe to restart the server or wait overnight for a scheduled restart
Available Data Fields
Available data fields include the following.
Data Element | Field Name (form question must be mapped to this value) | Max Length | Accepted Values (where applicable, form answers must be sent over as accepted STParm values listed in Campus Cafe) |
|---|---|---|---|
Name (first) | firstName | 25 | alpha |
Name (middle) | middleName |
| alpha |
Name (last) | lastName | 50 | alpha |
Name (preferred) | preferredName |
|
|
emailAddress | 60 |
| |
Phone Number (mobile) | phoneNumber | 25 | Numbers only, no dashes or parentheses |
Phone Number (home) | homePhoneNumber | 25 | Numbers only, no dashes or parentheses |
Phone Number (work) | workPhoneNumber | 25 | Numbers only, no dashes or parentheses |
Date of Birth | dateOfBirth | 8 | Format YYYYMMDD |
Gender | gender | 1 | Use valid Campus Cafe Parameter Value Admin > STParm > Parameter Code SBSTSX |
In-house Ethnicity | ethnicityCode |
|
|
IPEDs Hispanic | ipedsHispanic |
|
|
IPEDs Ethnic | ipedsEthnic |
|
|
US Citizen | citizenStatus |
|
|
Citizenship Country | citizenCountry |
|
|
Visa Type | visa | 1 | Use valid Campus Cafe Parameter Value Admin > STParm > Parameter Code SBGDCD |
Social Security Number | socialSecurityNumber | 9 | Numbers only, no dashes or spaces |
Religion | religion |
|
|
Resident code | residenceCode |
|
|
Inquiry Source (marketing source) | inquirySource | 30 | Use Campus Café valid code associated with Source triggers set up in application |
Lead Url | leadUrl | None | See notes in section below. |
Major | majorCode | 10 | Use valid Campus Café Concentration Code from Majors |
Entering Semester | enteringSemester | 6 | Numbers only; Use valid Campus Cafe six-digit semester code Parameter Value Admin > STParm > Parameter Code SMDESC Semesters must also be added to the restapi Campus Cafe inquiry form/application in Adm Portal Configuration. |
Admissions Site | site | 2 | Numbers only; Use valid Campus Cafe Parameter Value Admin > STParm > Parameter Code SBCONO |
Admissions Billing Site | billingSite | 2 | Numbers only; Use valid Campus Cafe Parameter Value Admin > STParm > Parameter Code HOCONO |
Counselor | counselor | 3 | Use Campus Cafe valid code |
Texting Allowed | textAllowed | 1 | Use value Y for texting allowed. If allowed, send null value. |
Veteran Code | veteranCode | 1 | Use valid Campus Cafe Parameter Value Admin > STParm > Parameter Code SBVTCD |
Prior School Graduation Year | priorSchoolGradYear | 4 | Numbers only; Use four-digit year |
Prior School Graduation Month | priorSchoolGradMonth | 2 | Numbers only; Use values 1 to 12 |
Address (street 1) | street1 | 50 | alphanumeric |
Address (street 2) | street2 | 50 | alphanumeric |
Address (street 3) | street3 | 50 | alphanumeric |
Address (city) | city | 25 | alpha |
Address (state) | state | 2 | alpha - abbreviation only |
Address (Zip) | zipCode | 15 | numbers only |
Address (country) | country | 20 |
|
Student type | studentMode |
| Use valid Campus Cafe Parameter Value Admin > STParm > Parameter Code SBMODE |
Campus Café organization ID |
| 9 (exact) |
|
Gender Identity | genderIdentity | 30 | Use valid Campus Cafe Parameter Value Admin > STParm > Parameter Code GENDID |
Prounouns | pronoun | 30 | Use valid Campus Cafe Parameter Value Admin > STParm > Parameter Code PRNOUN |
Alternate ID | alternateID | 14 |
|
First Prior College Transcript Activity | collegeCeeb1 | 6 | Will map to Admissions Previously Attended College on Admissions Activity. Value entered must have CEEB code in Campus Cafe Schools table. To trigger activity, set up transcript collection and Portal Request Trigger using Portal Request Header: COLLEGE and Trigger TRANCOL01 |
Second Prior College Transcript Activity | collegeCeeb2 |
| To trigger activity, set up transcript collection and Portal Request Trigger using Portal Request Header: COLLEGE and Trigger TRANCOL02 |
Third Prior College Transcript Activity | collegeCeeb3 |
| To trigger activity, set up transcript collection and Portal Request Trigger using Portal Request Header: COLLEGE and Trigger TRANCOL03 |
Fourth Prior College Transcript Activity | collegeCeeb4 |
| To trigger activity, set up transcript collection and Portal Request Trigger using Portal Request Header: COLLEGE and Trigger TRANCOL04 |
Fifth Prior College Transcript Activity | collegeCeeb5 |
| To trigger activity, set up transcript collection and Portal Request Trigger using Portal Request Header: COLLEGE and Trigger TRANCOL05 |
High School Transcript Activity | hsCeeb1 |
| Will map to High School on Admissions Activity Value entered must have CEEB code in Campus Cafe Schools table. To trigger activity, set up transcript collection and Portal Request Trigger using Portal Request Header: HIGHSCHOOL and Trigger HSCOL01 |
Open API URL
Campus Café’s Open API inquiry/application POST URL has several adjustable components that need to be configured:
<Organization Code>: This is your 3-character school code that precedes "-web" in your Campus Cafe URL, like https://***-web.scansoftware.com/cafeweb/tl/login
<Portal Form Name>: This is the name of your application, set in the Admissions Portal Configuration screen. Any spaces in the name are to be replaced with "%20". If your portal name is "Undergraduate Application" this value would be Undergraduate%20Application in the Open API URL.
<Application or Inquiry>: If configuring the API as an Inquiry, this value should be set to Inquiry.
For an API as an Application, this should be set to Application. The Admissions Portal Config Mode needs to match this setting for the form being used:
<OPEN_API_TOKEN value>: This is the value set in Web App Configurations (Admin Menu -> Web
App) under the parameter OPEN_API_TOKEN and can be any word or random
string of characters.
This is the placement of those values within the OpenAPI URL:
https://<Organization Code>-web.scansoftware.com/cafeweb/openAPI/v1/inquiries?portalConfig=<Portal Form Name>&value=<Application or Inquiry>&token=<OPEN_API_TOKEN value>As an example, if the *** school had an Open API form named "Web Inquiry", with a token of "Bosco" it would look like this:
https://***-web.scansoftware.com/cafeweb/openAPI/v1/inquiries?portalConfig=Web%20Inquiry&value=Inquiry&token=Bosco
leadUrl Field (UTM)
Campus Cafe can import UTM (Urchin Tracking Module) by adding parameters to the URL string that is passed to Campus Café through the API.
Tip UTM codes are parsed out of the value found in the leadUrl data field. You must send a leadUrl parameter name in your request to have UTM codes parsed. The leadUrl parameter name is case sensitive, your name must match exactly as shown.
Below is an example of the URL string. In this case, we are passing utm_medium, utm_source, utm_campaign, utm_content and utm_term
https://www.yourschool.edu/my-utmcodes-ip?utm_medium=cpc&utm_source=google&utm_campaign=1053902585&utm_content=389973371894_c_1t1&utm_term=online%20masters%20in%20social%20entrepreneurship
If a parameter value of leadUrl is passed into the Open API form, Campus Café will look for an included tracking record in Admissions Portal Config with a trigger name of LEADURL. The record must be checked as included and be placed in a tab at a location to be included on the form. The tracking record will be added with a the entire leadUrl value stored in the tracking record’s comment box.
Additionally, the leadUrl will be parsed to find any parameters in the URL. Each parameter key will look for an included tracking record with a trigger equal to the parameter key. If the key begins with utm_ (case insensitive) that portion of the key will be removed. If a trigger is found, that tracking record will be added with that parameter’s value in the comment 1 field if it’s 75 characters or less. It will be added to the comment box if greater than 75 characters.
Since triggers can only be 10 characters long, the parameters in the leadUrl must only be 10 characters long (excluding the utm_). When creating your Template Request Triggers use Template Request Headers that have been defined as Request Type M - Multiple Values, so these values are not lost when prospects are sent to the holding table.
Reporting Tips
UTM parameter names are not case sensitive. When creating your UTM triggers use the utm names as received in the url, and only use the part of the name following utm_. For example, if you want to caputure the utm_medium parameter value, create a trigger with name of MEDIUM.
To use the Campus Cafe UTM report, create your tracking names using the Campus Cafe report name. For example, store the utm_medium parameter value into tracking UTMMEDIUM, to have these values show in the Campus Cafe UTM report.
Have your trigger generate the tracking. Following the above example your trigger MEDIUM would have the value UTMMEDIUM in the 'Trigger Name:' value of your trigger definition.
The base report Admissions Inquiry Applicant Listing-Extended will pull the UTM tracking records. The names of the activity tracking records must be as follows to appear on the report.
UTMCAMPAIGN
UTMCONTENT
UTMGCLID
UTMLEADURL
UTMMEDIUM
UTMSOURCE
UTMTERM
Web Form Data Format
Campus Café accepts these values transmitted via an HTTP POST action. In constructing an HTTP request, Campus Café will accept a single inquiry in the form of HTTP web form data. Below is a test web form, which can be used in a Hypertext Markup Language (HTML) document to deliver inquiry test data.
<form action="https://campusCafeURL/cafeweb/openAPI/v1/inquiries" method="POST">
<input type="hidden" name="portalConfig" value="WebInquiry" />
<input type="hidden" name="value" value="Inquiry" />
<input type="hidden" name="token" value="baseball" />
<input type="hidden" name="leadUrl" value="https://www.myschool.com/thisform?utm_medium=med&utm_source=google&utm_campgn=548&utm_conten=778&utm_term=online%20learning%20in%20social%20studies&gclid=KOFS_34_3423KI"/>
<label for="firstName">First Name:</label><input type="text"
name="firstName" id="firstName" /><br />
<label for="lastName">Last Name:</label><input type="text"
name="lastName" id="lastName" /><br />
<label for="emailAddress">Email Address:</label><input
type="text" name="emailAddress" id="emailAddress" /><br />
<label for="phoneNumber">Phone Number:</label><input type="tel"
name="phoneNumber" id="phoneNumber" /><br />
<label for="inquirySource">Inquiry Source:</label><input
type="text" name="inquirySource" id="inquirySource" />
<br />
<label for="majorCode">Major Code:</label><input type="text"
name="majorCode" id="majorCode" /><br />
<label for="enteringSemester">Entering Semester:</label><input type="text" name="enteringSemester" id="enteringSemester"/><br />
<label for="streetAddress1">Street Address 1:</label><input
type="text" name="streetAddress1" id="streetAddress1" />
<br />
<label for="streetAddress2">Street Address2:</label><input
type="text" name="streetAddress2" id="streetAddress2" />
<br />
<label for="streetAddress3">Street Address3:</label><input
type="text" name="streetAddress3" id="streetAddress3" />
<br />
<label for="city">City:</label><input type="text" name="city"
id="city" /><br />
<label for="state">State:</label><input type="text" name="state"
id="state" /><br />
<label for="zipCode">Zip Code:</label><input type="text"
name="zipCode" id="zipCode" /><br />
<label for="country">Country:</label><input type="text"
name="country" id="country" /><br />
<input type="submit" value="Submit"/>
</form>The common model for delivering web form data is via a set of name/value pairs within he HTTP request. Note that this form of inquiry POST requires that the “application/x-www-form-urlencoded” must be set within the request header Field Content-Type.
JSON Data Format
Campus Café will also accept one or more inquiry records in the form of a JSON array (note: even a single record must be sent in an array). JSON data is also sent to the Open API URL described above. When this means of data delivery is used, the HTTP Request Content-Type must be set to “application/json”. The data payload should be set in the HTTP request body as raw data.
Sample raw body value:
Open API Inquiries Returned Data
Campus Café provides a response to inquiry API requests that includes information regarding the inquiry data save results. The response returns a set of counts for the various results of each inquiry import attempt.
The field date provides a timestamp of the inquiry process response.
The field totalRecordCount returns the total number of records processed.
The field holdingRecordCount returns the total number of records that have been placed into the Campus Café Admissions Holding Table because one or more inquiries may have collided with existing inquiry records.
The field directlyUpdatedCount returns the total number of records that were located in Campus Café and updated with current inquiry information.
The field insertedRecordCount returns the total number of inquiry records saved to Campus Cafe.
The field duplicateRecordCount returns the total number of records identified as duplicate inquiry records.
The field unknownRecordCount returns the total number of records that cannot be identified during the inquiry process.
The field failedRecordCount returns the total number of records that have failed to be imported.
The field messages includes any error message information that may have been generated during the import process.
Retrieving Valid Codes
Campus Café’s Open API Inquiry portal expects the following data fields values to match internal values.
billingSite
counselor
enteringSemester
inquirySource
majorCode
site
veteranCode
To accommodate automated communication of legitimate values available use the following REST URL replacing the bolded characters with the appropriate values.
https://yourCampusCafeDomain/cafeweb/public/openAPI/v1/values?portalConfig={form name}&fieldName={field name}
For example to get a list of valid major codes for form named ExtServiceInq use url:
https://yourCampusCafeDomain/cafeweb/public/openAPI/v1/values?portalConfig=ExtServiceInq&fieldName=majorCode
Sample return value:
Using these service calls, the developer may validate incoming inquiry data to Campus Café to ensure correct values are selected.
