API Guide - Student Applications

Introduction

Northstar's Student Application API facilitates the creation of students via 3rd-party services such as those being used to handle admissions processing (eg. SalesForce, BPLogix). The Student Application API is available as extension of the Portal sites and can be found by navigating to your school's respective URL as described below. Students created through the Test URLs will be recorded into your Nightly/Test Northstar and can be reviewed using that server selection in the Northstar desktop application. On both the test and live API, no emails are sent to the student; only the status result is returned to the external source. API requests that fail will return an error message and details about which data was missing or invalid. When an API requests succeeds, it returns a success code and custom student information such as their StudentID, DemoKey, and GoogleEmailAddress. Successfully created students can also be reviewed by filtering on the "Source" column of the "Student Applications" form in Northstar.


Testing Site:

Replace the "COLLEGE" domain in the following URLs with your own.

    • Web UI: https://portal.COLLEGE.edu/Test/apidocs
    • API: https://portal.COLLEGE.edu/Test/api/beta/students/applications

Production Site:

By default, the Production API is disabled. After you've tested against the beta API successfully, contact the dev team for verification. We'll review the logs and enable the Production API.

Replace the "COLLEGE" domain in the following URLs with your own.

    • Web UI: https://portal.COLLEGE.edu/Portal/apidocs
    • API: https://portal.COLLEGE.edu/Portal/api/v1/students/applications

Getting Started

Access to the API is restricted. Before you can begin attempting connections to it, you'll first need to generate a private API Key. To do so, follow these steps:

  1. Login to the Portal as a Staff user in the web-admin role.
    • Initially, this would be your /Test testing site.
  2. Click the "Web Admin Dashboard" link.
  3. Click the "Student Application Settings" link.

  1. Scroll down to the "API Key " section.
  2. Click the "Generate New Key" button.

Testing

Before attempting to integrate the API directly into your 3rd party tool, we recommended that you first familiarize yourself with the API structure using our interactive web UI. This UI make it simple to quickly test multiple API calls to ensure your model is formatted correctly and can successfully connect to the API. To access the web UI, navigate to the apidocs link as described in the "Introduction" section above. The apidocs page should look like the annotated image below.

How to use the Web UI:

  1. Find the "Student Application" item and click the "Expand Operations" link (A).
  2. Paste the API Key you generated from the "Getting Started" section above into the 'apiKey' field (B).
  3. Paste the formatted JSON model containing the student data's into the 'model' field (C).
    • Below is code block containing a template of the data model.
      • For a quick test you can copy this template and replace any "REQUIRED" section with an appropriate value. An optional section accepts either null or a value as indicated by the notation "null/true/false" or "/null. Edit the file to provide a single value for each field or use your 3rd party tool to generate a JSON formatted file.
      • To read a more thorough description of each field, click the "Model" link on the apidocs page (E).
        • Some fields are required, while others are always optional or conditionally required based on custom rules.



  4. Click the "Try it out" button to initiate an API call directly to Northstar (D).
    • A series of loading dots will appear to the right of the button to indicate the API call is in progress.

  5. The results of the API attempt will then be displayed in the section under (D), noted with a response code and message of 200 or 400 as noted below (F).

    • A 200 response code means the API call succeeded and a student was created. The JSON response includes information about the newly created unique account as seen in this code block.

    • A 400 response code means the API call reached the server but failed to create a student account due to either invalid data or other processing errors. The JSON response will include a Message field with a general error summary. If the error was due to invalid data then a ModelState field will also be included that describes the specific error in greater detail.
        • In this example, the FirstName field caused a validation error because it wasn't provided.

        • In this example, the request failed because the API key was either not supplied or was invalid.

Going Live

After you've successfully tested the API in your test environment, you'll need to contact the development team for us to enable it on your production site.

Change History

  • 2021-08-31
    • Official API available for college testing and certification.
  • 2021-10-04
    • Added "Message" field to 200 OK response JSON. The value will always be "The operation completed successfully".