Document API

This article describes API calls available for Documents configuration:

  • /api/document: Allows retrieving, creating, updating, and deleting Documents.
  • /api/document_category: Allows retrieving Documents assigned to Categories, assigning a Document to a Category, and removing a Document from a Category.
  • /api/document_element: Allows retrieving Documents assigned to Elements, assigning a Document to an Element, and removing a Document from an Element.
  • /api/document_folder: Allows retrieving Documents assigned to Folders, assigning a Document to a Folder, and removing a Document from a Folder.
  • /api/document_group: Allows retrieving Documents assigned to Groups, assign a Document to a Group, and removing a Document from a Group.
  • /api/document_type: Allows retrieving, creating, updating, and deleting Document Types.

Prerequisites:

Table of contents:

  1. Access Admin > System > API Toolkit
  2. Configure Documents
    1. Retrieve Documents
    2. Create Document
    3. Update Document
    4. Delete Document
  3. Configure Document Categories
    1. Retrieve Document Categories
    2. Assign Document to Category
    3. Remove Document From Category
  4. Configure Document Elements
    1. Retrieve Document Elements
    2. Assign Document to Element
    3. Remove Document From Element
  5. Configure Document Folders
    1. Retrieve Document Folders
    2. Assign Document to Folder
    3. Remove Document From Group
  6. Configure Document Types
    1. Retrieve Document Types
    2. Create Document Type
    3. Update Document Type
    4. Delete Document Type

1. Access Admin > System > API Toolkit

2. Configure Documents

2.1. Retrieve Documents

The GET request to /api/document returns all Documents.

  1. Item: document
  2. Method: GET
  3. Optionally, filter the result by:
    • ID: Enter the Document ID
    • element: Enter the element ID
    • document_type: Enter the ID of the Document Type
    • created_by_user: Enter the ID of the User
    • is_global_document:
      • 'Y': Returns all Global Document
      • 'N': Returns all Documents that are not global
  4. Enter an API Token
  5. [Run request]

Example Response 

 {
  "documents": [
    {
      "id": 1,
      "document_type": 2,
      "name": "Jump Start Guide for Regular Users",
      "created_by_user": 19,
      "revision_date": "2018-11-30 10:59:02",
      "source_type": "External Link",
      "external_url": "http://help.metricinsights.com/m/Jump_Start_Guide_for__Regular_Users",
      "is_global_document": "Yes",
      "share_with_admin": "No",
      "share_with_power": "No",
      "share_with_regular": "No"
    },
    {
      "id": 2,
      "document_type": 2,
      "name": "Jump Start Guide for Administrators",
      "created_by_user": 19,
      "revision_date": "2019-01-28 14:22:49",
      "source_type": "External Link",
      "external_url": "http://help.metricinsights.com/m/Jump_Start_Guide_for_Administrators",
      "is_global_document": "Yes",
      "share_with_admin": "No",
      "share_with_power": "No",
      "share_with_regular": "No"
     }
  ]
}

Fields Description

Parameter Name Value Type Description
id integer The ID of the Document
document_type integer The ID of the Document Type
name string The Document name
created_by_user integer
 The ID of the User who created the Document
revision_date string The Revision Date of the Document
source_type string
 The Document's Source type. Supported values: "External Link", "PDF File".
external_url
 string
 The Document's External URL 
is_global_document string
 Whether or not the Document is global. Supported values: "Y", "N".
share_with_admin
 string Whether or not the Document is shared with Admins. Supported values: "Yes", "No".
share_with_power
 string
 Whether or not the Document is shared with Power Users. Supported values: "Yes", "No".
share_with_regular
 string
 Whether or not the Document is shared with Regular Users. Supported values: "Yes", "No".

2.2. Create Document

The POST request to /api/document creates a new Document.

  1. Item: document
  2. Method: POST
  3. ID: Enter the ID of an existing Document
  4. Select JSON request and modify the request body by providing the following values:
    • document_type: The ID of the Document Type
    • name: The name of the Document
    • share_with_admin: Whether or not the Document is shared with Admins
      • Supported values: "Yes", "No"
    • share_with_power: Whether or not the Document is shared with Power Users
      • Supported values: "Yes", "No"
    • share_with_regular: Whether or not the Document is shared with Regular Users
      • Supported values: "Yes", "No"
    • revision_date: The Revision Date of the Document
    • is_global_document: Whether or not the Document is global
      • Supported values: "Y", "N"
    • source_type: The Document's Source type.
      • Supported values: "External Link", "PDF File"
    • external_url: The Document's External URL
      • Leave this field empty if the source_type is set to "PDF File"
  5. Enter an API Token
  6. [Run request]

2.3. Update Document

The PUT request to /api/document/id/<ID> updates the selected Document.

  1. Item: document
  2. Method: PUT
  3. Enter the ID of the Document that needs to be updated
  4. Select JSON request and provide values for the following parameters:
    • id: The ID of the Document
    • document_type: The ID of the Document Type
    • name: The name of the Document
    • share_with_admin: Whether or not the Document is shared with Admins
      • Supported values: "Yes", "No"
    • share_with_power: Whether or not the Document is shared with Power Users
      • Supported values: "Yes", "No"
    • share_with_regular: Whether or not the Document is shared with Regular Users
      • Supported values: "Yes", "No"
    • revision_date: The Revision Date of the Document
    • is_global_document: Whether or not the Document is global
      • Supported values: "Y", "N"
    • source_type: The Document's Source type.
      • Supported values: "External Link", "PDF File"
    • external_url: The Document's External URL
      • Leave this field empty if the source_type is set to "PDF File"
    • created_by_user: The ID of the User who created the Document
  5. Enter an API Token
  6. [Run request]

2.4. Delete Document

The DELETE request to /api/document/id/<ID> deletes the Document.

  1. Item: document
  2. Method: DELETE
  3. ID: Enter the ID of the Document that needs to be deleted
  4. Enter an API Token
  5. [Run request]

3. Configure Document Categories

3.1. Retrieve Document Categories

The GET request to /api/document_category returns all Categories that the Documents are assigned to.

  1. Item: document_category
  2. Method: GET
  3. Optionally, filter the result by:
    • ID: The ID of the document_category data entry
    • document: Enter the ID of the Document
  4. Enter an API Token
  5. [Run request]

Example Response 

{
  "document_categories": [
    {
      "id": 1,
      "document": 4,
      "category": 187
    },
    {
      "id": 2,
      "document": 21,
      "category": 213
    },
    {
      "id": 3,
      "document": 24,
      "category": 123
    }
  ]
}

Fields Description

Parameter Name Value Type Description
id integer The ID of the document_category data entry
document integer
 The ID of the Document
category integer
 The ID of the Category

3.2. Assign Document to Category

The POST request to /api/document_category assigns Document to a Category.

  1. Item: document
  2. Method: POST
  3. ID: Enter the ID of an existing document_category data entry
  4. Select JSON request and modify the request body by providing the following values:
    • document: The ID of the Document
    • category: The ID of the Category
  5. Enter an API Token
  6. [Run request]

3.3. Remove Document From Category

The DELETE request to /api/document_category/id/<ID> removes Category from the Document.

  1. Item: document_category
  2. Method: DELETE
  3. ID: Enter the ID of the document_category data entry that needs to be deleted
  4. Enter an API Token
  5. [Run request]

4. Configure Document Elements

4.1. Retrieve Document Elements

The GET request to /api/document_element returns all Elements that the Documents are assigned to.

  1. Item: document_element
  2. Method: GET
  3. Optionally, filter the result by:
    • ID: The ID of the document_element data entry
    • document: Enter the ID of the Document
  4. Enter an API Token
  5. [Run request]

Example Response 

{
  "document_elements": [
    {
      "id": 1,
      "document": 1,
      "element": 1439
    },
    {
      "id": 7,
      "document": 8,
      "element": 1523
    }
  ]
}

Fields Description

Parameter Name Value Type Description
id integer The ID of the document_element data entry
document integer
 The ID of the Document
element integer
 The ID of the Element

4.2. Assign Document to Element

The POST request to /api/document_element assigns Document to an Element.

  1. Item: document_element
  2. Method: POST
  3. ID: Enter the ID of an existing document_element data entry
  4. Select JSON request and modify the request body by providing the following values:
    • document: The ID of the Document
    • element: The ID of the Element
  5. Enter an API Token
  6. [Run request]

4.3. Remove Document From Element

The DELETE request to /api/document_element/id/<ID> removes Document from the selected Element.

  1. Item: document_element
  2. Method: DELETE
  3. ID: Enter the ID of the document_element data entry that needs to be deleted
  4. Enter an API Token
  5. [Run request]

5. Configure Document Folders

5.1. Retrieve Document Folders

The GET request to /api/document_folder returns all Folders that the Documents are assigned to.

  1. Item: document_folder
  2. Method: GET
  3. Optionally, filter the result by:
    • ID: The ID of the document_folder data entry
    • document: Enter the ID of the Document
  4. Enter an API Token
  5. [Run request]

Example Response 

{
  "document_folders": [
    {
      "id": 1,
      "document": 21,
      "folder": 209
    },
    {
      "id": 2,
      "document": 25,
      "folder": 279
    }
  ]
}

Fields Description

Parameter Name Value Type Description
id integer The ID of the document_folder data entry
document integer
 The ID of the Document
folder integer
 The ID of the Folder

5.2. Assign Document to Folder

The POST request to /api/document_folder assigns Document to the selected Folder.

  1. Item: document_folder
  2. Method: POST
  3. ID: Enter the ID of an existing document_folder data entry
  4. Select JSON request and modify the request body by providing the following values:
    • document: The ID of the Document
    • folder: The ID of the Folder
  5. Enter an API Token
  6. [Run request]

5.3. Remove Document From Folder

The DELETE request to /api/document_folder/id/<ID> removes Document from the selected Folder.

  1. Item: document_folder
  2. Method: DELETE
  3. ID: Enter the ID of the document_folder data entry that needs to be deleted
  4. Enter an API Token
  5. [Run request]

6. Configure Document Groups

6.1. Retrieve Document Groups

The GET request to /api/document_group returns all Groups that the Documents are assigned to.

  1. Item: document_group
  2. Method: GET
  3. Optionally, filter the result by:
    • ID: The ID of the document_group data entry
    • document: Enter the ID of the Document
  4. Enter an API Token
  5. [Run request]

Example Response 

{
  "document_groups": [
    {
      "id": 1,
      "document": 13,
      "group": 17
    },
    {
      "id": 5,
      "document": 25,
      "group": 63
    }
  ]
}

Fields Description

Parameter Name Value Type Description
id integer The ID of the document_group data entry
document integer
 The ID of the Document
group integer
 The ID of the Group

6.2. Assign Document to Group

The POST request to /api/document_group assigns Document to the selected Group.

  1. Item: document_group
  2. Method: POST
  3. ID: Enter the ID of an existing document_group data entry
  4. Select JSON request and modify the request body by providing the following values:
    • document: The ID of the Document
    • group: The ID of the Group
  5. Enter an API Token
  6. [Run request]

6.3. Remove Document From Group

The DELETE request to /api/document_group/id/<ID> removes Document from the selected Group.

  1. Item: document_group
  2. Method: DELETE
  3. ID: Enter the ID of the document_group data entry that needs to be deleted
  4. Enter an API Token
  5. [Run request]

7. Configure Document Types

7.1. Retrieve Document Types

The GET request to /api/document_type returns all Document Types.

  1. Item: document_type
  2. Method: GET
  3. Enter an API Token
  4. [Run request]

Example Response 

{
  "document_types": [
    {
      "id": 4,
      "name": "Case Study & White Paper"
    },
    {
      "id": 3,
      "name": "Video"
    },
    {
      "id": 1,
      "name": "Release Note"
    },
    {
      "id": 2,
      "name": "User Guide"
    }
  ]
}

Fields Description

Parameter Name Value Type Description
id integer The ID of the Document Type
name string The name of the Document Type

7.2. Create Document Type

The POST request to /api/document_type creates a new Document Type.

  1. Item: document_type
  2. Method: POST
  3. ID: Enter the ID of an existing Document Type
  4. Select JSON request and modify the request body by providing the following values:
    • name: The name of the Document Type
  5. Enter an API Token
  6. [Run request]

7.3. Update Document Type

The PUT request to /api/document_type/id/<ID> updates the selected Document Type.

  1. Item: document_type
  2. Method: PUT
  3. Enter the ID of the Document Type that needs to be updated
  4. Select JSON request and provide values for the following parameters:
    • id: The ID of the Document Type
    • name: The new name of the Document Type
  5. Enter an API Token
  6. [Run request]

7.4. Delete Document Type

The DELETE request to /api/document_type/id/<ID> deletes the Document Type.

  1. Item: document_type
  2. Method: DELETE
  3. ID: Enter the ID of the Document Type that needs to be deleted
  4. Enter an API Token
  5. [Run request]