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) supporting bi-directional communication and sharing of Application data identified as fraudulent by colleges in an effort to combat admission, enrollment, and financial aid fraud activity across the California Community Colleges system. Developed using GraphQL API technology, this new service leverages the SuperGlue framework to amass a fraud data repository from college reports and stream fraud notifications from the CCCTC to affected colleges.
The Fraud Data API supports colleges that have implemented the SuperGlue College Adaptor to receive fraud notifications, as well as colleges that choose to query the API directly to get fraud information.
About This Guide
The purpose of this guide is twofold: a) to introduce the new Fraud Data API project, with its processes and procedures, to college and district staff who will be participating in fraud reporting and data sharing processes - with a practical guide for performing the primary operations; and b) provide more detailed, technical information to college and district IT staff who have a higher understanding of the basic concepts and capabilities of GraphQL API technology, with access to the API schema and the documentation required 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)*. *Courtesy of GraphQL EdEx Course
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..
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
The Fraud Data API supports the reporting and sharing of fraudulent application data between colleges across the system through 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 to 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.
For colleges that have implemented the College Adaptor, the Fraud Data API leverages SuperGlue to stream fraud notifications to a new dedicated staging table.
See the Fraud Data API Implementation Process page for more details.
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.
Authorized access to the API is restricted to individual MIS code(s). Account credentials identifying the specific college’s MIS code are provided by the CCCTC during the implementation process.
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 provide cohesive documentation for exposed fields, types, schemas and operations. Users are able to easily explore the data through the description field, and the schema Reference and Introspection (SDL) that provides supplementary notes and supports strings and markdown.
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 in an Apollo sandbox (see links below).
The Apollo sandbox supports all GraphQL operation types (
Query
,Mutation
, andSubscription
) and allows you to explore the Fraud Data API schema documentation.
Explore the API in the Apollo Sandbox
The Apollo Studio Sandbox is a web interface that supports exploration of the Fraud Data API schema and metrics, and test the available Fraud Report operations. The schema A running instance of the Fraud Data API schema is loaded in sandboxes for the Pilot and Production environments. the Apollo sandbox supports API development, documentation, testing and validation resources to use and interact with
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.
Advantages of Using Postman: CCCTC highly recommends using Postman when interacting with the Fraud Data API. The advantages of Links to download and install Postman are provided in the Implementation Process section of this guide. In addition, a custom Postman collection (of files) can be imported containing your college OAuth configuration and ready-to-use fraud report queries.
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
Click here for more information about the Fraud Data API Implementation Process.
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.
More information is provided to the district during the Fraud Data API Implementation Process overview meeting with CCCTC Enabling Services.
Fraud Data API Operations
Each of the primary Fraud Data API operations are specified below, with an option to execute each call using Postman.
Required: An authorized API account with the appropriate credentials must be established by the CCCTC in order to query and submit fraud reports 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
token required in the Authorization
head for secured requests to the API. (Note: An API account is configured 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'
Note: In the example above, the token request is made using cURL, however any preferred API tool can be used, such as Python, PowerShell, Ruby, Java, etc.
Use Postman to Get Your API Access Token
If you are using Postman to query the API, your account credentials were imported with the Fraud Report event collection and configured with the Fraud Report OAuth file.
To access your API token in Postman, click on the Fraud Report OAuth tab (which should still be open in your Postman workspace) for the appropriate environment. In the example below see the “GraphQL:Pilot” environment is selected (active). Click the Send button to get your access token.
The ‘access_token’ is automatically saved to the header for the API operation you intend to execute.
Submitting a Fraud Report Via API
A primary objective of the Fraud Data API is to report local fraud data from an individual college or multiple colleges in a district to the CCCTC, which then identifies the individual (CCCID) connected to the suspected fraud application (AppID), so that all other applications submitted by that CCCID can be located and shared with the college(s) that have received applications from the identified individual.
Through the API, the FraudReportSubmit mutation is the operation used for submitting a fraud report using an application id (AppID) or a student ID (CCCID), or both. In most cases, only the AppID is truly needed. A GraphQL mutation is an object type that is used to modify server-side data. Just as with queries, if the mutation field returns an object type, you can ask for nested fields. It can also contain multiple fields.
The FraudReportSubmit mutation requires an input (FraudReportSubmitInput!)
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}}}'
Reminder: The access token code is entered as the Bearer
token required in the Authorization
head for secured requests to the API. The access token includes the user credentials and the reporting college’s mis code.
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, Python, Java, etc.
Taking a closer look at the same operation in the Apollo sandbox, you can see that the
Variable table - where you can provide the information to submit (legitimate AppId for your MIScode).
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
Testing: While the purpose of this API is strictly for the reporting and sharing of information related to fraudulent applications and bad actors, any valid AppID or CCCID can be used for testing purposes. In addition to testing the API, these data will support the Tech Centers testing of the internal workflows to identify other applications that may be associated with the individual(s) reported to be fraudulent.
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.
Update Your College Adaptor for Fraud Data - Please see the Fraud Data API Implementation Process page for integration details.
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
As mentioned previously, colleges that are not yet able to stream fraud report notifications via the SuperGlue College Adaptor, the Fraud Data API supports a direct query of systemwide fraud information using the FraudReportQuery API call.
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":{}}'
Reminder: Enter your access token code as the Bearer
token required in the Authorization
head for secured requests to the API.
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 } ] } } }
Data Dictionary
Type | Field | Scalar Type | |
---|---|---|---|
Object | FraudReport | Fraud Report for a student and/or application | |
Field | submitTimestamp | String! | Timestamp of when report was created or updated last |
Field | cccId | String! | Student id this report belongs |
Field | ReportedByMisCode | String! | The college that submitted the report |
Field | RecipientMisCode | String! | The college that the report impacts |
Field | appId | Int! | Application id that triggered this fraud report |
Field | fraudType | FraudReportType | Reported by college: Stage of fraud reported |
Field | FraudReportType | ENUM | Values: APPLICATION, ENROLLMENT, FINANCIAL |
Field | federalAid | Float! | Reported by college: Total amount of Federal aid funds disbursed to associated individual identified to be fraudu |
Field | ccgiAid | Float! | Reported by college: Total amount of Cal Grant funds disbursed to associated individual identified to be fraudulent |
Field | localAid | Float! | Reported by college: Total amount of Local aid funds disbursed to associated individual identified to be fraudulent |
Field | otherAid | Float! | Reported by college: Total amount of Other State or Local aid funds disbursed to associated individual identified to be fraudulent |
Object | FraudReportQuery | Query for Fraud Reports | |
Field | withAppId | [FraudReport!] | Return list of reports for an application |
Field | withCCCID | [FraudReport!] | Return list of reports for a given student Id |
Field | withRecipientMisCode | [FraudReport!] | Return list of reports for a given mis code |
Object | FraudReportSubmitPayload | ||
Input | FraudReportSubmitInput | ||
Definitions of Terms
Term | Description |
---|---|
Fraud Data API | An API that supports bi-directional communication and sharing of application data between colleges in the system that have been identified as fraudulent. Used for fraud reporting. |
Fraud Report | |
Fraud Type | |
Application Fraud | |
Enrollment Fraud | The act of registering for classes without the intent to legitimately attend. Follows admissions application fraud and can only occur once a college has accepted the admissions application and enabled access to registration. |
Financial Aid Fraud | The act of attempting to collect financial aid to which the applicant is not legally entitled. Follows admissions application fraud and enrollment fraud. Can occur only once a college has allowed the student to register for classes, and once relevant external agencies have accepted students' financial aid application and colleges have begun the process of disbursing local, state, and/or federal financial aid. |
SuperGlue | SuperGlue is the integrations framework for products of the California Community Colleges and combines several technologies - application integration, service orchestration, api management, data integration and others. These technologies mostly leverage existing open source technology or cloud services from AWS with the addition of ERP/SIS integration supporting the three major Student Information Systems in use by colleges in the California Community College system. |
College Adapter | |
Staging Table | A dedicated database table established to store or hold a data set that receives incoming data. |
GraphQL API | GraphQL is a query language for APIs and a runtime for fulfilling queries with existing data. GraphQL provides the power to ask for exactly the data needed and nothing more, making it easier to evolve APIs over time and enables powerful developer tools. GraphQL queries always return predictable results. Apps using GraphQL are fast and stable because they control the data they get, not the server. (For more information, see this primer on GraphQL). |
GraphQL Schema | |
Apollo Server |
Documentation & Supporting Resources
Item | Description | File / Link |
---|---|---|
Apollo API Sandbox | Fraud API Documentation | |
GraphQL API Documentation | Introduction to GraphQL Primer / Documentation | |
Postman Documentation | Introduction to Postman / Documentation | https://learning.postman.com/docs/getting-started/introduction/ |
Postman Collection Files | Fraud Report Collection:
GraphQL:Pilot Environment Collection | |
Table of Fraud API Data Fields | CCCTC Fraud API Data Element | |
Definition of Terms | CCCTC Fraud Report Project Definition of Terms |