Introduction
The Bi-Directional Fraud Data API is a SuperGlue-based solution (API) supporting bi-directional communication and sharing of suspected application fraud data with the CCC Technology Center for the purpose of sharing this determination of fraud status with other colleges in the system automatically. Developed using GraphQL API technology, the first phase of development leverages the SuperGlue framework to amass a fraud data repository built on college reports and streaming notifications out to other affected colleges. Eventually, through continuous improvement, the API will be extended to support other types of fraud data, including enrollment and financial aid fraud. Participating districts are provided the Bi-Directional Fraud Data API schema (GraphQL-based, described further below) and authorized access to the API during an implementation call with the CCCTC Enabling Services.
Panel | ||||||
---|---|---|---|---|---|---|
| ||||||
The Bi-Directional Fraud Data API will support colleges that have implemented the SuperGlue College Adaptor to receive fraud notifications as well as colleges that may choose to query the API directly to get fraud information. |
About This Guide
The purpose of this guide is twofold:
a) to provide an introduction to the Bi-Directional Fraud Data API project including the processes and procedures for college and district staff who will be participating in fraud reporting operations; and
b) to provide the technical information and documentation for IT staff and developers who have the necessary skills and 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 supported by this service.
About GraphQL API
GraphQL is a new API standard that provides a more efficient, powerful, and flexible alternative to REST API.
While there are many good learning resources and tutorials available, Introduction to GraphQL is an excellent primer for understanding the GraphQL language and the primary query operations used by the Fraud Data API.
See the About GraphQL APIpage for an introduction to the basic concepts of GraphQL, the schema, and examples of the functional operations used in the Fraud Data API (query, mutation, subscription).
The Bi-Directional Fraud Data API
The Bi-Directional Fraud Data API provides a mechanism for colleges to report locally-identified instances of fraud to the CCCTC, as well as facilitate the ability to query against that data using an authorized MIS code with an AppID or CCCID. In turn, CCCTC server-side workflows analyze the data to determine if the submitted fraud information impacts other colleges across the system. If impacts are found, Superglue is leveraged to notify these colleges of the bad actor.
By integrating the SuperGlue API to identify and share fraud data, colleges will be able to effectively extend the functionality of their own SIS systems and resources for increased efficiency. This is essential, not only for meeting fraud reporting requirements, but also for decreasing overall costs and increasing time savings. Districts are encouraged to use this API within their own internal systems.
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 Bi-Directional 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 Reportsection of this guide.
Receive Fraud Notifications to Staging Table
Each instance of application fraud reported to the CCCTC is used to identify other instances submitted by the same CCCID. These findings are then delivered to colleges as notifications to a 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.
Panel | ||||||
---|---|---|---|---|---|---|
| ||||||
For colleges that have implemented the College Adaptor, the Fraud Data API leverages SuperGlue to stream fraud notifications to a dedicated fraud-data staging table. |
Below is a diagram of the API processes leveraged by SuperGlue and the College Adaptor.
Querying Fraud Data Directly Via API
In addition to the streaming of fraud reports via the SuperGlue College Adaptor, the API also facilitates the ability to query the fraud table directly using aCCCID, an AppID, or an authorized MIS code(withRecipientMisCode). A successful response is returned if the CCCID used in the query matches any other application(s) submitted to the authorized MIS code. The process for querying the API directly is described in the Querying Fraud Report Datasection of this guide.
Note |
---|
Authorized access via the API is restricted by college- or district MIS code, which is set as the default attribute in the API account. Multi-college districts will have a default MIS code as well but may also be granted authorization for additional MIS codes for individual colleges in their district. API accounts are set up by the CCCTC and provided to the college during the implementation process. |
The Bi-Directional Fraud Data APISchema
The schema is one of the most important concepts when working with 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 of a GraphQL server.
The Bi-Directional Fraud Data API schema defines the query type operations currently available to execute. The FraudQuerySubmit mutation typeprovidesthe operation and data structure for submitting a fraud report to the CCCTC for a CCCApply Application (AppId) or a student ID (CCCID). The FraudReportQuery operation provides the structure for retrieving fraud data via the API.
Panel | ||||||
---|---|---|---|---|---|---|
| ||||||
In the hands of a knowledgeable API programmer, the schema provides The schema details everything needed to construct and execute the FraudReportSubmit operation, including the required input argument, input fields, and the payload response via an API development tool such as Postman, cURL, PowerShell, Python, Java, etc. Any of these development tools will provide the mechanism needed to make this API web request. |
API Documentation, Tools & Sandbox
One of the benefits of the CCCTC API is its ability to be self-documenting. This means that when an interactive tool like GraphiQL is used, users are able to explore what data is exposed by this 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 a clear understanding of the API. 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 a Sandbox tool as well as operation templates provided by the CCCTC (see links below).
The CCCTC API sandbox supports all operation types and allows you to explore the Fraud Data API schema documentation.
Explore the API in the CCCTC Sandbox
Access to the Bi-Directional Fraud Data API schema is available in the CCCTC API Sandbox to college IT staff for exploration of theschema and metrics, API development, documentation, and testing of the Fraud Report operations. Reach out to CCCTC Enabling Services for links and access to the sandbox.
By providing districts direct access to the Fraud Data API schema, the CCCTC has empowered provided the colleges with the ability to create and generate a user interface of their own. Such an Interface could, for example, 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 API’s functionality and/or visualize the data structure.
Using Postman with the Fraud Data API
CCCTC recommends using Postman for interacting with the Bi-Directional Fraud Data API. The Postman client -configured with ready to use templates provided by the CCCTC- will allow colleges that may not have the immediate resources or technical skills to integrate with the API initially to submit fraud reports and query the fraud database efficiently in order to participate in the fraud data reporting effort.
Links to install Postman, as well as the custom templates for submitting and querying fraud reports and the user authorization credentials are provided to the college during the implementation process. For more information on using Postman, please request a copy of Using Postman with the Fraud API from reach out to CCCTC Enabling Services.
Panel | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
Postman is a testing platform generically 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. |
College Implementation Process
To get started with the Bi-Directional 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:
Contact the CCCTC Enabling Services team to obtain your API account and credentials
Integrate with the Fraud Report API
Install Postman tool and import templates (optional, but recommended)
Or set up standard templates in preferred API tool (Python, cURL, Powershell, Ruby, Node, Java, etc.)
Install the Fraud Report staging table and deploy latest version of the College Adaptor to receive a live stream of fraud notifications, or use the Fraud Report Query to receive a list of fraud notifications.
Panel | ||||||
---|---|---|---|---|---|---|
| ||||||
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 attributes, and secured to the MIS codes authorized for the specific user. Users from multi-college districts may be authorized to submit and query fraud reports for all or some of the individual colleges in their district. Single college districts will be restricted to their single college MIS code.
Panel | ||||||
---|---|---|---|---|---|---|
| ||||||
More information is provided to the district during the Bi-Directional Fraud Data API Implementation Process overview meeting with CCCTC Enabling Services. |
Bi-Directional Fraud Data API Operations
Panel | ||
---|---|---|
| ||
|
more information about Using Postman with the Fraud Data |
API. |
Rescinding a Fraud Report Via API
Getting the API Access Token
Panel | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
Non-technical Users: Click here to Getting Your API Access Token Using Postman |
With your API account created with the proper credentials 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.)
Code Block |
---|
curl --location --request POST 'PLACE_AUTHENTICATION_ENDPOINT_URL_HERE' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'username=PLACE_PLAINTEXT_USERNAME_HERE' \ --data-urlencode 'password=PLACE_PLAINTEXT_PASSWORD_HERE' \ --data-urlencode 'grant_type=password' \ --data-urlencode 'client_id=fraudReporting' |
Panel | ||||||
---|---|---|---|---|---|---|
| ||||||
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, Node, Java, etc. |
Getting Your Access Token Using Postman
Once Postman is installed and the Fraud Report Postman Collection and the Fraud Report Postman Environment 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 will automatically store the token as the Bearer
in the Authorization
head for all secured API requests.
Panel | ||||||
---|---|---|---|---|---|---|
| ||||||
A primary function of the API is to facilitate the process of automating the submission of suspected or identified fraudulent admission applications to the CCCTC for use in combating system-wide fraud. |
Submitting a Fraud Report
The schema defines the process for submitting fraud information to the CCCTC as the FraudReportSubmit operation. Specifications for this operation are documented in the CCCTC API Sandbox.
In general terms, the components of this operation are quite basic. The root of the FraudReportSubmit query operation is a mutation type object that has a required Input argument (FraudReportSubmitInput) where at least one input variable field must be provided and a custom payload response is defined (FraudReportSubmitPayload). For the majority of fraud report submissions, only the ccc Id (cccId) is truly needed, although additional input fields may also be added to the operation.
![(blue star)](/wiki/s/533672791/6452/ae7a1f07ba3926d9aae49dcfaed7cc806fb684d3/_/images/icons/emoticons/star_blue.png)
.
The FraudReportSubmit Operation
Below is an example of a basic FraudReportSubmit operation built with a template in the CCCTC API sandbox.
In the Operation section, the root mutation, FraudReportSubmit, has been selected with 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 in the adjacent screenshot).
|
Panel | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
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 |
Panel | ||||||
---|---|---|---|---|---|---|
| ||||||
Reminder: The user’s API account is configured with their default authorized MIS code(s), which is identified in the access token that becomes part of the request heading. The “appId” value entered must be a legitimate application corresponding to the authorized MIS code or the request will return an error. |
In this operation, the mutation has a required input argument (FraudReportSubmitInput) that specifies which data fields will be included in the submission.
Learn how to use an Input object type in a GraphQL mutation operation.
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). The default MIS code for a single college district is passed automatically in the token, so it does not need to be included as a variable in the input argument. |
The schema provides everything needed to construct and execute the FraudReportSubmit operation, including the required input argument, Input fields, and the payload response using an API dev tool such as cURL, PowerShell, Node, Python, Java, etc. Any of these development tools will provide the mechanism needed to make this API web request.
Panel | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
To export the FraudReportSubmit operation, or a variation of that template, as described in the schema in the CCCTC API sandbox, click the three dots in the Operation section to display the context menu for options. |
With a basic understanding of the operation and their API account with the appropriate credentials and configured attributes, an API user has everything they need to effectively format a proper web request using an application development tool such as cURL, Python, Node, PowerShell, etc.
The example below submits a formatted web request for a fraud report for application id (AppID) 34110
.
Code Block |
---|
curl --location --request POST 'PLACE_CCCTC_API_URL_HERE' --header 'Authorization: Bearer PLACE_AUTHORIZATION_TOKEN_HERE' --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}}}' |
Panel | ||||||
---|---|---|---|---|---|---|
| ||||||
Reminder: The access token code is entered as the |
Below is an example of a successful reply:
Code Block |
---|
{ "data": { "FraudReportSubmit": { "cccId": "AAA6198", "appId": 34110, "fraudType": "APPLICATION" } } } |
Panel | ||
---|---|---|
| ||
|
Receiving Fraud Notifications to a Staging Table
One objective of the fraud reporting project is to leverage SuperGlue and the College Adaptor to implement more automated processes for bi-directional sharing of fraud information between colleges. CCCTC is able to broadcast notifications of reported bad actors to any other colleges that have also received applications from the same CCCID.
When this happens, a new fraud-report is pushed to a dedicated staging table (for each college) via the SuperGlue College Adaptor. Each notification will identify the suspect CCCID and the application ID(s) (AppID), a timestamp for the fraud report, and the reporting college’s MIS code (reportedByMisCode).
Panel | ||||||
---|---|---|---|---|---|---|
| ||||||
Update Your College Adaptor for the Fraud Data API - Please see the Fraud Data API Implementation Process page for integration details. |
Querying Fraud Report Data
Colleges may query fraud data information for an authorized MIS code directly using the Fraud Data API. The schema specifies this operation as the FraudReportQuery type query, which is an interface for retrieving a FraudReport object consisting of a multi-field payload for an individual student and/or application.
The CCCTC API provides colleges the power to ask for exactly what they need, nothing more and nothing lesswhich fields they like be given to them. Such queries always return predictable results. Apps using this API are relatively fast because they control the amount of data they get , not the server(as opposed to the server returning additional unneeded data).
The FraudReportQuery Operation
The schema describes the FraudReportQuery as a Query type object that requires at least one of three different input-Object variations as part of the API calloperation. Each variation has a specific input argument (variable) that can be customized to retrieve all or some of the FraudReport data fields in the payload response. The input variations can be used alone or in combination with each other as part of the operation.
The three query variations are:
Use this operation… | that requires the… | to… |
---|---|---|
FraudReportQuery.withRecipientMisCode | “RecipientMisCode” field as the input variable | Return a list of FraudReport objects for a specified MIS code. |
FraudReportQuery.withAPPID | “AppId” field as the input variable | Return a FraudReport objects for a specific student Application. |
FraudReportQuery.withCCCID | “CCCID” field as the input variable | Return a FraudReport objects for a specific student CCCID. |
To better understand the syntax for these variable definitions, it's useful to learn the GraphQL schema language, explained in detail on the Schema page.
From Root, select Query > FraudReportQuery | Configure the Query Operation | Selectfields for the expected response. |
---|---|---|
Below is an example of the three query inputObject variations. | Below shows the “withCCCID” inputObject query selected. | Fields can be selected individually from the FraudReport object. |
The majority of multi-college districts will find the “withRecipientMisCode” query to be the most useful and commonly used variation for retrieving information on fraudulent applications submitted to one or more colleges in their district mis code.
Below is an example of a request using the FraudReportQuery:withRecipientMisCode query where one or more additional input variables are being used in addition to the “recipientMisCode”.
Code Block |
---|
curl --location --request POST 'PLACE_CCCTC_API_URL_HERE' \ --header 'Authorization: Bearer PLACE_AUTHORIZATION_TOKEN_HERE' \ --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 }\n }\n}","variables":{}}' |
This is an example of the expected response.
Code Block |
---|
{ "data": { "FraudReportQuery": { "withRecipientMisCode": [ { "submitTimestamp": "2022-10-07T21:15:37.000Z", "cccId": "AAA0002", "reportedByMisCode": "ZZ2", "recipientMisCode": "ZZ1", "appId": 4, "fraudType": "APPLICATION" } ] } } } |
Panel | ||||||
---|---|---|---|---|---|---|
| ||||||
Reminder: The user’s access token should be entered alongside the |
Panel | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
Below is an example of the FraudReportQuery:withRecipientMisCode operation configured in the CCCTC API sandbox. |
Panel | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
Reminder: The purpose of the Fraud Data API is to provide colleges the ability to integrate their internal systems in order to streamline their own fraud reporting processes. |
Copying & Exporting Query Operations
The fastest and easiest way to create the other query variations to use in Postman is to modify the existing file starting in the CCCTC sandbox. The process below outlines the steps for creating a new query entry to your Fraud Report Postman collection which will allow you to make an API call using a CCCID or App ID.
Panel | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
To export the FraudReportQuery operation, or a configuration of the template, as defined in the schema in the sandbox, click the three dots in the Operation section to display the context menu for options. |
bgColor | #FFF0B3 |
---|
Using Postman to Query Fraud Data
Rescinding a Fraud Report
The schema defines the process for rescinding fraud information to the CCCTC as the FraudReportRescind operation. Specifications for this operation are documented in the CCCTC API Sandbox.
In general terms, the components of this operation are quite basic. The root of the FraudReportRescind operation is a mutation type object that has a required Input argument (FraudReportRescindInput) where at least one input variable field must be provided and a custom payload response is defined (FraudReportRescindPayload). For the majority of fraud report rescission, only the ccc Id (cccId) is truly needed, although additional input fields may also be added to the operation.
The FraudReportRescind Operation
Below is an example of a basic FraudReportRescind operation built with a template in the CCCTC API sandbox.
With a basic understanding of the operation and their API account with the appropriate credentials and configured attributes, an API user has everything they need to effectively format a proper web request using an application development tool such as cURL, Python, Node, PowerShell, etc.
The example below submits a formatted web request for rescinding a fraud report for application id (AppID) 34110
.
Code Block |
---|
curl --location --request POST 'PLACE_CCCTC_API_URL_HERE'
--header 'Authorization: Bearer PLACE_AUTHORIZATION_TOKEN_HERE'
--header 'Content-Type: application/json'
--data-raw '{"query":"mutation FraudReportRescind($input: FraudReportRescindInput!) {\n FraudReportRescind(input: $input) {\n cccId\n appId\n }\n}\n","variables":{"input":{"appId":34110}}}' |
Panel | ||||||
---|---|---|---|---|---|---|
| ||||||
Reminder: The access token code is entered as the |
Below is an example of a successful reply:
Code Block |
---|
{
"data": {
"FraudReportRescind": {
"cccId": "AAA6198",
"appId": 34110
}
}
} |
Panel | ||
---|---|---|
| ||
|
Documentation & Supporting Resources
Panel | ||||||
---|---|---|---|---|---|---|
| ||||||
See more: SuperGlue API: Terminology & Data Element Descriptions |
Item | Description | File / Link |
---|---|---|
CCCTC API Sandbox | Fraud Data API Endpoint & Schema Documentation | See Enabling Services for the link |
GraphQL API Documentation | (Official) Online Introduction to GraphQL API | |
About GraphQL | CCCTC-based Introduction to GraphQL API | |
Postman Documentation | Introduction to Postman / Documentation | https://learning.postman.com/docs/getting-started/introduction/ |