Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents
stylenone

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.

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: 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://cchapidocsuc4apidocs.unifiedcompliance.com

Use Cases

The following are some typical use cases for acquiring content via the APIs.

Use Case #1: Retrieve Account information

To retrieve account information, 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

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 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/:id/mandate/:mandateId → Replace the “:id” parameter with the actual elementID of the authority document retrieved in step #1 and replace “:mandateId” with the actual elementID of the mandate retrieved in step #3. Use this API call to retrieve a specific mandate of an authority document.

Use Case #4: Retrieve an Authority Document and all associated Common Controls

Call 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 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/common-control?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 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 → Replace the “:id” parameter with the actual elementID of the authority document retrieved in step #1 and replace “:controlId” with the actual elementID of the common control retrieved in step #3. Use this API call to retrieve a specific common control of an authority document.