This article aims to describe the features and functionality of the ProcessUnity Global Risk Exchange (GRX) API V2 and provide a guide for customers wishing to leverage the API for integration or reporting purposes.
As additional functionality is released, information in this article will be updated along with updates to the OpenAPI Spec. Please see the API V2 Change Log article for delivered and planned releases information.
API Getting Started
The ProcessUnity GRX V2 APIs allow customers to create and automate workflows to support your Third Party Risk Management program.
Here are the high-level quick-start steps for using the GRX API:
- Explore the technical documentation for information about what endpoints and fields are available on our OpenAPI Spec
- Please contact your GRX representative to provide your demo or production environment credentials.
- Verify your credentials with the built-in OpenAPI auth GET TOKEN
- Experience the data available with OpenAPI’s “TRY” functionality
- Review your current TPRM process and decide what level of integration and automation is best for your business
- Need more info? Keep reading below to get answers to all your API-related questions
API Access & Information
OpenAPI Spec
ProcessUnity GRX uses OpenAPI Specification (fka Swagger RESTful API Documentation Specification) to document our REST APIs.
View the OpenAPI Spec for the production GRX API.
View the OpenAPI Spec for the demo / test GRX API.
API Authentication
At ProcessUnity GRX, we are all about keeping your data secure. To access the GRX APIs, you must have a GRX account and credentials with the appropriate permissions.
API Credentials
Please contact your ProcessUnity GRX representative to generate API V2 credentials in either Demo or Production. An encrypted email will then send you a client ID and client secret associated with your company account.
If you are interested in "end-to-end" integration functionality and do not currently have access to an account in the Demo environment, one will be created for you at this time. While you can experience production-like functionality in the demo, we do not have real company and assessment information in it. It has been seeded with “fake” company records and completed assessments to enable end-to-end testing.
If you are primarily interested in "reporting" functionality, Demo environment access is not needed as it will be better for you to leverage the real data in Production.
NOTE: Currently, the GRX Portal does not offer a self-serve option for creating API V2 credentials. That functionality is planned for a future release.
Your API credentials carry many privileges, so be sure to keep them secure. Do not share your secret API credentials in publicly accessible areas such as GitHub, client-side code, etc.
API Tokens
You need an API token to make a call to the GRX REST API. We set up the OAuth 2.0 API authentication mechanism to provision API tokens for you. Once you have received your API credentials, verify them with the built-in OpenAPI auth GET TOKEN.
Tokens are valid for 10 hours and should be reused by the same application. Token end times are encoded into the token and can be checked before using the token so a new one can be generated. Decoding the token can be done with a standard library to view the “issued at” (iat) and the “expiration” (exp) timestamps.
Otherwise, once a token expires, the call to the endpoint will fail authentication. If you generate a new token before the expiration has passed, the previous token will still work through its expiration timestamp.
API Scopes
All scopes assigned to the account will be enabled when provisioning a token. When you decide what level of integration you want, we can update your account to have only the necessary scopes to limit data access. Data that is not within one of the selected scopes will not be accessible to the API token.
We use Auth0 for our authentication provider. Here is their high-level documentation. More specifically, this link has an example about how to pass in the client id and secret to retrieve the token and an example is provided below.
curl -s --request POST \
--url https://cybergrx-production.us.auth0.com/oauth/token \
--header 'content-type: application/json' \
--data '{"client_id":"$client_id","client_secret":"$client_secret","audience":https://api.cybergrx.com,"grant_type":"client_credentials"}'
In order to see which scopes are required to call an endpoint, refer to the below table:
| API Endpoint | Required Scope |
| Company Endpoints | |
| GET /v2/company/companies | read:company |
| GET /v2/company/companies/{company_id} | read:company |
| Portfolio Endpoints | |
| GET /v2/portfolio/third-parties | read:portfolio |
| POST /v2/portfolio/third-parties | write:portfolio |
| GET /v2/portfolio/third-parties/{company_id} | read:portfolio |
| PUT /v2/portfolio/third-parties/{company_id} | write:portfolio |
| DELETE /v2/portfolio/third-parties/{company_id} | write:portfolio |
| PATCH /v2/portfolio/third-parties/{company_id} | write:portfolio/tags |
| POST /v2/portfolio/third-parties/{company_id}/requests | write:portfolio |
| GET /v2/portfolio/tags | read:portfolio/tags |
| Collection Endpoints | |
| GET /v2/portfolio/third-parties/{company_id}/impact-questionnaire | read:questionnaire/impact |
| PUT /v2/portfolio/third-parties/{company_id}/impact-questionnaire | write:questionnaire/impact |
| GET /v2/collection/impact-questionnaire | read:questionnaire/impact |
| Reporting Endpoints | |
| GET /v2/portfolio/third-parties/{company_id}/risk-profile | read:portfolio |
| GET /v2/portfolio/third-parties/{company_id}/risk-navigator/{framework_id}/summary | read:portfolio-findings |
| GET /v2/portfolio/third-parties/{company_id}/risk-navigator/{framework_id} | read:portfolio-findings |
| GET /v2/reporting/frameworks | read:frameworks |
| GET /v2/reporting/frameworks/{framework_id} | read:frameworks |
| GET /v2/reporting/framework-controls/{framework_id} | read:frameworks |
| GET /v2/reporting/priority-third-parties/{framework_id} | read:portfolio-findings |
| POST /v2/reporting/exports | write:exports |
| GET /v2/reporting/exports/{export_id} | read:exports |
| GET /v2/reporting/exports/{export_id}/download | read:exports |
Release Versions
Beta Release
Endpoints tagged as Beta are available for customer use and testing. Please feel free to try them out and provide feedback for future enhancements! These endpoints have been vetted and should be final. Depending on the specific endpoint(s) complexity, they may stay in Beta mode for varying lengths to ensure they are stable before moving them to the Generally Available areas.
Once an endpoint is released to Beta, changes to the schema that would be “breaking” – field renames, field type changes, schema reorganizations, etc.– are highly unlikely. However, we still reserve the right to do those, if necessary, with notice via our release notes process.
Alpha Release
Endpoints tagged as Alpha are not available for customer access at this time. You can go over the schema and the planned functionality to get a sneak peek at future functionality, but these endpoints are still under review, and we may likely introduce breaking changes as they undergo our review process. Please submit suggestions or feedback on these endpoints, as they are undergoing active development!
We do not recommend developing against these endpoints while they are in Alpha.
Internal
Endpoints tagged as Internal are not customer use. They are for integration between the Global Risk Exchange and the TPRM Workflow.
Base URL
The GRX REST API base URL is as follows:
- Production: https://api.cybergrx.com
- Demo/Test: https://demo-api.cybergrx.com
The GRX authentication base URL is different since we leverage AuthO 2.0 to manage authentication, token creation, and scope permissions.
- Production: https://auth.portal.cybergrx.com/oauth/token
- Demo/Test: https://auth.demo.cybergrx.com/oauth/token
All requests to the GRX API must use TLS protocol version 1.2 for the request to be successfully sent.
Time Zone
All dates and time zones available via the API are presented in Coordinated Universal Time (UTC). You may notice a difference in the day or timestamp in the GRX UI because that display is localized based on your set time zone.
Standard libraries are available for converting the UTC dates to local time before presenting them to your users.
Pagination
We have one style of pagination you will see in the endpoint to get the list of companies in your third party portfolio.
In the response, “total” represents the total number of results available, even if they have not all been returned.
Setting the “limit” parameter allows you to control the number of records returned in the response. ProcessUnity GRX sets a maximum.
If you turn the “limit” up and the “total” still shows a number higher than the limit, you can iterate through the result set by calling the endpoint again and incrementing the “offset.”
Filtering
Several of the endpoints for the GRX API allow for filtering. Filtering is optional.
For multiple values of the same filter type, append the filter name and selected values with “&” separating them. Do not use comma-delimited lists or new lines for multiple values.
Example: Tags=123&Tags=345&Tags=XXX
Rate Limits
The ProcessUnity GRX API is rate-limited. Users can make up to 5 requests a second. Information about rate limits will be returned in the response headers.
API Features & Functionality
API Overview
The ProcessUnity GRX V2 APIs allow members to automate reporting and workflows to support your Third-Party Risk Management program.
Interact with the Exchange
Search for companies in the ProcessUnity Global Risk Exchange (GRX)
Search for companies in the GRX Exchange by name or domain. Optionally filter the results by Country Code. Provides public company firmographics, third-party relationship flags, and available assessment information to identify a company on the exchange.
The main data point to save is the company_id—this is the GRX ID for a company, which is used as the identifier for that company in all subsequent API calls.
The domain is the best way to search. If you search by name and domain, the system actually does two separate searches and presents the mixed results back to you ranked on match strength. If you want to completely automate adding a new company to your third-party portfolio, pass in both name and domain and take the top result by setting the limit to 1.
Want to know more about using Company Search? Check out this article for more information.
View a company in the ProcessUnity Global Risk Exchange
GET /v2/company/companies/{company_id}
Suppose you already have a GRX company_id stored. In that case, you can fetch that company to view public-level company firmographics, third-party relationship flags, and available assessment information for a company on the exchange.
Use this endpoint if any other endpoint gives you an error on the company_id to ensure you have a correct GRX ID saved. Also, use this to pull back address information on a company if needed since the GET TP endpoint does not return the company’s address.
Manage Your Third-Party Portfolio
Add a company in the ProcessUnity Global Risk Exchange to your third-party portfolio
PUT /v2/portfolio/third-parties/{company_id}
You have found your vendor on the ProcessUnity Global Risk Exchange. (And maybe they already have a completed attested assessment—awesome!) Now, it is a simple step to use the company_id returned in the company search to add that company to your third-party portfolio to unlock additional risk information.
Add a company to the ProcessUnity Global Risk Exchange and to your third party portfolio
POST /v2/portfolio/third-parties
If you have searched for a company on the GRX Exchange and have not found the vendor you are looking for, you can request to add a new company to the GRX Exchange and your third-party portfolio with this endpoint. It requires the company name, domain, and country ISO2 code. If the remaining address elements are known, they are strongly encouraged to be provided, as they feed into our company deduplication and enrichment efforts and will help ensure the correct company you are looking for is added to the Exchange.
Remove a company from your third-party portfolio
DELETE /v2/portfolio/third-parties/{company_id}
Important Note – With the February 2025 release of the Global Risk Exchange, this endpoint will ‘Archive’ third parties in your third-party portfolio and not actually remove them from the portfolio.
Added the wrong company? No longer doing business with a vendor? Declutter your third-party portfolio by archiving that company; simply pass in the company_id to this endpoint, and that company will automatically be set to a status of ‘Archived’ in your third-party portfolio.
If you try to call the GET /v2/portfolio/third-parties/{company_id} again with the same company_id, it would indicate that the third party is not in your portfolio and no results will be returned (In this case, the third party is in your portfolio with a status of ‘Archived’) If you used that company_id to do the more general GET /v2/company/companies/{company_id}, you should see the “in_third_party_portfolio” set to true.
In a future release of API V3, the name of the endpoint will be updated to reflect the archiving of a third party and a status of ‘Active’ and ‘Archived’ status will be available when viewing companies in your third party portfolio.
NOTE: If you have any requests for the third party, all those requests will be cancelled when a third party is ’Archived’. You will lose access to data from previously completed requests and authorized assessments as well. Even if you ’Unarchive’ the third party in the third-party portfolio, you will need to re-request access to view attested information.
View the companies in your third-party portfolio
GET /v2/portfolio/third-parties
Now that you are done with all the searching, adding, and archiving of companies, let’s see who is currently in your third-party portfolio. View the companies in your third-party portfolio, which is filterable by several elements such as Tags, Inherent Risk, and Custom ID. Provides third-party relationship metadata, request and authorization status, available questionnaires and dates, and high-level risk information for analysis and prioritization.
To understand how to interpret the data provided on a third party, read the Access Your Third Party Risk Information section below.
View the tags associated with companies in your third-party portfolio
View the tags currently associated with companies in your third-party portfolio. Use this information to filter and find third parties via GET /v2/portfolio/third-parties
View a company in your third-party portfolio
GET /v2/portfolio/third-parties/{company_id}
View a company in your third party portfolio by its GRX Company ID. Provides third party relationship metadata, request and authorization status, available questionnaires and dates, and high level risk information for analysis and prioritization.
To understand how to interpret the data provided on a third party, read the Access Your Third Party Risk Information section below.
Update information on a company in your third-party portfolio
PATCH /v2/portfolio/third-parties/{company_id}
Update information on a company in your third-party portfolio by GRX ID. Manage tags associated with a third party. Set or update the custom id associated with a third party. Use this information to filter and find third parties via GET /v2/portfolio/third-parties
Request a third party to complete and authorize a GRX questionnaire
POST /v2/portfolio/third-parties/{company_id}/requests
Request a third party to complete and authorize access to the specified GRX questionnaire with the option for validation. A third party contact must also be provided.
Before placing a request for an assessment, check if that vendor already has an attested assessment on the Exchange. If you order that tier or lower, the vendor only has to authorize the release of the completed assessment and results to you. If you order a higher tier or if the vendor does not have any assessment on the Exchange yet, that vendor must first complete the assessment in order to authorize the release of the results to you.
NOTE: It is possible that the contact you provided will not be the one returned in the GET TP call. The contact provided at this time is the “Assessment Owner” if possible, or the "Account Admin". This is the user determined by ProcessUnity GRX to be the contact most likely to be able to action on your request.
Want to know more about the assessment tiers? Check out this article for more information.
Check to see if a request has been fulfilled
Once a request for an assessment has been placed on a company in your Third Party portfolio, you can use either the GET /v2/portfolio/third-parties/{company_id} or GET /v2/portfolio/third-parties to check if that request has been fulfilled.
There are two milestones that must be completed for a request to be fulfilled. The company must authorize you to view their data and the company must complete and attest the questionnaire tier. If you requested validation, then a third activity also needs to be completed where the company uploads their evidence documents and ProcessUnity GRX Assessors review the evidence to make determinations if it substantiates the vendor’s claims.
At a higher level, the field “available_in_portfolio” will show you when you have access to an Attested questionnaire or a Validated questionnaire and a request has been fulfilled.
For more detailed information, the section “request_status” provides information about that status and the authorization for access to the data while the section “data_available_in_exchange” provides information about the state of completed and validated questionnaires. While sometimes the "latest_questionnaire" data may match the "data_available_in_exchange", when they do not match the "latest_questionnaire" section is displaying the status of In Progress assessments.
Request_access_status
- Requested: The company has not yet responded to your request.
- Approved: The company has authorized you to view their attested data for the questionnaire tier and validation requested. This field and status alone does not signify that the request has been fulfilled yet as the company may still need to finish the questionnaire and validation may need to be completed.
- Denied: The company has rejected your request to view their attested data for the questionnaire tier and validation requested.
Request_progress
- the request progress field is associated with the "latest_questionnaire" section and will show you the status of your first request for an assessment as well as ongoing refreshes by the third party
Data_available_in_exchange
- If the questionnaire_name and validation are at the same level or a lower tier as the “request_status” questionnaire_name and validation, you know that the vendor already has a completed assessment on the Exchange and you are only waiting for “request_access_status” to be updated to Approved
- If the questionnaire_name and validation are at a higher than the “request_status” section questionnaire_name and validation, then the vendor must complete the additional questions and validation process (if requested). Once that is done you will see the new tier and dates reflected here since this section always shows the highest available tier on the Exchange.
- If this section is null, then the vendor has no questionnaire completed on the Exchange and must finish answering all the questions for the requested tier and attest for that information to populate for this section.
- If you requested a validated questionnaire, it is possible that you will see a questionnaire with an attestation date prior to the validation being completed
Access Your Third-Party Risk Information
Third-Party Risk Profile
Once a company has been added to your third-party portfolio, you can use either the GET /v2/portfolio/third-parties/{company_id} or GET /v2/portfolio/third-parties/{company_id}/risk-profile to understand the risk profile for a company.
The “available_in_portfolio” field indicates at a glance what risk data is available to you at your third party portfolio level.
Inherent_Profile | Predictive Profile | Attested Profile | Validated Profile
- An Inherent Profile is set when predictive data is not available for the company and when there is no request for an assessment, or when there is a request that is not yet approved and completed.
- A Predictive Profile is set when predictive data is available for the company and when there is no request for an assessment, or when there is a request that is not yet approved and completed.
- An Attested Profile is set when the third party approves the request and attests the associated assessment. For non-validated assessments, the request is considered complete at this point. For assessments with validation pending, this status is displayed when the request is in the validation process but validation has not yet been completed.
- A Validated Profile is set when the third party has approved the request and attested the assessment associated with that request and an assessor has completed the validation process and is only applicable to assessments with validation
Inherent Risk Profile
As soon as a company is added to your third party portfolio, you will have access to Inherent Risk data, powered by the GRX “Auto Inherent Risk” feature. You can use the GET /v2/portfolio/third-parties/{company_id}/risk-profile to understand the Inherent Risk profile for a company.
Inherent Risk describes risk when all cybersecurity controls fail or are missing. It provides a worst-case scenario view for engaging with a third party.
There is a section of the company response “inherent_risk” that has the following fields:
inherent_risk_score
- Returns a number from 0.00 to 100.00
- This score is not static and is subject to change daily based on a variety of inputs
- The score is provided to allow custom thresholds for classification if you would prefer to calculate your own bands
inherent_risk_rating
- Returns a string to provide the GRX interpretation of the inherent_risk_score
- The rating provided is the GRX standard classification - GRX is currently using a 5 band of Critical, High, Medium, Low and Nominal
impact_status
- Returns “CONFIRMED” if you have completed the Impact Questionnaire for the third party
- Returns “UNCONFIRMED” if you have not yet completed the Impact Questionnaire for the third party and are instead seeing the score and rating based on our “Auto Inherent Risk” feature
What to do next?
If “available_in_portfolio” = Inherent_Profile
You can complete the Impact Questionnaire to fine tune the Inherent Risk and ensure it is reflecting how you do business with and rely on that vendor.
- Currently selected answers (selected_answer_value) or the AIR answers (auto_impact_response_value) to the Impact Questionnaire for a Third Party can be viewed via GET /v2/portfolio/third-parties/{company_id}/impact-questionnaire
- Answers to the Impact Questionnaire for a Third Party can be set or updated via PUT /v2/portfolio/third-parties/{company_id}/impact-questionnaire
You can wait for Predictive to be generated for that company. Predictive results are typically available within 2 weeks. See the section “Predictive Risk Profile” for more info.
Depending on the inherent risk of the vendor and your business process, you can request an assessment and wait for it to be completed and authorized to get access to Attested information from the vendor. See the section “Request a third party complete and authorize a GRX questionnaire” for more info.
Want to know more about inherent risk? Check out this article for more information.
Predictive Risk Profile
As soon as an existing company on the GRX Exchange is added to your third party portfolio, you will have access to Predictive Residual Risk data, powered by the GRX Predictive Model. You can use the GET /v2/portfolio/third-parties/{company_id}/risk-profile to understand the Predictive Risk profile for a company.
If you added a new company to the GRX Exchange and to your third party portfolio, the Predictive data may take a while to be generated. Predictive results are typically available within 2 weeks.
Residual Risk describes risk when cybersecurity controls are in place and is what remains of Inherent Risk after the controls assessment answers predict what is mitigated. The score is provided to allow custom thresholds for classification.
There is a section of the response “residual_risk” that has the following fields:
predictive_residual_risk_score
- Returns a number from 0.00 to 100.00
- This score is not static and is subject to change daily based on a variety of inputs
predictive_risk_reduction_percentage
- Returns a number from 0.00 to 100.00 and is the percentage reduction between the Inherent Risk and the Predictive Residual Risk
- This score is not static and is subject to change daily based on a variety of inputs
predictive_risk_reduction_rating
- The rating of how well the residual risk reduced inherent risk
- Values: EXCELLENT, VERY_GOOD, GOOD, FAIR, POOR, VERY_POOR, INSUFFICIENT_INHERENT_RISK
What to do next?
If “available_in_portfolio” = Predictive_Profile
You can review the summary of the Predictive Assessment results that support the higher level Predictive Residual Risk score. See the section “Assessment Results” for instructions on how to pull and understand the summary Predictive Results.
You can dig deeper into the details of the Predictive Assessment results that support the higher level Predictive Residual Risk score. See the section “Assessment Results” for instructions on how to pull and understand the detailed Predictive Results.
Depending on the inherent risk of the vendor and your business process, you can request an assessment and wait for it to be completed and authorized to get access to Attested information from the vendor. See the section “Request a third party complete and authorize a ProcessUnity GRX questionnaire” for more info.
Want to know more about residual risk? Check out this article for more information.
Attested Risk Profile
After you have requested an assessment and that vendor has completed and authorized you to view the assessment, you will have access to Attested Residual Risk data. You can use the GET /v2/portfolio/third-parties/{company_id}/risk-profile to understand the Attested Risk profile for a company.
Residual Risk describes risk when cybersecurity controls are in place and is what remains of Inherent Risk after the controls assessment answers tell us what is mitigated. The score is provided to allow custom thresholds for classification.
There is a section of the response “residual_risk” that has the following fields:
attested_residual_risk_score
- Returns a number from 0.00 to 100.00
- This score is not static and is subject to change daily based on a variety of inputs
attested_risk_reduction_percentage
- Returns a number from 0.00 to 100.00 and is the percentage reduction between the Inherent Risk and the Attested Residual Risk
- This score is not static and is subject to change daily based on a variety of inputs
attested_risk_reduction_rating
- The rating of how well the residual risk reduced inherent risk
- Values: EXCELLENT, VERY_GOOD, GOOD, FAIR, POOR, VERY_POOR, INSUFFICIENT_INHERENT_RISK
What to do next?
If “available_in_portfolio” = Attested_Profile
You can review the summary of the Attested Assessment results that support the higher-level Attested Residual Risk score. See the section “Assessment Results” for instructions on how to pull and understand the summary Attested Results.
You can dig deeper into the details of the Attested Assessment results that support the higher-level Attested Residual Risk score. See the section “Assessment Results” for instructions on how to pull and understand the detailed Attested Results.
Want to know more about residual risk? Check out this article for more information.
Validated Risk Profile
A validated profile will only ever be available if you had requested a validated assessment for that vendor. This profile will be available after the company has completed and attested the assessment, submitted evidence documentation, and the GRX Assessors reviewed the documentation and made determinations if the evidence validates the critical controls.
NOTE: Validation results do not influence the Attested Residual Risk data.
What to do next?
If “available_in_portfolio” = Validated_Profile
At this time you can pull the detailed “Assessment Results” again and additional fields will be populated. See the section “Assessment Results” for instructions on how to pull and understand the detailed Validation Results.
Assessment Results
Assessment Results - Data Available
GET /v2/portfolio/third-parties/{company_id}/risk-profile
View the attestation dates for the assessment and validation data that is visible to you for a company in your third party portfolio. These dates are associated with the assessment data pulled via the Summary or Detailed Assessment Results.
Assessment Results - Summary
GET /v2/portfolio/third-parties/{company_id}/risk-navigator/{framework_id}/summary
View summary assessment and risk information for a company in your third party portfolio for a specified framework. Review predictive or attested assessment results at the overall and group levels, depending on what data is authorized and available in portfolio. This endpoint will return the highest level of data available to be viewed as the default.
If “available_in_portfolio” = Inherent_Profile: Assessment data does not yet exist to be pulled via this API.
If “available_in_portfolio” = Predictive_Profile: Predictive assessment data exists and can be pulled via this API. Predictive data is the default response when it is the highest level of data available.
If “available_in_portfolio” = Attested_Profile: Attested assessment data exists and can be pulled via this API. Attested data is the default response when it is the highest level of data available.
If “available_in_portfolio” = Validated_Profile: Validated and Attested assessment data exists and can be pulled via this API. Validated data is the default response when it is the highest level of data available.
After deciding what framework to use, you will get the following assessment results information:
Assessment Results - Details
GET /v2/portfolio/third-parties/{company_id}/risk-navigator/{framework_id}
View detailed assessment and risk information for a company in your third party portfolio for a specified framework. Review predictive or attested assessment results in detail at the question level, depending on what data is authorized and available in portfolio, in order to analyze and prioritize gaps for risk mitigation. This endpoint will return the highest level of data available to be viewed as the default.
If “available_in_portfolio” = Inherent_Profile: Assessment data does not yet exist to be pulled via this API.
If “available_in_portfolio” = Predictive_Profile: Predictive assessment data exists and can be pulled via this API. Predictive data is the default response when it is the highest level of data available.
If “available_in_portfolio” = Attested_Profile: Attested assessment data exists and can be pulled via this API. Attested data is the default response when it is the highest level of data available. When attested controls are available, results will be returned for attested findings and supplemented with predictive findings when attested not available. (Returning a combination of attested and predictive findings for an ‘Attested Profile’ is a new feature as of February 2025)
If “available_in_portfolio” = Validated_Profile: Validated and Attested assessment data exists and can be pulled via this API. Validated data is the default response when it is the highest level of data available.
After deciding what framework to use, you will get the following assessment results information:
Every framework selected has one or more framework controls. The results are organized by the framework controls first with information about each one along with their score. Each framework control is supported with information on the list of GRX controls, and associated information, mapped to the framework control.
framework_control_number
- The unique control number for each framework
framework_control_name
- The framework specific control name, label or identifier
framework_control_description
- The framework specific control description to elaborate on what is being considered and evaluated
framework_control_group
- The framework specific group that the framework control is associated with for organization and filtering purposes
framework_control_score
- Weighted average score that is derived from the mapped GRX question(s) score(s) and represents how well a framework control is covered
framework_control_rank
- Rank that is associated with the framework control score and represents how well a framework control is covered
- values: VERY_POOR, POOR, FAIR, GOOD, VERY_GOOD
cybergrx_controls
- This section shows the list of GRX controls that were mapped to the framework control
- There could be 0, 1 or many GRX controls mapped depending on the context of the framework control
question_number
- This is the unique identifier for the GRX question on the assessment
question_name
- This is the high-level name / topic for the GRX question on the assessment
question_type
- Shows the relationship of the GRX question to the associated framework control
- Primary – indicates one to one matching of the GRX question to the Framework control
- Supporting – indicates that the GRX question will typically cover an aspect of the Framework control but not the control in its entirety
question_prompt
- This is the full question text that was displayed to the third party as they were answering the GRX assessment
question_score_basis
- Describes the means by which the scores were derived for each control. Values may be any of the following:
- Attested Metrics – the control score is based on Tier 1 answers and includes strength, coverage, and timeliness fidelity
- Attested Control – the control score is based on Tier 2 answers at a Yes/No fidelity
- Attested NA – the control was answered with a 'Not Applicable' response
- Predictive Control – the control score is a predicted value
- Unavailable – neither predictive or attested results are available for this control
question_score
- The attested or predicted effectiveness of the GRX control
- Tier 1 assessments range from 0-100
- Tier 2 assessments are credited with 0 for "No" answers and 85 for "Yes" answers
- Predictive outcomes range from 0-85
- The score will be null if the control answer is "NA" or Unavailable
answer_state
- Answer states for the GRX question presented to the vendor
- Yes – the company confirmed they do have the GRX control in place
- No – the company confirmed they do not have the GRX control in place
- NA (Not Applicable) – the company confirmed that the GRX control was not applicable to them
- Unavailable – The company did not have this control in the version of the questionnaire they answered
- Empty / Null – If calculation_basis = Predictive_Profile this field will be null since Predictive assessments do not include an answer state from the company
question_comment
- Third Party comments on the GRX Control if provided. In February 2025, this was updated to show the most recent comment rather than the oldest comment.
- If the answer_state = NA, then comments are required to be provided by the company
- If calculation_basis = Predictive_Profile, this field will be null since Predictive assessments do not include comments from the company
validation_status
- Describes the validation state for each mapped GRX Control
- Not Applicable – control is not a GRX 60 Critical Control; or validation was not included with your request; or if calculation_basis = Predictive_Profile
- Pending Review – GRX Analysts are in the process of evaluating evidence provided by the Third Party; will only show if “available_in_portfolio” = Attested_Profile and validation was included with your request
- Not Validated – evidence provided was inadequate to determine if the control was in place; will only be an option if “available_in_portfolio” = Validated_Profile
- Validated – all of the validation criteria has been met for this control; will only be an option if “available_in_portfolio” = Validated_Profile
- Not Selected – GRX 60 Critical Control that the third party stated they do not perform (i.e. 'No' answer state), therefore validation is not required; will only be an option if “available_in_portfolio” = Validated_Profile
finding_severity
- Finding severity refers to the identification of a security, policy, or management weakness at the control level. The determination severity is based on a combination of the control’s effectiveness and classification, with those deemed Critical or instrumental in preventing MITRE ATT&CK scenarios given extra scrutiny
- High, Medium or Low
- Empty /null – no finding severity for the given control
maximum_impact
- Maximum impact refers to the highest level of impact that a failed control would have on your business, based on how you answered the Impact Questions. If the Impact Questions are Unconfirmed, then the Auto Impact Responses will be used.
mitigation
- Provides suggested approaches, technologies, or standards that help improve the control, establish best practices, and reduce the risk of compromise
evidence_type
- Describes the type of evidence that was provided by the third party to validate a control
- Written – evidence in a narrative documentation format. Examples include policies, procedures, emails, etc.
- Demonstrated – any type of primary, technical evidence. Examples include actual live demonstrations, screenshots, exports, etc.
- Verbal – any evidence which is self-attested. Examples include discussions, written notes or explanations, previously completed self-assessments, etc.
- No Evidence – evidence was not provided by the third party
- Not Applicable – control is not a GRX 60 Critical Control; or validation was not included with your request
metrics
- This section shows the list of metrics associated with the control
- There are three metrics available for each control
metric_category
- The category for the metric. Categories include Coverage, Strength, and Timeliness.
metric_number
- The unique identifier for the metric
content_name
- The high level name for the metric
content_prompt
- The question text for the metric that is displayed to the third party
options
- This section shows the list of possible answer options for each metric
option
- Text of the answer option presented to the third party
answered
- The response to the answer option. Returns ‘true’ or ‘false’
order
- Number representing the order the responses are displayed to the third party
Want to know more about assessment results? Check out this article for more information.
Get the list of available frameworks
Get the list of available GRX Frameworks, Standard Frameworks, Threat Profiles, and Industry Profiles. If applicable, Licensed Content and Custom Frameworks will also be returned. Store the framework_id to be used as the input parameter for the Risk Navigator or the Portfolio Risk Findings.
Don’t know where to start? We recommend using our “ProcessUnity Cyber Risk Questionnaire” framework as it returns the entire GRX Assessment organized by Risk Domains.
Want to know more about frameworks? Check out this article for more information.
Download a Third Party Risk Information Report
If your risk analysts prefer to review the risk information on a third party in report format, endpoints are available to retrieve the spreadsheet report for a company’s predictive or attested assessment.
Request the Report
Use the company_id and selected framework_id to request the export of the spreadsheet version of the Assessment Report. This report can be downloaded for either a “PREDICTIVE_PROFILE” or an “ATTESTED_PROFILE”.
The report provided is the same file from the Third Party -> Risk Profile tab -> Risk Navigator "Download". This report includes Third Party meta data, Inherent and Residual Risk data, and detailed Assessment data with scoring and findings.
If you do not include "report_type", it will default to "EXCEL".
Check if the Report is Ready
GET /v2/reporting/exports/{export_id}
Use the export_id to check the status of the report until it is "Ready". At that time, you will also get the url for the download.
Retrieve the Report
GET /v2/reporting/exports/{export_id}/download
Use the export_id to download the report. The download will work only once. If not retrieved, the download link will expire after 30 days.