Introduction & Prerequisites
Purpose: This guide provides a step-by-step process for OEM Vendors to retrieve compliance-related data via APIs, ensuring each of your customers has a unique API Key.
Prerequisites:
OEM Vendor must have an active OEM Vendor Account in the Common Controls Hub
OEM Vendor must have customer CCH accounts created in the Partner Portal
OEM Vendor must have assigned and paid for a subscription plan and add-on to each customer account in the Partner Portal
OEM Vendor must have assigned a corresponding Authority Document List that matches the subscription on each customer account
API Access
API Key: OEM Vendors will make API calls on behalf of their customers to consume governance data supplied by Unified Compliance. Each customer added by an OEM Vendor 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 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.
When making API calls on behalf of your customer(s), set the unique API Key for each customer in an Authorization bearer token, ie: Authorization: Bearer {{API Key}}
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://cchapidocs.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 Lists
To 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.
GET /cch-ad-list/:list-id/authority-documents → 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 call.
GET /authority-document/:document-id/details → Use this API call to retrieve the metadata and all associated compliance data for a particular authority document. Replace “document-id” with the unique “id” of the authority document.
Use Case #3: Retrieve a list of Common Controls for a given authority document list
In 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 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.
/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.