This introductory user guide provides colleges with:

• a general description and usage of the SuperGlue Bi-directional Fraud Data API

• an overview of the college implementation process and options for integration with the API

• a basic introduction to a GraphQL API for reporting and querying fraud data

• API documentation & resources

Contents

Introduction

The Fraud Data API is a SuperGlue-based solution (API) that supports bi-directional communication and sharing of suspected admission application, enrollment, or financial aid fraud with the CCC Technology Center, which in turn can suspend or block the individual’s profile, effectively protecting all other colleges automatically. Developed using GraphQL API technology, the first phase of this service will leverage the SuperGlue framework to amass a fraud data repository from college reports and then stream notifications out to other affected colleges.

About This Guide

The purpose of this guide is twofold: a) to introduce the Fraud Data API project, with its processes and procedures, to college and district staff who will be participating in fraud reporting and data sharing operations; and b) to provide the technical information and API documentation to IT staff and developers who have a higher understanding of the basic concepts and capabilities of GraphQL API technology, including access to the schema and query templates used to execute the primary operations currently supported by this service.

About GraphQL API

GraphQL is a new API standard that provides a more efficient, powerful and flexible alternative to REST (Representational State Transfer)*. GraphQL

While there are many excellent learning guides and tutorials on GraphQL online, including what it is and how to work with it, this document will primarily focus on learning and understanding the Fraud Data API - which is developed on GraphQL technology.

^{*Courtesy of GraphQL EdEx Course}

See the About GraphQL API page for an introduction to the basic concepts of GraphQL technology, the schema, and examples of the functional operations used in the Fraud Data API (query, mutation, subscription).

The Fraud Data API

In the first phase of the Fraud Data API development, the CCCTC has developed an API solution that supports the reporting of admission application data to a centralized database and the ability to run queries against that data using an authorized MIS code with an AppID or CCCID. Internally, an algorithm determines if a submitted fraud application report also impacts another college in the district. If so, Superglue is leveraged to notify that college of the suspected bad actor.

Districts are encouraged to use this API for development within their own internal SIS system.

The API can also be used ad hoc to perform the three primary workflow operations:

• Submit fraud information to a CCCTC centralized database

• Receive fraud notifications to a dedicated staging table using the College Adaptor

• Query the fraud database directly via the API

Eventually through continuous improvement, the API will be extended to also support other types of fraud data, including financial aid fraud. Participating districts are provided the Fraud Data API schema (GraphQL-based, described further below) and authorized access to the API during the implementation process with the CCCTC.

Reporting Fraud Data Via API

The reporting of locally identified fraud data from an individual college or district to the CCC Technology Center (CCCTC) is managed via the Fraud Data API. Everything needed to submit fraud reports is documented in the schema (see the API Documentation section below), as well as through custom Postman files configured specifically for the fraud data operations. More information and detailed examples of the FraudReportSubmit mutation are provided in the Submitting a Fraud Report Via API section of this guide.

Receive Fraud Notifications to Staging Table

As colleges report fraud by application ID (AppID), the CCCTC executes a workflow to identify the individual associated with the reported fraud (via their CCCID) and then locates any other submitted applications by that suspect CCCID. CCCTC then delivers these findings to the colleges that have also received a submitted application from that individual. These notifications are streamed to a new fraud-report staging table (for each college) via the SuperGlue College Adaptor. Each notification response will consist of the application ID (AppID), the applicant’s CCCID, and the MIS code of the college reporting the fraud (ReportedByMisCode).  Learn more about this process in the Receiving Fraud Notifications to a Staging Table section below.

Below is a diagram of the API processes leveraged by SuperGlue and the College Adaptor.

Querying Fraud Data Directly Via API

An option for colleges that have not yet implemented the SuperGlue College Adaptor, districts have the ability to query the fraud table directly through the API, with a CCCID, with an AppID, or with their authorized MIS code (withRecipientMisCode). A successful response is returned if the CCCID used in the query matches any other application submitted to their authorized MIS code. The process for querying the API directly is described in the Querying Fraud Data via API section of this guide.

The Fraud Data API Schema

The schema is one of the most important concepts when working with a GraphQL API. It specifies the capabilities of the API, the shape of the available data, and the specific queries and mutation functions that can be used to read, write and make web requests from a GraphQL server. GraphQL enables users to specify exactly what data they get back in their response—nothing more, and nothing less, and it allows querying for multiple field

The Fraud Data API schema specifies the fraud report operations currently available to execute. The FraudQuerySubmit type mutation provides the operation and data structure for submitting a fraud report to the CCCTC for a CCCApply Application (AppId) or a student ID (CCCID). The FraudReportQuery provides the data structure for retrieving fraud data information via the API. The schema is provided to colleges in documentation and the following supporting resources in which to explore the Fraud Data API:

• Apollo API documentation & sandbox (see links below)

• Query examples for each operation

• Postman API tool and custom collections configured with the schema, OAuth specifications, and ready-to-use turnkey fraud report operations.

By providing districts direct access to the [Fraud Data] API schema, the CCCTC has effectively empowered the colleges with the ability to create and generate a user interface of their own, for example, that could be used to implement a more automated process for dealing with fraud application data. Or they can simply use Postman and the files configured for the Fraud Data API that are provided, to educate themselves on the GraphQL API or visualize the data structure.

API Documentation, Tools & Sandbox

One of the benefits of a GraphQL API is its inherent ability to be self-documenting. This means that when you use an interactive tool like GraphiQL, you’re able to explore what data is exposed by your GraphQL API, including the fields, types, and more. Users can also explore the data through the description field which provides supplementary notes about the endpoint.

In most cases this provides enough API reference documentation. However, to better understand and visualize the Fraud Data API, the complete schema documentation and the ability to explore, test, and validate the primary API calls is provided via an Apollo sandbox tool and operation templates provided by the CCCTC (see links below).

The Apollo sandbox supports all GraphQL operation types (Query, Mutation, and Subscription) and allows you to explore the Fraud Data API schema documentation.

Explore the API in the Apollo Sandbox

Access to the Fraud Data API schema is available in the Apollo Sandbox to college IT staff for exploration of the schema and metrics, API development, documentation, and testing of the Fraud Report operations.

Access & explore the Fraud Data API schema in each environment.

PILOT: https://apollo-router.pilot.ccctechcenter.org/

PROD: https://apollo-router.ccctechcenter.org/

The Documentation tab (in the sandbox) enables you to step into the Fraud Data API schema, beginning at one of its entry points. Click the ⊕ button next to any field in the Documentation tab to add that field to the operation editor, at your current path. By default, the Explorer automatically generates variables for that field's arguments.

Using Postman with the Fraud Data API

Postman is an API platform used for developing and using APIs. Postman has built-in support for sending GraphQL queries in the request body, using GraphQL variables, and introspection and importing GraphQL schemas. Postman includes a set of tools - such as the API Client - designed to “easily explore, debug, and test your complex API requests for HTTP, REST, SOAP, GraphQL, and WebSockets. The Postman client also includes built-in support for authentication protocols like OAuth 1.2/2.0, AWS Signature, Hawk, and more.” Learn more in the Postman Learning Center.

Postman supports working with GraphQL

College Implementation Process

To get started with the Fraud Data API, an authorized college or district IT engineer with a good understanding of API technology must contact with the CCCTC Enabling Services team to schedule a checklist meeting.

Below is an overview of the process:

• Work the CCCTC Enabling Services team to obtain API account and credentials

• Integrate with the Fraud Report (GraphQL) API

  • Install Postman tool and import event collections (optional, but recommended)

  • Or set up standard templates in preferred API tool (Python, cURL, Powershell, Ruby, Java, etc.)

• Install the Fraud Report staging table and deploy latest version of College Adaptor to receive a live stream of fraud notifications; or use the GraphQL Fraud Report Query to receive a list of fraud notification

Authorized Access Accounts

During the implementation process, one or more user accounts will be created for your college or district by a CCCTC implementation engineer. The account will be configured with the appropriate roles and secured to the mis codes authorized for the user. Users from multi-college districts may be authorized to submit and query fraud reports for each of the colleges in their district. Single college districts will be restricted to their single mis code.

Fraud Data API Operations

Recommended: Non-technical college staff are encouraged to use Postman for running ad hoc fraud reporting and queries. See /wiki/spaces/GLUEPD/pages/2851438610.

• Getting the API Access Token

• Submitting a Fraud Report Via API

• Receiving Fraud Notifications to Staging Table

• Querying Fraud Data Via API

Getting the API Access Token

With your API account created with the proper credentials in place, the request below returns a JSON block including an “access_token” field. This token becomes the Bearer required in the Authorization head for secured requests to the API. (Reminder: Your API account is provided by the CCCTC during the implementation process.)

curl --location --request POST '<https://auth.ci.ccctechcenter.org/auth/realms/API/protocol/openid-connect/token'> \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'username=mis-zz1-fraudreporter' \
  --data-urlencode 'password=Mis-zz1-fraudreporter' \
  --data-urlencode 'grant_type=password' \
  --data-urlencode 'client_id=fraudReporting'

Getting Your Access Token Using Postman

Once Postman is installed and the two Fraud Report Postman Collection files have been imported and configured with your API account credentials and environment specifications, the process for generating and refreshing your access token is managed on the Fraud Report OAuth tab. Once generated, Postman stores the token as the Bearer in the Authorization head for all secured API requests.

On the Fraud Report OAuth tab. Step 1: In your Postman Workspace, click on the Collections icon to expand the Fraud Report collection. Step 2: Click on the Fraud Report OAuth file to open the tab in your Workbench. Step 3: Ensure the appropriate environment is selected. In the adjacent example, the “GraphQL:Pilot” environment is selected (active). Step 4: Click the Send button to generate the access token. Access Token The 'access_token” becomes the Bearer required in the Authorization head for secured requests to the API. (Reminder: Your API account is provided by the CCCTC during the implementation process.) Each time you refresh your authorization, the new ‘access_token’ is automatically saved to the header for the next API operation you intend to execute. Each token expires in 300 seconds (5 mins).

Submitting a Fraud Report Via API

The primary function of the API is to enable colleges to report suspected or identified fraudulent admission applications to the CCCTC which can be used to identify, notify, and prevent the individual (CCCID) from committing additional fraud against colleges in the future.

The FraudReportSubmit Operation

The process for submitting fraud reports to the CCCTC is defined in the Fraud Data API schema as the FraudReportSubmit operation, which is a query mutation that requires an Input argument (FraudReportSubmitInput!) where at least one input field variable is required and a basic payload response is provided (FraudReportSubmitPayload).

In the majority of cases, only the application ID (AppID) input is truly needed; however additional input fields can or should be added to the operation.

In the screenshot below, an example of a basic fraud submit operation is built in the Apollo sandbox.

In the Operation section, a FraudReportSubmit mutation is built showing the default FraudReportSubmitPayload fields displayed. In the Documentation column, the Input argument - FraudReportSubmitInput - is selected and expanded showing the fields that can be used for the required input. In the Variables table, the “appId” field as been added as the only input variable for this basic operation (currently displaying a null value). Before submitting the request, a value would be entered in the “appId” input field (as shown below).

For multi-college district accounts, the operation should be modified to also include the “reportedByMisCode” field in the input argument to specify which college in the district the fraudulent application (appId) is being submitted for (see example shown in the Variables table).

With a better understanding of the basic operation, a skilled API developer has everything they need to effectively format a proper web request using an application development tool such as Curl, Python, PowerShell, etc. The Operation becomes the query itself

The example below submits a fraud report for application id (AppID) 34110.

curl --location --request POST 'https://apollo-router.qa.ccctechcenter.org' 
--header 'Authorization: Bearer eyJ......' 
--header 'Content-Type: application/json' 
--data-raw '{"query":"mutation FraudReportSubmit($input: FraudReportSubmitInput!) {\n  FraudReportSubmit(input: $input) {\n    cccId\n    appId\n    fraudType\n  }\n}\n","variables":{"input":{"appId":34110}}}'

Below is an example of a successful reply:

{
    "data": {
        "FraudReportSubmit": {
            "cccId": "AAA6198",
            "appId": 34110,
            "fraudType": "APPLICATION"
        }
    }
}

In the hands of a knowledgable API programmer, the schema provides everything needed to construct and execute the FraudReportSubmit operation, including the required argument, Input fields, and the payload response using an API dev tool such as CURL, PowerShell, Python, Java, etc. Any of these development tools will provide the

In the hands of a GraphQL tool, such as CURL, the operation must be formatted as a web request (web request object) - have to have the skill set to know how to do that. We provide the schema and information to do that

In this operation, the mutation has an Input argument, FraudReportSubmitInput!, that specifies data values that will be included in the submission. FraudReportSubmitInput! input is a required argument, and the FraudReportSubmitPayload! becomes the response.

Learn how to use an Input object type in a GraphQL mutation operation.

A Mutation type is a special root type that is used to modify server-side data. Just like in queries, if the mutation field returns an object type, you can ask for nested fields. It can also contain multiple fields. However, unlike queries, mutation fields run in series, one after the other.

Learn more about GraphQL mutations

Explore the schema documentation for the FraudReportSubmit mutation and see the available Input fields.

Submit a Fraud Report Using Postman

In your Postman workspace, click on the Fraud Report Submit file in the Fraud Report collection.

To support users that may not have the necessary skillset to build and submit a web request from the schema, the report can be submitted via the Postman tool - operation can be using be API developers, In the body of the post, the data structure for the FraudReportSubmit mutation appears in the Query portion of the workspace, with ($input: FraudReportSubmitInput!) as the required argument. In GraphQL, an Input can be an argument against an object. In this case, FraudReportSubmit is an object type. The three fields below the object indicate the fields that we want values for in the response. The input variables appear in the GraphQL VARIABLES box

Receiving Fraud Notifications to a Staging Table

An objective of the fraud data project is to leverage SuperGlue in developing more automated processes for sharing fraud information with and between colleges that are receiving fraudulent applications from the same individuals. In the first phase, CCCTC is able to identify every college that has received applications from the suspect CCCID, and then notify those colleges that have received an application from the individual associated with a fraudulent application reported by a college.

When this happens, when the system identifies other submitted applications to other colleges by the same CCCID, a new fraud-report is pushed to a dedicated staging table (for each college) via the SuperGlue College Adaptor. Each notification response contains, among other available fields, the fraudulent application ID (AppID), the applicant’s CCCID, and the MIS code of the college reporting the fraud. 

A GraphQL-based Fraud Report schema gives colleges the ability to submit fraud reports with an AppID and query fraud information with an AppID (or CCCID) that is associated with their college MIS code. Leveraging the SuperGlue framework, CCCTC is then able to stream a notification to your dedicated staging table that it detects an application has also been submitted to your college by the same individual. association with the the system finds as to which the suspect has also applied. If your MIS code is recognized associated with any instance of fraud reported Based on your authorized MIS code, of these findings to a dedicated staging table if the findings identify your MIS code among the colleges the suspect has also applied to.

Example of a list of fraud reports, streamed to recipient college’s sis fraud staging table.

submitReport ( 1667930615650 , AAA8480 , 911 , undefined , 23995 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , ZZ3 , 26437 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , ZZ1 , 25674 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , ZZ3 , 26438 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , ZZ5 , 20468 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , 271 , 20453 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , 661 , 23269 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , 661 , 23270 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , 233 , 23177 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , 334 , 23168 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , 981 , 23170 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , 611 , 17933 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , 611 , 17934 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , 611 , 18704 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , ZZ1 , 17557 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , ZZ1 , 17105 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , ZZ1 , 17107 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , ZZ1 , 17109 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , 345 , 22733 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , 981 , 23296 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , ZZ5 , 21319 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , ZZ5 , 21316 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , 781 , 27856 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , ZZ2 , 17558 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , 261 , 20198 , APPLICATION , undefined , undefined , undefined , undefined )
submitReport ( 1667930615650 , AAA8480 , 911 , 261 , 20295 , APPLICATION , undefined , undefined , undefined , undefined )

Querying Fraud Data via API

For colleges that aren’t able to stream fraud notifications via the SuperGlue College Adaptor, fraud data can be queried directly using the FraudReportQuery API request. The FraudReportQuery is the query interface for a FraudReport type object, which is basically the “fraud report” response for a student and/or application that includes 10 fields.

When an authorized user fetches fraud reports related to your college through the API, the Access Token authenticates the user’s credentials and also identifies the user’s MIS code as the “recipientMisCode” in a query and responds with a list of fraud reports that match your MIS code.

There are three different variations of the FraudReportQuery that can be used to query fraud reports:

FraudReport object has the following fields:

• appId!

• cccId!

• recipientMisCode!

• reportedByMisCode!

• submitTiimestamp!

• fraudType

• ccpgAid

• federalAid

• localAid

• otherAid

Three FraudReportQuery three Input arguments:

• withAPPID

• withCCCID

• withRecipientMisCode

Each argument

Mostly used with the “withRecipientMisCode” query (because the district or college will be retrieving the applications or CCCIDs of the applicants that have submitted applications to their institution’s mis code.

Fraud Report Query (FraudReportQuery)

The FraudReportQuery type :

Example: FraudReportQuery Request

curl --location --request POST 'https://apollo-router.qa.ccctechcenter.org' \
  --header 'Authorization: Bearer eyJhb' \
  --header 'Content-Type: application/json' \
  --data-raw '{"query":"query FraudReportQuery {\n  FraudReportQuery {\n    withRecipientMisCode {\n      submitTimestamp\n      cccId\n      reportedByMisCode\n      recipientMisCode\n      appId\n      fraudType\n      federalAid\n      ccpgAid\n      localAid\n      otherAid\n    }\n  }\n}","variables":{}}'

with example of expected response:

{
    "data": {
        "FraudReportQuery": {
            "withRecipientMisCode": [
                {
                    "submitTimestamp": "2022-10-07T21:15:37.000Z",
                    "cccId": "AAA0002",
                    "reportedByMisCode": "ZZ2",
                    "recipientMisCode": "ZZ1",
                    "appId": 4,
                    "fraudType": "APPLICATION",
                    "federalAid": null,
                    "ccpgAid": null,
                    "localAid": null,
                    "otherAid": null
                }
            ]
        }
    }
}

To learn more about the syntax for these variable definitions, it's useful to learn the GraphQL schema language. The schema language is explained in detail on the Schema page.

Documentation & Supporting Resources

See also:

• Definitions of Terms

• Fraud API Data Elements