Table of Contents |
---|
|
|
Introduction & Prerequisites
Purpose: This guide provides a step-by-step process for OEM Vendors Partners to retrieve compliance-related data via APIs, ensuring each of your customers has a unique API Key.
Prerequisites:
OEM Vendor Partner must have an active OEM Vendor Partner Account in the Common Controls Hub
OEM Vendor Partner must have customer CCH accounts created in the Partner Portal
OEM Vendor Partner must have assigned and paid for a subscription plan and add-on to each customer account in the Partner Portal
OEM Vendor Partner must have assigned a corresponding Authority Document List that matches the subscription on each customer account
References
https://unifiedcompliance.atlassian.net/wiki/x/CgDln
Legacy (CCH) OEM Vendor Partner - API Quick Start Guide
Related PRDs
/wiki/spaces/ICP/pages/2598764545
/wiki/spaces/ICP/pages/2656436242
/wiki/spaces/ICP/pages/2656436227
Flows
Expand | ||
---|---|---|
| ||
API Access
API Key: OEM Vendors Partners will make API calls on behalf of their customers to consume governance data supplied by Unified Compliance. Each customer added by an OEM Vendor Partner will be assigned their own unique API Key and that API Key must be used for authorization when making API calls on behalf of that customer. You can retrieve the API Key for a customer on the Customers page of the Partner Portal.
NOTE: OEM Vendors Partners can make API calls themselves using their own/unique API Key. Login to the Common Controls Hub and navigate to Settings and then API Manager where you can create your own API Key.
Info |
---|
When making API calls on behalf of your customer(s), set the unique API Key for each customer in an Authorization bearer token, ie: |
Full API Documentation
For a complete list of available APIs, the production URL endpoints, and example API responses, refer to the Postman Documentation here: https://cchapidocsuc4apidocs.unifiedcompliance.com
Use Cases
The following are some typical use cases for acquiring content via the APIs.
Use Case #1: Retrieve Account information
and Authority Document ListsTo retrieve account information and the authority document lists associated with the account, call the following API:
GET /my-account → The API Key passed in the header will be used to retrieve the account it belongs to.
Use Case #2: Retrieve an Authority Document and all associated Citations
and Common Controls.In order to retrieve an authority document, it must be contained in a shared Authority Document List. Lists are created and maintained in the Common Controls Hub under Workspace → Common Controls.
Call the following 3 APIs to retrieve an authority document:
GET /my-account → The API Key passed in the header will be used to retrieve the account it belongs to. Use this API call to retrieve all of the authority document lists created under the account. The response will contain an ad_lists array that contains all of the authority document lists. Each list will be returned as an object, and the “id” property will contain the unique ID for that list. Utilize that “id” to invoke the next API call.
Call the following 4 APIs to retrieve an authority document and its associated citations
GET /authority-document?page=1&perPage=100&search=NIST → Start by searching for the authority document you are looking for. Alternatively, if you already know the unique elementID of the authority document, then skip to step #2. This endpoint will return all of the authority documents that contain the text “NIST”. The response will be a paginated list, so utilize the “perPage” and “page” parameters to retrieve more pages of data. Once you have located the desired document, note down the elementID and proceed to step #2.
GET /authority-document/:id → Replace the “:id” parameter with the actual elementID of the document retrieved in step #1. Use this API call to retrieve all of the metadata for the authority document.
GET /authority-document/:id/citation?page=1&perPage=100&search → Replace the “:id” parameter with the actual elementID of the document retrieved in step #1. Use this API call to retrieve a paginated list of citations for that authority document. Utilize the “perPage” and “page” parameters to retrieve more pages of data, and, utilize the search parameter to find specific citations that contain the search value in their “guidance” and/or “reference” properties. Note down the elementID value(s) for specific citations to retrieve.
GET /authority-document/:id/citation/:citationId → Replace the “:id” parameter with the actual elementID of the authority document retrieved in step #1 and replace “:citationId” with the actual elementID of the citation retrieved in step #3. Use this API call to retrieve a specific citation of an authority document.
Use Case #3: Retrieve an Authority Document and all associated Mandates
Call the following 4 APIs to retrieve an authority document and its associated mandates.
GET /authority-document?page=1&perPage=100&search=NIST → Start by searching for the authority document you are looking for. Alternatively, if you already know the unique elementID of the authority document, then skip to step #2. This endpoint will return all of the authority documents that contain the text “NIST”. The response will be a paginated list, so utilize the “perPage” and “page” parameters to retrieve more pages of data. Once you have located the desired document, note down the elementID and proceed to step #2.
GET /authority-document/:id → Replace the “:id” parameter with the actual elementID of the document retrieved in step #1. Use this API call to retrieve all of the authority documents in the list specified by “list-id” (replace this with the “id” from above). The response will contain an array of authority document objects where the “id” property contains the unique ID for each document returned. Utilize that “id” to invoke the next API callthe metadata for the authority document.
GET /authority-document/:id/mandate?page=1&perPage=100&search → Replace the “:id” parameter with the actual elementID of the document retrieved in step #1. Use this API call to retrieve a paginated list of mandates for that authority document. Utilize the “perPage” and “page” parameters to retrieve more pages of data, and, utilize the search parameter to find specific mandates that contain the search value. Note down the elementID value(s) for specific mandates to retrieve.
GET /authority-document/:document-id/detailsmandate/:mandateId → Use this API call to retrieve the metadata and all associated compliance data for a particular specific mandates of an authority document. Replace “document-the “:id” parameter with the unique “id” actual elementId of the authority document retrieved in step #1 and replace “:mandateId” with the actual elementId of the mandate retrieved in step #3. Repeat the API call for each distinct mandate you intend to retrieve.
Use Case
#3#4: Retrieve
a list ofan Authority Document and all associated Common Controls
for a given authority document listIn order to retrieve a list of common controls for a given authority document list, the list must be shared. Lists are created and maintained in the Common Controls Hub under Workspace → Common Controls.
Call the following 2 APIs to retrieve a list of Common Controls for a given authority document list:
/my-account → The API Key passed in the header will be used to retrieve the account it belongs toCall the following 4 APIs to retrieve an authority document and its associated common controls.
GET /authority-document?page=1&perPage=100&search=NIST → Start by searching for the authority document you are looking for. Alternatively, if you already know the unique
elementID
of the authority document, then skip to step #2. This endpoint will return all of the authority documents that contain the text “NIST”. The response will be a paginated list, so utilize theperPage
andpage
parameters to retrieve more pages of data. Once you have located the desired document, note down theelementID
and proceed to step #2.GET /authority-document/:id → Replace the
:id
parameter with the actualelementID
of the document retrieved in step #1. Use this API call to retrieve all of the authority document lists created under the account. The response will contain an ad_lists array that contains all of the authority document lists. Each list will be returned as an object, and the “id” property will contain the unique ID for that list. Utilize that “id” to invoke the next API call./cch-ad-list/:list-id/tracked-controls/details → Use this API call to retrieve all of the Common Controls in the list specified by “list-id” (replace this with the “id” from above). The response will contain all of the distinct common controls across all of the authority documents contained in that list.metadata for the authority document.GET /authority-document/:id/common-control?page=1&perPage=100&search → Replace the
:id
parameter with the actualelementID
of the document retrieved in step #1. Use this API call to retrieve a paginated list of common controls for that authority document. Utilize the “perPage
” and “page
” parameters to retrieve more pages of data, and, utilize the search parameter to find specific common controls that contain the search value. Note down the elementId value(s) for specific common controls to retrieve.GET /authority-document/:id/common-control/:controlId → Use this API call to retrieve specific common controls of an authority document. Replace the
:id
parameter with the actualelementID
of the authority document retrieved in step #1 and replace:controlId
with the actual elementId of the common control to retrieve. Repeat the API call for each distinct common control you intend to retrieve.
Use Case #5: Retrieve just the Citations that have Mandates
For a given authority document, if you want to retrieve just the Citations that are associated with a Mandate, then that can be achieved by:
Retrieve all of the mandates for the authority document
Retrieve each of the citations for the authority document using the primaryCitation.elementId in the mandates response
Thus, start by calling the Mandates paginated list endpoint for the authority document:
GET /authority-document/:id/mandate?page=1&perPage=100 → Replace the: id parameter with the elementId of the authority document. For each mandate returned, grab the elementId of the primaryCitation object. Here is an example:
Code Block |
---|
"primaryCitation": {
"@id": "https://feature-qa-c.api.app.unifiedcompliance.com/api/authority-document/67/citation/6248",
"@type": "Citation",
"elementId": "6248",
"reference": "AC-2(2) ¶ 1"
}, |
Next, for each mandate returned above, retrieve the associated citation using the primaryCitation.elementId value:
GET /authority-document/:id/citation/:citationId→ Replace the :id parameter with the elementId of the authority document. Replace the :citationId parameter with the
elementID
of the primary citation retrieved above.
Data Hierarchies
Certain data elements within an Authority Document, such as Citations or Common Controls, are organized hierarchically. These hierarchies are presented in the API using th hierarchyItems
object. The structure includes:
hierarchicalParent
Object: Contains theelementId
of the parent data elementhierarchicalChildren
Array: Includes one or more child elements, each represented by theirelementID
sortValue
Property: Defines the relative order of the data element within its parent.
Here is an example hierachyItems
structure in the API response:
Code Block | ||
---|---|---|
| ||
"hierarchyItems": [
{
"@id": "URL",
"@type": "string",
"elementId": "string",
"hierarchicalChildren": [
{
"@id": "URL",
"@type": "string",
"elementId": "string"
}
],
"hierarchicalParent": {
"@id": "URL",
"@type": "string",
"elementId": "string"
},
"sortValue": "string"
}
] |
Here is an illustration of the hierarchy using Citations as an example: