This document provides colleges with an introductory user guide for the SuperGlue Bi-directional Fraud Report API, including:

• a general description and usage of the bi-directional fraud report API

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

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

• supporting documentation & API resources

Contents

Introduction

The Fraud Data API is a SuperGlue-based solution (API) supporting bi-directional communication and sharing of CCCApply Application data identified as fraudulent by colleges in support of the ongoing effort to identify and reduce admission and financial aid fraud across the California Community Colleges system. A GraphQL-based Fraud Report schema gives colleges the ability to submit fraud reports and query fraud data with an AppID (or CCCID) associated with their college MIS code. Leveraging the SuperGlue framework, CCCTC is able to then stream notifications of reported fraud with other colleges to which the suspect applicant has also applied.

About This Guide

The purpose of this guide is to provide college or district IT staff, or other technically-minded individual, who has an understanding of the basic concepts and capabilities of GraphQL API technology, a general overview of the Fraud Data API project and a high-level outline of the API schema and operations supported by this service. Comprehensive documentation and sandbox is provided for the API schema the three primary operations in this API are specified , API calls are provided Where possible, query code is provided are provided schema and the specific operations supported by the API are provided to colleges, as well as implementation steps to integrate with the API and implement the staging table.

By providing districts with direct access to the [Fraud Data] API schema, with appropriate authorized access to submit reports via the API, 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.

About the Fraud Data API

The Fraud Data API supports the reporting and sharing of Application fraud data between colleges across the system through three primary workflow operations: report (submit) fraud data to a central database; receive streaming notifications of fraud data to a dedicated staging table; and query the fraud database directly using the API. Eventually, in a subsequent phase, the API will be extended to also support other types of data, including financial aid fraud data. 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.

Submitting Fraud Data Via API

Colleges can submit AppIDs (or CCCIDs) using the FraudReportSubmit mutation-query to report instances of CCCApply application fraud to the CCC Technology Center (CCCTC). Everything needed to submit fraud reports through the API are provided in the schema (see the API Documentation links below). More information and examples of the FraudReportSubmit query-mutation are provided in the Submitting Fraud Reports Via API section below.

Receiving Fraud Data Notifications to Staging Table

As colleges report fraudulent applications by application ID (AppID), the CCCTC executes a workflow to identify the individual associated to the reported fraud (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. 

Query Fraud Data Using the API

Colleges that have not implemented the SuperGlue College Adaptor may query the Fraud Data API directly using an AppID or a suspect CCCID. An indicator of suspected fraud is returned when this has been reported by a college and is associated with the individual or application queried.

About GraphQL APIs

The Fraud Data API is a GraphQL service API which can be used with any language and framework. GraphQL is organized in terms of schema and type system versus Rest API endpoints.

GraphQL has its own type system that’s used to define the schema of an API. The syntax for writing schemas is called Schema Definition Language (SDL).

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 fields in a single request.

The Fraud Data API Schema

The Fraud Data API schema specifies which fraud report queries and mutations are available to execute. The FraudReportQuery describes the query interface for the FraudReport type object. The FraudQuerySubmit mutation provides the method colleges will use to submit fraud report data for a CCCApply Application. To explore the Fraud Data API schema, the following resources are provided to authorized college users:

• Apollo API documentation & sandbox (see links below)

• Raw code examples are provided for each operation

• Postman API tool and custom collections configured to the fraud report operations.

API Documentation, Tools & Sandbox

One of the benefits of a GraphQL API is its inherent ability to provide cohesive documentation for exposed fields, types, schemas and operations. Users are able to easily explore the data through the description field that provides supplementary notes and supports strings and markdown.

To better understand and visualize the schema and available queries and mutations of the GraphQL-based Fraud Data API, the CCCTC offers colleges a variety of API development, documentation, and testing resources to use and interact with.

Explore & View the API in the Apollo Sandbox

The Apollo Studio Sandbox is a web interface that can be used to view & explore the Fraud Data API schema and metrics, and test the available Fraud Report operations. A running instance of the Fraud Data API schema is loaded in sandboxes for the Pilot and Production environments.

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

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

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

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

Access the Fraud Data API Documentation

One of the benefits of a GraphQL API is its inherent ability to provide cohesive documentation for exposed fields, types, schemas and operations. Users are able to easily explore the data through the description field that provides supplementary notes and supports strings and markdown.

The Documentation tab 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

The Query and Mutation types are the entry points for the Fraud Report requests sent by the client. To execute the fraudReportQuery-query, the Query type is written as follows:

type Query {
  fraudReportQuery: FraudReportQuery
}

For the fraudReportSubmit-mutation, add a root field to the Mutation type:

type Mutation {
  fraudReportSubmit
}

Implementation Process

Overview:

• Work with 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
  

Get Started: Engage with CCCTC Enabling Services

To get started with the implementation process, an authorized representative (user) from the college or district will engage with the CCCTC Enabling Services (ES) team and schedule an initial overview meeting. The overview meeting allows the ES engineer the opportunity to understand and customize the implementation process to meet the college’s needs.

Below is a summary of the steps that are completed during the implementation overview meeting:

1. College user engages with the CCCTC Enabling Services and schedules overview meeting.

2. CCCTC creates an API account for the user and configures the appropriate roles, MIS code, and OAuth details.

3. CCCTC provides the college with the API account credentials via secure process.

4. CCCTC provides the college with related API files for use with Postman tool via secure process (optional).

5. CCCTC provides support for Fraud Report staging table and College Adaptor schema update.

6. CCCTC provides GraphQL API and schema documentation, integration recommendations, and supporting resources.

CCCTC Creates API User Account & Provides Credentials to College

An API user account gets created for the authorized college user during the implementation process, configured with the appropriate role(s) and college MIS Code that ensures secure access to the fraud data the college is authorized to retrieve from the API. CCCTC will provide the college user their account credentials (username and password) via secure process such as PrivNote.

CCCTC Recommends Postman Tool with Fraud Data API

To support your fraud report data submissions and queries for your college, two Postman collection files have been created containing all the JS code and environment information you need to automate your requests and workflows. Download and save these two files locally and import once your Postman install is complete. The two files are detailed in the Install & Configure Postman section below.

Install & Configure Postman (Optional, but recommended)

To support the use of the Fraud Report API, the CCCTC recommends using a tool such as Postman API client to automatically detects the language of the response, links, and format text inside the body to make inspection easy.

Step 1: Download & Install Postman

• Sign up for Postman: Click here to Sign up and start using Postman now for free.

• Download & Install Postman

Get the latest version of Postman. Visit the download page and select Download for your platform.

Step 2: Import Fraud Report Collections & Configure Postman

Once installed, Postman is configured to authenticate your access and greatly simplify your to the Fraud Report API submissions and requests. CCCTC will provide two Postman collection files containing all the JS code and environment information needed to automate your requests and workflows to the Fraud Report API.

Fraud Report Event: This collection includes three files:

• Fraud Report OAuth: Provides the authentication and

• Fraud Report Submit:

• Fraud Report Query:

GraphQL:Pilot Environment: This file contains the parameters specific to your account authorization credentials, the appropriate user role(s) and college MIS code, which identifies the fraud data your college has access to.

Postman Collections: Through the Postman API client, requests can be organized into Collections which help organize your requests for reuse so that time isn’t wasted rebuilding everything from scratch. Collections can contain JavaScript code to tie requests together to automate common workflows, and you can use scripting to visualize your API responses as charts and graphs.

Import Fraud Report Collections and Configure Postman

Expand for steps to import Fraud Report Postman Collection files:

 Import Fraud Report Collections and Configure Postman

1. Click the Fraud Report Postman Collection file below to save to your local Downloads directory.

1. From your

My Workspace page in Postman, click on the Collections button from the left menu, then click the Import button in the top right of the column.

1. Locate the

Fraud Report Postman Collection file in your Downloads folder (or wherever the files were downloaded to) and complete the Collection import process.

1. Once imported, expand the

Fraud Report collection heading to display the three fraud report files included. These files are named:

• Fraud Report OAuth

• Fraud Report Submit

• Fraud Report Query

1. Repeat the process to import the

GraphQL:Pilot Environment file. This file contains the parameters specific to your account authorization, including the appropriate role(s) and your college MIS code, which identifies the specific fraud report data your college is authorized to access.

1. Once imported, click on the

Environments icon from the upper right side menu in the workspace and select the appropriate environment (GraphQL:Pilot). The parameters for the GraphQL:Pilot environment will display in the center of your workspace.

Configure Account Credentials

1. In the USER row of the CURRENT VALUE column, enter the account username provided by the CCCTC.

1. In the PASSWORD row of the CURRENT VALUE column, enter the account password provided by the CCCTC.

1. Click the Fraud Report Postman Collection file below to save to your local Downloads directory.

2. From your My Workspace page in Postman, click on the Collections button from the left menu, then click the Import button in the top right of the column.

3. Locate the Fraud Report Postman Collection file in your Downloads folder (or wherever the files were downloaded to) and complete the Collection import process.

4. Once imported, expand the Fraud Report collection heading to display the three fraud report files included. These files are named:

• Fraud Report OAuth

• Fraud Report Submit

• Fraud Report Query

5. Repeat the process to import the GraphQL:Pilot Environment file. This file contains the parameters specific to your account authorization, including the appropriate role(s) and your college MIS code, which identifies the specific fraud report data your college is authorized to access.

5. Once imported, click on the Environments icon from the upper right side menu in the workspace and select the appropriate environment (GraphQL:Pilot). The parameters for the GraphQL:Pilot environment will display in the center of your workspace.

Configure Account Credentials

6. In the USER row of the CURRENT VALUE column, enter the account username provided by the CCCTC.

7. In the PASSWORD row of the CURRENT VALUE column, enter the account password provided by the CCCTC.

Getting/Refreshing Your Access Token

Once your account credentials (username and password) have been configured in the appropriate environment, open the Fraud Report OAuth tab and click the Send button.

In the lower half of the workspace see the JSON code displayed adjacent to the “access_token” variable. This token information will automatically fill the BEARER token in the Authorization header for each fraud report API request.

Configuring the Fraud Report Staging Table

Updating the College Adapter Version

Fraud Data API Operations

• Authorization: Getting API Access Token

• Submitting a Fraud Report

• Querying a Fraud Report

Getting API Access Token

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

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 & Refreshing Your Access Token with Postman

If you are using Postman to query the API, your account credentials were imported with the Fraud Report event collection and configured from the Fraud Report OAuth file.

To obtain or refresh your access token in Postman, click on the Fraud Report OAuth tab (which should still be open in your workspace) and confirm the appropriate environment. In the example below see the “GraphQL:Pilot” environment is selected (active). Click the Send button to get your access token.

Submitting a Fraud Report Via API

In the Fraud Data API schema, the operation to submit or report a fraudulent application is called a “mutation”. The Mutation type is a special 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

The Fraud Data API can be called to transmit data in the following use cases:

1. Provide CCCID only

2. Provide CCCApply AppID only

3. Provide AppID and corresponding CCCID

Submitting a Fraud Report

Colleges submit fraud report data for a specific College Application (CCCApply) using the Mutation operation: FraudReportSubmit: FraudReportSubmitPayload!

  FraudReportSubmit(input: FraudReportSubmitInput!): FraudReportSubmitPayload!

Example: Submitting a fraud report for 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}}}'

Submit a Fraud Report in Postman

Using Postman, click on the Fraud Report Submit” file in the Fraud Report collection.

Receiving Fraud Data to Staging Table

In our current flow of Bi-directional Fraud Reporting, We support a College being able to submit (via our Apollo API) a fraud report and have it broadcast to other colleges (those colleges that the student also applied to). For each of those colleges, if they have college adaptor installed and the fraud-staging-table config enabled, then we push the fraud report into that college’s sis staging table.

For college’s that do not have the College Adapter installed (or the fraud-staging-table config disabled), we do not share the fraud report with them. Instead, It is expected that the college will use the Apollo API to retrieve the fraud reports associated with their college (by misCode). But this functionality does not yet exist.

Example of

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 the Fraud Data via API

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
                }
            ]
        }
    }
}

Definitions of Terms

Documentation & Supporting Resources