Open API

Campus Café Open API

Campus Café exposes an open application programming interface (API). With this API, software developers can create automated services to send to and retrieve data from Campus Café directly. Campus Café’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 ScreenCampus Café accepts inquiry and application data through an Open API. In this document, 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, submit a support ticket through Campus Cafe's support portal.

Custom Control

Once the portal configuration has been completed, set the Custom Control ‘REST_INQ’ to the name of the default REST portal configuration.

1. Navigate to Admin > Custom Control Maintenance
2. In the Search box enter "REST_INQ"
3. 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.
4. Click Save
5. If control "REST_INQ" 1-1 does not exist, Enter REST_INQ in the Prog ID box
6. In the Seq # box enter 1
7. In the Context drop down, select Admissions
   
8. Click Add
9. In the Parameter Value 1 box enter the name of the admissions portal
10. 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.

1. Navigate to Admin > Web App Config
2. Locate the parameter OPEN_API_TOKEN 
3. Double click in the Value box and enter the token
4. Contact Campus Cafe to restart the server or wait overnight for a scheduled restart

Available Inquiry Data Fields

The values collected for an inquiry include the following:

• First Name
  1. Field name firstName 
  2. Max length 25 characters
• Last Name
  1. Field name lastName
  2. Max length 50 characters
• Email Address
  1. Field name emailAddress 
  2. Max length 60 characters
• Phone Number (mobile)
  1. Field name: phoneNumber 
  2. Max length 25 characters
• Home Phone Number
  1. Field name: homePhoneNumber 
  2. Max length 25 characters
• Work Phone Number
  1. Field name: workPhoneNumber 
  2. Max length 25 characters
• Inquiry Source (marketing source)
  1. Field name: inquirySource 
  2. Max length 10 characters
     • use Campus Café valid code
• Lead Url
  1. Field name: leadUrl
  2. Max length none
  3. See next section for more information.
• Major
  1. Field name: majorCode 
  2. Max length 10 characters
     • use Campus Café valid code
• Entering Semester
  1. Field name: enteringSemester
  2. Max length 6 characters, digits only
     • use Campus Café valid code
• Admissions Site
  1. Field name: site
  2. Max length 2 characters , digits only
     • use Campus Café valid code
• Admissions Billing Site
  1. Field name: billingSite
  2. Max length 2 characters , digits only
     • use Campus Café valid code
• Counselor
  1. Field name: counselor
  2. Max length 3 characters
     • use Campus Café valid code
• Texting Allowed
  1. Field name: textAllowed
  2. Max length 1 characters
     • Use value Y for texting allowed
• Veteran Code
  1. Field name: veteranCode
  2. Max length 1 characters , digits only
     • use Campus Café valid code
• Prior School Graduation Year
  1. Field name: priorSchoolGradYear
  2. Max length 4 characters , digits only
     • use 4 digit year
• Prior School Graduation Month
  1. Field name: priorSchoolGradMonth
  2. Max length 2 characters , digits only
     • Use values 1 through 12
• Address 
  • Street Address Line 1
    • Field name: streetAddress1
    • Max length: 50 characters
  • Street Address Line 2
    • Field name: streetAddress2
    • Max length 50 characters
  • Street Address Line 3
    • Field name streetAddress3 
    • Max length 50 characters
  • City
    • Field name: city 
    • Max length 25 characters
  • State
    • Field name state 
    • Max length 2 characters
  • Zip Code
    • Field name zipCode 
    • Max length 15 characters
  • Country
    • Field name country
    • Max length 20 characters
• Student type 
  • Field Name studentMode
• Middle name
  • Field Name middleName
• Preferred name
  • Field Name preferredName
•  Social Security Number
  • Field Name socialSecurityNumber
• Campus Café organization ID (9 numeric) 
  • Field Name 
• Date Of Birth
  • Field Name dateOfBirth
• Gender
  • Field Name gender
• Religion
  • Field Name religion
• IPEDs Hispanic
  • Field Name ipedsHispanic
• IPEDs Ethnic
  • Field Name ipedsEthnic
• US citizen (includes permanent resident as an option)
  • Field Name citizenStatus
• Citizenship Country
  • Field Name citizenCountry
• Visa Type
  • Field Name visa
• In house Ethnicity
  • Field Name ethnicityCode
• Resident code
  • Field Name residenceCode

leadUrl Field (UTM)

Campus Cafe can import UTM (Urchin Tracking Module) by adding parameters to the the url string that is passed to Campus Café through the API. 

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.

There is a base report (Admissions Inquiry Applicant Listing-Extended that 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

Open API URL

Campus Café’s Open API Inquiry 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://abc-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 your API as an Inquiry, this value needs to be Inquiry. For an API as an Application, this would be set as Application. The Admissions form mode needs to match this setting:<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 ABC school had an Open API Inquiry form named "Web Inquiry", with a token of "Bosco" it would ook like this:

https://abc-web.scansoftware.com/cafeweb/openAPI/v1/inquiries?portalConfig=Web%20Inquiry&value=Inquiry&token=Bosco

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="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">Major Code:</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:

[
     {
           "firstName":"Thomas",
           "lastName":"TestStudent",
           "emailAddress":"tteststudent@email.com",
            "phoneNumber":"7778884444",
           "inquirySource":"web-ad",
           "majorCode":"CIS",
           "enteringSemester":"201900",
           "address":{
                "street1":"5487 Payton Pl.",
                "street2":"Ste. 2",
                "street3":"",
                "city":"Los Angeles",
                "state":"CA",
                "zipCode":"92000",
                "country":"USA"
           }
}
]

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.

{
"date":{
     "cal":{
           "year":2018,
           "month":6,
           "dayOfMonth":20,
           "hourOfDay":10,
           "minute":57,
           "second":26
     },
     "validDay":false,
     "zeroDate":false
},
"totalRecordCount":1,
"holdingRecordCount":0,
"directlyUpdatedCount":1,
"insertedRecordCount":0,
"duplicateRecordCount":0,
"unknownRecordCount":0,
"failedRecordCount":0,
"messages":{
     "elements":[]
}
}

Retrieving Valid Codes

Campus Café’s Open API Inquiry portal expects the following data fields values to match internal values. 

1. billingSite
2. counselor
3. enteringSemester
4. inquirySource
5. majorCode
6. site
7. 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:

[
  {"value":"CED","description":"Continuing Education"}, 
  {"value":"FIN","description":"Finance"}
]

Using these service calls, the developer may validate incoming inquiry data to Campus Café to ensure correct values are selected.