API integration

REST API user guide

SS&C Blue Prism Document Automation provides a REST API for uploading image files (inbound) and retrieving the resulting JSON data (outbound). Refer to the Postman files and Swaggerhub docs referenced below for a more comprehensive explanation of our API.

Inbound API call sequence

Document Automation is a batch-based system with the ability to scale up and handle extremely high volumes. To submit files to Document Automation: 

1. Create a batch – The first API call is to create a batch. This is a POST request with a JSON payload that includes details such as the batch name:

   https://shreddr.captricity.com/api/v1/batch/

   This is a synchronous call that returns a JSON response with the unique Batch ID for the newly created batch. An example of the anticipated response is documented in our Swaggerhub documentation, which is listed below.

2. Add files to the batch – The next step is to make an API request for each file in the batch.

   This is a multipart/form-data POST request that includes the file to be uploaded, as well as a JSON payload that contains any relevant batch metadata:

   https://shreddr.captricity.com/api/v1/batch/<batch_id>/batch-file/

   The <batch_id> is the Batch ID from the response to the request you made in step 1. All files in a batch must have distinct file names. Using your Content Management ItemID (CMID) as the Batch File Name is one possibility. The CMID can included in the Batch File metadata if you prefer not to name the file that way. The Batch File metadata is a set of key:value pairs in JSON format that are associated with the Batch File and its digital output for the duration of the file's life.

   This is a synchronous call that returns a JSON response which contains the unique Batch File ID corresponding to the newly created Batch File.

   A batch should only contain a maximum of 1,000 pages. In a future release, submitting a batch with more than 1,000 pages will result in an error. The size of the batch determines the turnaround time.

3. Submit the batch – The batch submission is the final API call. There is no payload needed for this straightforward POST request:

   https://shreddr.captricity.com/api/v1/batch/<batch_id>/submit

   The <batch_id> is the Batch ID you received from the response to the request you made in step 1. You will receive a JSON response from this synchronous call verifying the submission of the batch.

Outbound API call sequence

Data is returned in cases. All the data extracted from a single Batch File that was sent for processing is contained in one case.

1. Pull a list of ready cases – The first API call you make retrieves a list of ready-to-export cases. This is a GET request with parameters specifying the workflow ID, the status of cases you want, and the limit on cases returned:

   https://shreddr.captricity.com/api/v1/cases?limit=<int>&status=ready%20to%20export&workflow_id=<id>

   For more information on how to find your workflow ID, see How to find your workflow ID. The limit parameter is an integer value, recommended to be set between 10 and 100.

   This is a synchronous call that returns a JSON response with a list of cases in the state specified by the batch status (up to but not exceeding the limit you set).

   As an alternative, Document Automation can send a pub/sub notice to a webhook you set up to alert you when cases are ready for export. For more information, see How to set up notifications.

   If you'd like us to set up a notification for you, please get in touch with Document Automation Technical Support.

2. Pull case data –This step involves making an API request to retrieve the case data for each case you wish to process. This is done using the list of cases you obtained from step 1 by iterating through the list of cases using the case IDs. This is a GET request with the parameter for the case ID in the URL:

   https://shreddr.captricity.com/api/v1/cases/<case_id>/data

   The <case_id> is from the list of case IDs you received in the response to the request you made in step 1. You will receive a JSON response with the case data structured according to the format described below.

3. Mark the case as exported – The final step is to make an API request to update the case's status to exported after processing the case and exporting the data successfully. This stops you from unintentionally processing the same cases more than once when you make the API request in step 1 looking for cases ready to export.

   This is a POST request with a list of case IDs in the JSON payload that you wish to update as exported:

   https://shreddr.captricity.com/api/v1/cases/update_statuses_to_exported

   The JSON payload would look like this:

   { "case_ids" : [ <case_id1>, <case_id2> ] }.

   You must explicitly add the following to the HEADERS for this step: { 'Content-Type' : 'application/json' }

Outbound case data structure

The data that is retrieved from a single Batch File is described by a case. The case data includes any Batch File metadata you supplied, as well as identifying information such as the case ID and batch ID.

The Forms array lists all pages that matched a template and those that didn't (Rejected pages). A forms array item will contain an unordered list of matched pages and their extracted data, grouped by the template.

Please see the description of each header to understand its contents:

Header	Description	Type
id	The case ID.	Integer
name	The case name, represents the submitted file name.	String
batch_file_metadata	The Metadata added during submission.	Array
batch_id	The Batch ID.	Integer
workflow_id	The account ID.	Integer
forms	Contains the case data. Each object in the array represents a template group.	Array
data	The digitized data in the template group. Each object in the array represents a field.	Array
pages	Contains the group of pages in the submitted file. Each object in the array represents a page.	Array
value	The capture data in the field.	String
field_name	The name of the field.	String
page_id	The page ID of the field in the data object which corresponds to the page_id in the pages object.	String
confidence	The OCR engine's confidence in the captured data.	Float
order	The page number in the submitted file.	Integer
template_name	The matched template name.	String

How to handle multiple instances of the same form in one file

When you submit many identical forms in a single file, all of those forms will repeatedly match the same template. The pages will be returned unordered in the Forms array. Each data object will have an associated page ID that points to the specific page object in the pages array from which the extracted data was obtained.

Status codes

Code	Description
200 OK	The request was successfully processed by Document Automation.
400 Forms Not Validated	Check the response message body for the specific error. Possible issues include adding an empty file, trying to upload the same file name to a batch twice, or adding too many pages to a batch.
403 Forbidden	The server is refusing to respond to the request. This is usually because you have an invalid API token for authentication.
404 Not Found	The requested resource was not found but could be available again in the future. Check the request URL.
413 File Too Large	The request was not accepted because the file has exceeded the maximum size limit of 50 MB.
499 60 Time Out Error	The request timed out after over one minute while requesting a single batch.
500 Internal Server Error	An internal error occurred at Document Automation. Please contact support staff or try again later.
503 Service Unavailable	Service outage.
504 Gateway Timeout	The request could not be completed in time. Try breaking it down into multiple smaller requests.

API token creation and deauthorization

How to create an API token

1. In the top right hand corner of the Document Automation platform, click the gear icon to reveal a drop-down menu, and then select Settings.

   

2. Click Services from the menu on the left of the page, and in the API Integrations section, select Create API Token.

   

3. Enter the Application Name, and save your changes by clicking Create.

   You have successfully created an API token for the Document Automation platform. You will receive an email containing your application's name, third party ID, secret key, and the API token you’ve created to interact with your account.

How to deauthorize an API token

1. In the top right hand corner of the Document Automation platform, click the gear icon to reveal a drop-down menu, and then select Settings.

   

2. Click Services from the menu on the left of the page, and in the API Integrations section, select Delete.

   

3. Confirm the action in the modal by selecting Yes, Deauthorize.

   

Workflow ID

All the data extracted from a single Batch File that was sent for processing is contained in one case.

The workflow ID is used to associate these cases to your profile. The workflow ID is required in the GET request to retrieve a list of ready-to-export cases:

https://shreddr.captricity.com/api/v1/cases?limit=<int>&status=<ready to export>&workflow_id=<id>

How to find your workflow ID

1. In the top right hand corner of the Document Automation platform, click the gear icon to reveal a drop-down menu, and then select Settings.

   

2. Click Workflow Options from the menu on the left of the page. The workflow ID displays at the top of the page.

   

API notifications

Document Automation can send a pub/sub notice to a webhook you set up to alert you when cases are ready for export. You may set up the notifications as an Organization Admin, or if you'd like us to set up a pub/sub notification for you, please contact Document Automation Technical Support.

How to set up API notifications

1. In the top right hand corner of the Document Automation platform, click the gear icon to reveal a drop-down menu, and then select Settings.

   

2. Click Services from the menu on the left of the page.

   

3. In the Notifications section, enter the destination you want the notification to be sent to in the Notification Endpoint/Hook Url field.

4. In the Custom Headers field, add the relevant key and value for authorization on the endpoint.

5. In the Subscribed to Events section, select the notifications you want to receive.

6. Click Save.