2023:API Services (Service)

This article is about an older version of Grooper. Information may be out of date and UI elements may have changed.
2025	2024	2023.1	2023

You can perform Batch processing via REST API web calls by installing API Services.

About

The Grooper REST API (Application Programming Interface) allows for seamless integration between line of business solutions or custom-built software and your existing Grooper repositories and processes. A set of REST API methods allows users to push documents through Grooper Batch Processes and retrieve the results.

For example, using the Grooper REST API you can:

• Get information about a single Batch or all Batches
• Create a new Batch
• Delete a Batch
• Start or resume a Batch Process
• Get metadata for a specified Batch Folder.
• And more!

The first step in using the Grooper REST API is setting up an API endpoint for your 3rd party application to interact with a Grooper Repository. To do this, you will need to install a Grooper service in Grooper Config called API Services.

How To

Install the Grooper API Services

1. In Grooper config click the "Edit Services" button to open the "Service Manager" window.

2. From the Service Manager window click the "Install" button.
3. Select the desired repository from the "Repository" dropdown.
4. Choose API Services.
5. Click the "OK" button to confirm and open the "API Services" window.

6. From the "API Services" window add an API key for the API Keys property.
7. Copy the API endpoint URL from the URL property.
8. Ensure the Windows service user credentials are correct on the User Name and Password properties.
9. When finished configuring click the "Execute" button to confirm changes and close the "API Services" window.

10. In the "Service Manager" window, with the newly created "Grooper API Services" service installed and selected, click the "Start" button.
• FYI - If everything was configured properly, the "Status" of the service will change from "Stopped" to "Running".

Enable a Grooper API Test Endpoint

When using the Grooper REST API, you may find it helpful to test out certain API calls before you implement them. By turning the Enable Test Endpoint property on, you can expose a Grooper REST API testing interface which you can access by entering the API URL in a browser.

1. When editing an "API Services" service, in the "API Services" window, set the Enable Test Endpoint property to True.
2. Copy the API endpoint URL from the URL property.
3. When finished configuring click the "Execute" button to confirm changes and close the "API Services" window.

4. Paste the copied URL into a browser of your choice.

From here, you can view and test the various REST API methods available to process documents in Grooper.

Test Endpoints

Be aware this section is a work-in-progress. For more information about each API endpoint, set up a test endpoint and try it out for yourself!

Here, you will find more information about testing the Grooper API endpoints.

• Note, parameters you can pass with the request are in curly brackets.
• Example: You would replace {BatchID} with the GUID of a Batch.

Delete Batch

DELETE /api/v1/BatchProcessing/Batches/{BatchID}

Enter the GUID of a Batch and press "Execute". The Batch will be deleted in Grooper.

Get specific Batch info

GET /api/v1/BatchProcessing/Batches/{BatchID}

Enter the GUID of a Batch and press "Execute". You will receive a JSON response containing information about the Batch.

See below for an example response:

{
  "Id": "c548fe6c-ef2a-4054-ae80-86ee256f79d1",
  "Name": "2. GetBatchInfo",
  "NodeIndex": 0,
  "NumChildren": 2,
  "ParentId": "a4100c92-a1f2-45fe-a0b2-edc9105f8c47",
  "TypeName": "Grooper.Core.Batch",
  "Created": "/Date(1699383023767-0600)/",
  "CreatedBy": "company\\user",
  "Priority": 3,
  "RootFolderId": "e9145698-224a-44ca-9882-46e7be9227e7",
  "Status": 4,
  "StepNo": -1
}

Get all Batch info

GET /api/v1/BatchProcessing/Batches/All

Press "Execute" to return information about all production Batches in the Grooper Repository.

Get file stream

GET /api/v1/BatchProcessing/Files/{ItemId}/{FileName}

Enter the ID of the desired file and the filename and press "Execute". You will receive information about the file.

• In this example, {ItemId} was set to the GUID of a Batch Folder and {FileName} was set to the name of an attached PDF.
• The MIME type and file size for that file was returned.
• However, this could be used to return any number of things, including the full JSON for the Grooper.DocumentData.json file generated for a Batch Folder after it was extracted.

Get Content Type list

GET /api/v1/BatchProcessing/ContentTypes

Press "Execute" to return information about all Content Types (Content Models, Content Categories and Document Types) in your repository.

Example response:

{
  "Id": "ec23d7c3-6db5-4e7f-ad08-b7578e92636a",
  "Name": "7060 Content Model",
  "NodeIndex": 0,
  "NumChildren": 2,
  "ParentId": "c92afd6f-17be-446d-9da4-37cb259fd533",
  "TypeName": "Grooper.Core.ContentModel",
  "Children": [
    {
      "Id": "ab1b1090-3cb7-47fc-a791-542db5a68f72",
      "Name": "7060 Doc Type",
      "NodeIndex": 1,
      "NumChildren": 0,
      "ParentId": "ec23d7c3-6db5-4e7f-ad08-b7578e92636a",
      "TypeName": "Grooper.Core.DocumentType"
    }
  ]
}

Get folder info for a specific folder

GET /api/v1/BatchProcessing/Folders/{FolderId}

Enter the GUID of a Batch Folder and press "Execute". You will return information about the folder. Notably, its name and "DataIsValid" value are often of use.

Example JSON response if the folder exists:

{
  "Id": "0379d4ba-d67c-4ecc-ba82-f61117bc898c",
  "Name": "Doc Type (1)",
  "NodeIndex": 0,
  "NumChildren": 1,
  "ParentId": "3f1139e4-da29-488e-bed8-f1f381b483c3",
  "TypeName": "Grooper.Core.BatchFolder",
  "DataIsValid": false
}

Example JSON response if an invalid GUID is provided (i.e. the object whose GUID you summited is not a folder):

{
  "Message": "Object with ID '74b475a5-fc58-4e6d-b737-b94f6d0aed4c' is not a Batch Folder."
}

Example JSON response if the folder is not found (i.e. the folder has been deleted or never existed in the first place):

{
  "Message": "Batch Folder with ID '79aa46db-cc9c-4ee0-b15d-0c369b603910' not found."
}

Get info for all folders at a specific level

GET /api/v1/BatchProcessing/Folders/{ParentId}/Folders?Level={Level}

Enter the GUID for any parent folder (such as a Batch's root folder's GUID) and the folder level you want to search. Then, press "Execute". You will receive information about all folders at that level, including their GUID id, names, index, "DataIsValid" values and more.

Example JSON response:

[
  {
    "Id": "5256e88d-d032-4d24-ab94-edc43056bca2",
    "Name": "1 (1)",
    "NodeIndex": 0,
    "NumChildren": 1,
    "ParentId": "d754077b-9903-4e79-93da-4ececb3aabaf",
    "TypeName": "Grooper.Core.BatchFolder",
    "DataIsValid": false
  },
  {
    "Id": "7bb14095-28a5-4195-b675-29fafb39eee3",
    "Name": "2 (2)",
    "NodeIndex": 1,
    "NumChildren": 0,
    "ParentId": "d754077b-9903-4e79-93da-4ececb3aabaf",
    "TypeName": "Grooper.Core.BatchFolder",
    "DataIsValid": false
  }
]

Get extracted metadata for a specific document (single instance fields only)

GET api/v1/BatchProcessing/Folders/{FolderId}/Metadata

Enter the GUID of a Batch Folder and press "Execute". You will return two things:

1. The Batch Folder's "ContentTypeId" value (This is its Document Type's GUID).
2. A list of key-value pairs for each single instance field extracted for the document.
   • For example, if you extracted a value (000-00-0000) for a "Social Sec Num" field you would see something like the following:

"FieldValues": [
  {
    "Key": "Social Sec Num",
    "Value": "000-00-0000"
  }
]

• Note: "Key" names for Data Fields in single instance Data Sections are returned using dot notation (e.g. "DataSectionName.DataFieldName")

Example JSON response:

{
  "ContentTypeId": "baf3853e-9642-4c90-9811-a5c361ab9e2a",
  "FieldValues": [
    {
      "Key": "Section1.a",
      "Value": "Handy"
    }
  ]
}

Get page info for a specific folder

GET /api/v1/BatchProcessing/Folders/{ParentId}/Pages?Recursive={Recursive}

Enter the GUID for a Batch Folder and either "true" or "false" to indicate if the search is recursive. Then, press "Execute"

• For the recursive parameter, enter:
  • True if you want all pages from all levels below the Batch Folder
  • False if you want only pages at the given Batch Folder level.

Example when "Recursive" is False.

• Here, there was only a single page at the selected Batch Folder's level.

Example JSON response when "Recursive is False.

[
  {
    "Id": "afa2699d-6f71-40d1-9a33-0a3a8a233772",
    "Name": "Page 2",
    "NodeIndex": 1,
    "NumChildren": 0,
    "ParentId": "7d7984d4-ac9f-4742-9dfe-31e96311e403",
    "TypeName": "Grooper.Core.BatchPage",
    "DisplayImage": null,
    "Height": 11,
    "OriginalPageNo": 0,
    "PixelFormat": 0,
    "PrimaryImage": "Grooper.Image.pdf",
    "Width": 8.5
  }
]

Example when "Recursive" is True.

• Here, there are two pages. One is at level 1 and the other at level 2.

Example JSON response when "Recursive is True.

[
  {
    "Id": "a5502938-e76e-40e4-a8eb-8f4e44651617",
    "Name": "Page 1",
    "NodeIndex": 0,
    "NumChildren": 0,
    "ParentId": "74df0ea0-6225-4cc8-ae19-316906c3d017",
    "TypeName": "Grooper.Core.BatchPage",
    "DisplayImage": null,
    "Height": 11,
    "OriginalPageNo": 0,
    "PixelFormat": 0,
    "PrimaryImage": "Grooper.Image.pdf",
    "Width": 8.5
  },
  {
    "Id": "afa2699d-6f71-40d1-9a33-0a3a8a233772",
    "Name": "Page 2",
    "NodeIndex": 1,
    "NumChildren": 0,
    "ParentId": "7d7984d4-ac9f-4742-9dfe-31e96311e403",
    "TypeName": "Grooper.Core.BatchPage",
    "DisplayImage": null,
    "Height": 11,
    "OriginalPageNo": 0,
    "PixelFormat": 0,
    "PrimaryImage": "Grooper.Image.pdf",
    "Width": 8.5
  }
]