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.

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://uc4apidocs.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 → Use this API call to retrieve specific mandates of an authority document. 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. Repeat the API call for each distinct mandate you intend to retrieve.

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” perPage and “page” 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” 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” 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” “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” id parameter with the actual elementID of the authority document retrieved in step #1 and replace “:controlId” controlId with the actual elementId of the common control to retrieve. Repeat the API call for each distinct common control you intend to retrieve.

Data Hierarchies

Certain data elements within an authority document can be arranged by hierarchy, such as Citations or Common Controls. In this case, the data element will contain a “hierarchyItems” object. The hierarchyItems object that will contain one hierarchicalParent object and an array of hierarchicalChildren objects (if applicable - some data elements will not have child objects). The hierarchicalParent object contains the elementId of the parent data element. The hierarchicalChildren object contains the elementId of the child data element (and the array may contain more than one child). The sortValue property contains the sort location of that data element beneath its parent citation (multiple data elements can have the same parent). Here is an example hierachyItems structure in the API response:

"hierarchyItems": [
{
"@id": "URL",
"@type": "string",
"elementId": "string",
"hierarchicalChildren": [
{
"@id": "URL",
"@type": "string",
"elementId": "string"
}
],
"hierarchicalParent": {
"@id": "URL",
"@type": "string",
"elementId": "string"
},
"sortValue": "string"
}
]

Furthermore, here is an illustration of the hierarchy using Citations as an example:

Image Removed

Converting from Legacy Services APIs to NextGen APIs

The legacy Services APIs all require you to set up a Shared Authority Document List and then you invoke the APIs by specifying the unique List ID or Authority Document ID. When retrieving an authority document, all of the Citations, Mandates and Common Controls would be returned in a single response. With Nextgen, an Authority Document list is not required. Instead, you can acquire all of the citations for an authority document in a single API, then all of the mandates for an authority document in another API, and finally all of the common controls for an authority document in another API.

The following is a mapping of the Legacy APIs to the NextGen APIs:

Function

Legacy Services API

NextGen API

Comment

Get Account Information

/my-account

/my-account

Returns information about the account.

Search for Authority Documents

Not Available

/authority-document?page=1&perPage=100&search=<value>

Returns documents containing the search term. Optionally remove the search parameter to retrieve all documents.

Retrieve Authority Document

/authority-document/:document-id/details

/authority-document/:id

Legacy returns the document metadata, all citations, all mandates and all controls. NextGen only returns the document metadata.

Search for Citations in a document

Not Available

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:

1. Retrieve all of the mandates for the authority document

2. 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

Returns citations containing the search term. Optionally remove the search parameter to retrieve all citations for the document.

Retrieve a specific Citation

Not Available

/authority-document/:id/citation/:citationId

NextGen can retrieve specific citations within a document

Search for Mandates in a document

Not Available

/authority-document/:id/mandate?page=1&perPage=100&search=<value>

Returns mandates containing the search term. Optionally remove the search parameter to retrieve all mandates for the document.

Retrieve a specific Mandate

Not Available

/authority-document/:id/mandate/:mandateId

NextGen can retrieve specific mandates within a document.

Search for Controls in a document

Not Available

/authority-document/:id/control?page=1&perPage=100&search=<value>

Returns controls containing the search term. Optionally remove the search parameter to retrieve all controls for the document.

Retrieve a specific Common Control

Not Available

• → 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:

"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/

NextGen can retrieve specific controls within a document

Retrieve all Common Controls for a list of Authority Documents

/cch-ad-list/:list-id/tracked-controls/details

/authority-document/:id/control?page=1&perPage=100

Legacy returns all common controls for all documents in the list. For NextGen, retrieve all of the controls for one document at a time.

Legacy Authority Document IDs

In the NextGen system, all authority documents have been assigned a new elementId value. However, you can still retrieve an authority document in NextGen using the legacy ID, for example:

• GET /authority-document/legacy/:id (where :id is the legacy CCH elementId)

Use the above endpoint to retrieve the NextGen elementId for that authority document, and then all subsequent API requests (to retrieve metadata, citations, mandates & controls) in Nextgen should be invoked using the NextGen elementId value.

Furthermore, when retrieving the metadata of an authority document from NextGen, the legacy CCH elementId will be returned as a property. For example:

• 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 the elementId of the parent data element

• hierarchicalChildren Array: Includes one or more child elements, each represented by their elementID

• sortValue Property: Defines the relative order of the data element within its parent.

Here is an example hierachyItems structure in the API response:

"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:

Image Added