API docs by Redocly

Background Checks API (0.1.0)

Download OpenAPI specification:

Verify that college applications and need-based aid applications come from real students - not bad actors.

Features:

  • Integrates with all major student information systems (SIS)
  • Request-based pricing model
  • Detect fraud in Free Application for Federal Student Aid (FAFSA) applications
  • Integrate with student resources in SIS to automatically place holds on registration
  • Uses multiple datapoints for background checks - address liveness, program of study sanity checks, ML-model scoring

student

Student metadata for recording student liveness, fraud likelihood

Get a paginated list of students

Implementation note - later this operation will call SIS APIs for reading student data, for now query data in DynamoDB

Authorizations:
oauth2Profiles
query Parameters
offset
integer <int64> >= 0
Example: offset=5

offset for retreiving search results

limit
integer <int64> >= 1
Example: limit=25

number of results per page

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    },
  • "links": {
    }
}

Create a new student

Authorizations:
oauth2Profiles
Request Body schema: application/octet-stream
studentId
integer

Student's unique identifier (Implementation note- currently generated in DynamoDB, later will be foreign keys to SIS database)

email
required
string
address
required
string
birthdate
required
string
level_of_study
required
string
Enum: "BACHELORS" "MASTERS" "DOCTORAL"

student level of study

verificationStatus
any
consented
boolean

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "statusCode": 200,
  • "message": "/students/55"
}

Find a student by email

Implementation note - currently queries students in DynamoDB, eventually should query data with banner/other SIS APIs

Authorizations:
oauth2Profiles
query Parameters
email
required
any
Example: email=kworathur3@gatech.edu

Email of the student to retrieve

Responses

Response samples

Content type
application/json
{
  • "studentId": 0,
  • "email": "kworathur3@gatech.edu",
  • "address": "123 Cherry St., Atlanta GA, 30309",
  • "birthdate": "2002-04-12",
  • "level_of_study": "BACHELORS",
  • "verificationStatus": null,
  • "consented": true
}

Find student by identifier.

Returns a single student.

Authorizations:
oauth2Profiles
path Parameters
studentId
required
integer <int64>

ID of student to return

Responses

Response samples

Content type
application/json
{
  • "studentId": 0,
  • "email": "kworathur3@gatech.edu",
  • "address": "123 Cherry St., Atlanta GA, 30309",
  • "birthdate": "2002-04-12",
  • "level_of_study": "BACHELORS",
  • "verificationStatus": null,
  • "consented": true
}

Update a student's verification status

update a student's verification status with form data and place a hold on the student's registration if student marked as fraudulent

Authorizations:
oauth2Profiles
path Parameters
studentId
required
integer <int64>

ID of student that needs to be updated

Request Body schema: application/json

Update a student's status from UNVERIFIED to VERIFIED

status
string (VerficationStatus)
Enum: "UNVERIFIED" "VERIFIED" "NEEDS_REVIEW" "FRAUDULENT"

The new verification status of the student

Responses

Request samples

Content type
application/json
{
  • "status": "VERIFIED"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "statusCode": 200,
  • "message": "Successfully updated student(id:55) status from UNVERIFIED to VERIFIED"
}

Confirm a student's consent to background checks.

Authorizations:
oauth2Profiles
path Parameters
studentId
required
integer <int64>
Example: 55

ID of student to update

Request Body schema: application/octet-stream
consentStatus
required
boolean

Responses

Request samples

Content type
application/octet-stream
{
  "consentStatus": true
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "statusCode": 200,
  • "message": "Student has consented to background checks"
}

applications

An need-based financial aid application for a student

Create a new financial aid application for a student

Authorizations:
oauth2Profiles
path Parameters
studentId
required
integer <int64>
Example: 55

ID of student to update

Request Body schema: application/octet-stream
fafsa_id
string
last_name
string
first_name
string
middle_initial
string
street_address
string
city
string
mailing_state
string
zip_code
string
social_security_number
string/^[0-9]{9}$/
date_of_birth
string
high_school_name
string
high_school_city
string
high_school_state
string
students_income
integer
parents_income
integer
parents_cash_savings_and_checking
integer
students_number_of_family_members
integer
students_number_in_college
integer
housing_plans
string
date_completed
string
parents_asset_threshold_exceeded
boolean
appid
integer

Request samples

Content type
application/octet-stream
{
  "fafsa_id": 8911122,
  "last_name": "Worathur",
  "first_name": "Keshav",
  "middle_initial": "V",
  "street_address": "123 Cherry St. NW",
  "city": "Atlanta",
  "mailing_state": "GA",
  "zip_code": 30309,
  "social_security_number": 123456789,
  "date_of_birth": "2026-01-20",
  "high_school_name": "Reedy",
  "high_school_city": "Frisco",
  "high_school_state": "TX",
  "students_income": 0,
  "parents_income": 120000,
  "parents_cash_savings_and_checking": 50000,
  "students_number_of_family_members": 4,
  "students_number_in_college": 2,
  "housing_plans": "off-campus",
  "date_completed": "2020-05-01",
  "parents_asset_threshold_exceeded": "N",
  "appid": 1234
}

check

Background checks on students and their financial aid applications.

get a list of completed and in progress checks for a student

Authorizations:
oauth2Profiles
path Parameters
studentId
required
integer <int64>
Example: 55

ID of student to perform an inquiry against

Start an address liveness inquiry for a student.

Authorizations:
oauth2Profiles
path Parameters
studentId
required
integer <int64>
Example: 55

ID of student to perform an inquiry against

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "statusCode": 200,
  • "message": "24a0d969-f8f3-4a7b-b685-f25343caefad"
}

Perform a sanity check of a student's program of study based on a student's age.

Updates postSanityCheck indicator in indicators. Note that this sanity check is implemented synchronously.

Authorizations:
oauth2Profiles
path Parameters
studentId
required
integer <int64>
Example: 55

ID of student to perform a sanity check against

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "statusCode": 200,
  • "message": "Program of study sanity check complete"
}

Calculate attendance rate and class participation for a student.

Substitutes data from learning management systems and piazza with synthetic data

Authorizations:
oauth2Profiles
path Parameters
studentId
required
integer <int64>
Example: 55

ID of student to perform an inquiry against

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "statusCode": 200,
  • "message": "24a0d969-f8f3-4a7b-b685-f25343caefad"
}

Check if a student's SSN appears in a list of blacklisted SSNs.

Authorizations:
oauth2Profiles
path Parameters
studentId
required
integer <int64>
Example: 55

ID of student to perform an inquiry against

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "statusCode": 200,
  • "message": "24a0d969-f8f3-4a7b-b685-f25343caefad"
}

Get the status of a background check.

Authorizations:
oauth2Profiles
path Parameters
studentId
required
integer <int64>
Example: 55

ID of student to update

checkId
required
integer <int64>
Example: 100

ID of check to update

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "statusCode": 200,
  • "message": "IN_PROGRESS"
}

advising

Advising appointments booking

retrieve the value of a flag in the application's global config for advising.

Authorizations:
oauth2Profiles
query Parameters
configKey
string
Value: "ADVISING_PAUSED"

The config key to read. Defaults to ADVISING_PAUSED.

Responses

Response samples

Content type
application/json
{
  • "configKey": "ADVISING_PAUSED",
  • "value": false,
  • "reason": "registration for phase I now open"
}

Update the value of a flag in the application's global config for advising.

Authorizations:
oauth2Profiles
Request Body schema: application/json
configKey
required
string
Value: "ADVISING_PAUSED"

The config key to update

value
required
boolean
reason
string

Responses

Request samples

Content type
application/json
{
  • "configKey": "ADVISING_PAUSED",
  • "value": true,
  • "reason": "Maintenance Window"
}

Response samples

Content type
application/json
{
  • "message": "Advising paused",
  • "configKey": "ADVISING_PAUSED",
  • "value": true
}

list all rules for assigning advisors to students

Authorizations:
oauth2Profiles
query Parameters
limit
integer [ 1 .. 100 ]
Default: 25

Maximum number of rules to return (default 25, max 100)

lastKey
string

Cursor (ruleId) from the previous page for pagination

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "lastKey": "string"
}

create a new rule for assigning advisors to students

Authorizations:
oauth2Profiles
Request Body schema: application/json
advisorId
required
number

the advisor's ID

conditionType
string
Value: "LAST_NAME_RANGE"

Type of condition used for assigning advisors to students (e.g. range condition).

parameters
object

list of the parameters used to execute the mapping and their corresponding values

priority
number >= 1

priority for evaluating the rule. A lower number indicates a higher priority

isActive
boolean

whether or not the advising mapping is active.

Responses

Request samples

Content type
application/json
{
  • "advisorId": 12345,
  • "conditionType": "LAST_NAME_RANGE",
  • "parameters": {
    },
  • "priority": 1,
  • "isActive": true
}

Response samples

Content type
application/json
{
  • "message": "Rule created",
  • "ruleId": "a0000000-0000-4000-a000-000000000001"
}

Update an advisor-advisee mapping.

update the condition type, parameters, or priority of an advising rule

Authorizations:
oauth2Profiles
path Parameters
ruleId
required
number

ID of the advising rule to update

Request Body schema: application/json
advisorId
required
number

the advisor's ID

conditionType
required
string
Value: "LAST_NAME_RANGE"

Type of condition used for assigning advisors to students (e.g. range condition).

parameters
required
object

list of the parameters used to execute the mapping and their corresponding values

priority
required
number >= 1

priority for evaluating the rule. A lower number indicates a higher priority

isActive
required
boolean

whether or not the advising mapping is active.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "message": "Rule updated",
  • "ruleId": "a0000000-0000-4000-a000-000000000001"
}

getLoggedInUserAdvisor

find the advisor for the current student using the advisor-advisee mappings

Authorizations:
oauth2Profiles

Responses

Response samples

Content type
application/json
{
  • "advisorId": "advisor-uuid-1"
}

getAdvisorAvailability

get available slots for a given advisor in the next two weeks

Authorizations:
oauth2Profiles
path Parameters
advisorId
required
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

createAdvisorAvailability

bulk create or replace advisor availability slots for a given week

Authorizations:
oauth2Profiles
path Parameters
weekStartDate
required
string <date>

Responses

Response samples

Content type
application/json
{
  • "message": "Availability updated",
  • "slotIds": [
    ]
}

deleteAdvisorBooking

cancel an advisor booking

Authorizations:
oauth2Profiles
path Parameters
bookingId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "message": "Booking cancelled",
  • "slotId": "175eb645-92b7-478f-b868-207aea32920e"
}

getBookings

list a student's booked advising sessions

Authorizations:
oauth2Profiles

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

bookAdvisingSlot

book an advising slot

Authorizations:
oauth2Profiles

Responses

Response samples

Content type
application/json
{
  • "message": "Booking created",
  • "slotId": "175eb645-92b7-478f-b868-207aea32920e"
}

advising_insights

Insights to give students topics to discuss during advising

getAdvisingInsight

read an advising insight

Authorizations:
oauth2Profiles
path Parameters
insightId
required
string

Responses

Response samples

Content type
application/json
{
  • "insightId": "e0b109ff-077c-4d58-916e-b128cab16ecb",
  • "advisorId": "string",
  • "name": "string",
  • "templateKey": "CREDENTIALS_NEAR_COMPLETION",
  • "parameters": { },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

putAdvisingInsight

update an advising insight for a student

Authorizations:
oauth2Profiles
path Parameters
insightId
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "Insight updated",
  • "insightId": "string"
}

deleteAdvisingInsight

delete an advising insight

Authorizations:
oauth2Profiles
path Parameters
insightId
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "Insight deleted",
  • "insightId": "string"
}

listAdvisingInsights

list an advisor's insights

Authorizations:
oauth2Profiles

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

createAdvisingInsights

create a new advisor insight

Authorizations:
oauth2Profiles

Responses

Response samples

Content type
application/json
{
  • "message": "Insight created",
  • "insightId": "e0b109ff-077c-4d58-916e-b128cab16ecb"
}

runAdvisingInsight

run embedded sql query for an insight on a specific student

Authorizations:
oauth2Profiles
path Parameters
insightId
required
string
query Parameters
studentId
required
integer

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "insightId": "string",
  • "studentId": 0
}

getAdvisingSessions

return booked advising sessions for the current advisor in the next and upcoming week

Authorizations:
oauth2Profiles

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

seedDegreeWorks

seed degreeworks with initial degree data for insights

Authorizations:
oauth2Profiles