Hyperscience API Overview

• Updated on Jul 17, 2025
• Published on Sep 17, 2024
• 2 minute(s) read

Sunsetting API v4
We have sunset API v4 with the release of Hyperscience v38. If you are using API v4, migrate to v5 as soon as possible.
To learn more about our API deprecation policy, see our API documentation.

The Hyperscience API uses REST API endpoints and returns responses in JSON. The API supports a variety of use cases, including:

• Submitting and retrieving files.
• Submitting and retrieving cases.
• Retrieving documents, pages, fields, tables, and data types.
• Generating reports.

To learn more about the API, see our API documentation.

Authentication

Only users with the API Access permission can make API calls. To make API calls, you need to authenticate your user. There are two ways to authenticate, depending on your instance’s type:

• For on-premise / private cloud instances, see Managing API Tokens.
• For SaaS instances, see API Access for SaaS Instances.

Files submission

The Submission Creation endpoint gives you the option to submit files seamlessly through the API. To submit files, you need to make a POST request to /api/v5/submissions. This endpoint provides three ways of submitting files:

• By submitting the image files into the Submission Creation endpoint as multipart/form-data via the file parameter.
• By passing Base64-encoded file data in JSON format to the Submission Creation endpoint as multipart/json via the files parameter.
• By referencing the location of the files in the Submission Creation endpoint via the file or files parameter. The application will retrieve them on its own. In this case, you would use application/x-www-form-urlencode encoding, or you would use application/json encoding with file_url in the files parameter.

Accepted file types

The API supports submitting files in the following formats:

• .zip, .pdf, .xps, .tif, .tiff, .jpg, .jpeg, .png, .gif

Note that if the ZIP file is password-protected or the images are encrypted, an error will appear.
Support for other file types is possible but with limitations. For more information, contact your Hyperscience representative.

Parameters

The only required parameter for processing files through the API is:

• file for multipart/form-data and application/x-www-form-urlencode encoding.
• files for application/json encoding.

It is also possible to add optional parameters to your submissions for your convenience. To learn more about parameters, see our API documentation.

JSON outputs and objects

All API responses are in JSON format. Our main API data structure is an object. Within its structure, each of the objects contain arrays and other objects.

You can use the JSON outputs from each of the objects to:

• Integrate with connectors such as Bizagi and UiPath. Bizagi is only available for on-prem / private cloud instances.
  • To learn more about these integrations, see Bizagi and UiPath Notifier.
• Connect to other systems downstream.

OpenAPI specifications

OpenAPI specifications (f.k.a. Swagger specifications) provide standardized ways to interact with REST APIs and provide information about them. These standardizations make it easier for developers to create integrations with APIs in the languages of their choosing. To learn more about OpenAPI specifications, see Swagger's OpenAPI Specification page.

Hyperscience has built OpenAPI specifications for the following endpoints:

• Submissions
• Create Submissions

You can download these specifications from our API documentation.

For more information on our OpenAPI specifications, see MuleSoft's Anypoint Exchange.